@effected/yaml 0.8.0 → 0.10.0

package/README.md

@@ -8,7 +8,7 @@
 Zero-dependency YAML 1.2 parsing, editing, formatting and linting expressed as Effect schemas and pure functions. Parse a single document or a multi-document stream into plain values or an offset-preserving AST, resolve anchors and aliases, read and preserve per-node comments, strip comments, compute byte-minimal edits, format, modify by path, walk a document as a `Stream` of AST events or positioned tokens, lint it against a rule catalog with surgical autofix, and decode straight into a validated domain schema.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 beta. Packages graduate to
+> development against a single pinned Effect v4 prerelease. Packages graduate to
 > `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
 > exactly the ones the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
@@ -126,7 +126,9 @@ console.log(YamlFormat.formatToString(source, undefined, YamlFormattingOptions.m
 // port: 3000
 ```
 
-Comments are readable as data too. `YamlScalar`, `YamlMap`, `YamlSeq` and `YamlPair` each carry `commentBefore` (the own-line block above the node), `comment` (strictly the trailing comment on the node's own line) and `spaceBefore` (a blank line came first); `YamlDocument` adds `commentAfter` for a trailing block, and `YamlVisitor` tags every `Comment` event with `placement: "leading" | "trailing"`.
+Comments are readable as data too. Every node class — `YamlScalar`, `YamlMap`, `YamlSeq` and `YamlAlias` — carries `commentBefore` (the own-line block above the node), `comment` (strictly the trailing comment on the node's own line) and `spaceBefore` (a blank line came first). `YamlPair` carries none of them: an entry is its `key` and its `value`, and the comments live on those two nodes. `YamlDocument` uses the same two names as the nodes do, `commentBefore` for a header block sitting ahead of a `---` marker and `comment` for the trailing block, and `YamlVisitor` tags every `Comment` event with `placement: "leading" | "trailing"`.
+
+Which node a comment lands on follows one rule. An own-line comment above an entry leads that entry's key node, setting `commentBefore` and — when a blank line came first — `spaceBefore`. A trailing comment belongs to the last node on its line: in `a: 1 # t` the value ends the line, so `# t` is the value's `comment`; in `push: # only main` the value renders below, so the comment is the key's. Two slots per entry rather than one is what lets `push: # only main` and an own-line comment above the value both round-trip byte-intact, instead of one spelling being rewritten into the other. A header block with no `---` marker to separate it from the item stream leads the first entry's key by the same rule; one after the marker leads the root node.
 
 ## Lint and autofix
 
@@ -182,8 +184,8 @@ Multi-document streams — a Kubernetes manifest, or the two-document `pnpm-lock
 - `Yaml.stripComments` — quote-aware comment removal that keeps line numbers stable, or every byte offset stable when given a replacement character.
 - `Yaml.equals` / `Yaml.equalsValue` — semantic equality that ignores comments, whitespace, formatting and mapping key order while keeping sequence order significant.
 - `Yaml.schema` / `Yaml.fromString` / `Yaml.YamlFromString` / `Yaml.allFromString` — string→domain schema factories that decode a single document or a whole stream into a validated Effect `Schema` value.
-- `YamlNode` — an offset-preserving AST (`YamlScalar`, `YamlMap`, `YamlSeq`, `YamlPair`, `YamlAlias`) for locating and reading nodes by position or path, each collection and scalar carrying its own `commentBefore`, `comment` and `spaceBefore`.
-- `YamlDocument` — the full parsed AST plus the recovered `errors` and `warnings` arrays, so a partially valid document is still inspectable, and the leading and trailing comment blocks as `comment` / `commentAfter`.
+- `YamlNode` — an offset-preserving AST (`YamlScalar`, `YamlMap`, `YamlSeq`, `YamlPair`, `YamlAlias`) for locating and reading nodes by position or path; every node class except `YamlPair` carries its own `commentBefore`, `comment` and `spaceBefore`, and a pair is just its `key` and `value`.
+- `YamlDocument` — the full parsed AST plus the recovered `errors` and `warnings` arrays, so a partially valid document is still inspectable, and the header and trailing comment blocks as `commentBefore` / `comment`, the same two names the node classes use.
 - `YamlEdit` / `YamlFormat` — compute byte-minimal edit arrays for formatting and path-based modification, so a change preserves every comment and byte you did not touch; `preserveComments: false` opts out. `format` handles multi-document streams whole, re-emitting every document and its framing; `modify` is single-document by contract (a path names no particular document of a stream) and fails typed with `MultiDocumentStream` rather than guessing.
 - `YamlVisitor` — walk a parsed document as a `Stream` of a tagged-enum event union, with `Stream.take` early termination on large inputs and a `placement` on every comment event.
 - `YamlToken` / `YamlTokens` — the positioned token stream the lint rules read: `tokenize` is a synchronous `Result` that always succeeds, surfacing lexical problems as `error`-kind tokens, and `stream` derives an Effect `Stream` from the same walk.

package/YamlDocument.js

@@ -22,12 +22,14 @@ var YamlDirective = class extends Schema.Class("YamlDirective")({
 /**
 * A parsed YAML document: the root {@link (YamlNode:type)} (or `null` when
 * empty), recovered `errors` and `warnings` as {@link YamlDiagnostic} data,
-* the {@link YamlDirective} list, the optional document-level comments
-* (`comment` is the LEADING header block, `commentAfter` the trailing block
-* after the content or the `...` marker — the reference `yaml` package calls
-* these `commentBefore`/`comment`; the naming here keeps the pre-existing
-* `comment`-as-header field stable), and the `---`/`...` framing flags
-* (absent flags read as `false`).
+* the {@link YamlDirective} list, the optional document-level comments and the
+* `---`/`...` framing flags (absent flags read as `false`).
+*
+* `commentBefore` is a header block sitting AHEAD of a `---` marker; `comment`
+* is the trailing block after the content or the `...` marker. A header with
+* no marker, or one after the marker, belongs to the content rather than the
+* document — it leads the root node, or the first entry when there is no
+* marker to separate it from the item stream.
 *
 * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
 * synthetic documents.
@@ -39,8 +41,8 @@ var YamlDocument = class YamlDocument extends Schema.Class("YamlDocument")({
 	errors: Schema.Array(YamlDiagnostic),
 	warnings: Schema.Array(YamlDiagnostic),
 	directives: Schema.Array(YamlDirective),
+	commentBefore: Schema.optionalKey(Schema.String),
 	comment: Schema.optionalKey(Schema.String),
-	commentAfter: Schema.optionalKey(Schema.String),
 	hasDocumentStart: Schema.optionalKey(Schema.Boolean),
 	hasDocumentEnd: Schema.optionalKey(Schema.Boolean),
 	hasDocumentStartTab: Schema.optionalKey(Schema.Boolean)
@@ -186,8 +188,8 @@ function fromRawDocument(raw, text) {
 			name: d.name,
 			parameters: d.parameters
 		})),
+		...raw.commentBefore !== void 0 ? { commentBefore: raw.commentBefore } : {},
 		...raw.comment !== void 0 ? { comment: raw.comment } : {},
-		...raw.commentAfter !== void 0 ? { commentAfter: raw.commentAfter } : {},
 		hasDocumentStart: raw.hasDocumentStart,
 		hasDocumentEnd: raw.hasDocumentEnd,
 		hasDocumentStartTab: raw.hasDocumentStartTab
@@ -200,8 +202,8 @@ function toRawDocument(doc) {
 		errors: [],
 		warnings: [],
 		directives: doc.directives,
+		...doc.commentBefore !== void 0 ? { commentBefore: doc.commentBefore } : {},
 		...doc.comment !== void 0 ? { comment: doc.comment } : {},
-		...doc.commentAfter !== void 0 ? { commentAfter: doc.commentAfter } : {},
 		hasDocumentStart: doc.hasDocumentStart ?? false,
 		hasDocumentEnd: doc.hasDocumentEnd ?? false,
 		hasDocumentStartTab: doc.hasDocumentStartTab ?? false

package/YamlFormat.js

@@ -112,8 +112,8 @@ function toOutputDocument(doc, preserveComments) {
 		warnings: doc.warnings,
 		directives: doc.directives,
 		...preserveComments ? definedFields({
-			comment: doc.comment,
-			commentAfter: doc.commentAfter
+			commentBefore: doc.commentBefore,
+			comment: doc.comment
 		}) : {},
 		hasDocumentStart: doc.hasDocumentStart,
 		hasDocumentEnd: doc.hasDocumentEnd,
@@ -208,12 +208,7 @@ function modifyNode(node, path, depth, value) {
 				const oldPair = newItems[pairIndex];
 				newItems[pairIndex] = YamlPair.make({
 					key: oldPair.key,
-					value: newValueNode,
-					...definedFields({
-						commentBefore: oldPair.commentBefore,
-						comment: oldPair.comment,
-						spaceBefore: oldPair.spaceBefore
-					})
+					value: newValueNode
 				});
 				return rebuildMap(node, newItems);
 			}
@@ -236,12 +231,7 @@ function modifyNode(node, path, depth, value) {
 		const newItems = [...node.items];
 		newItems[pairIndex] = YamlPair.make({
 			key: pair.key,
-			value: newValue,
-			...definedFields({
-				commentBefore: pair.commentBefore,
-				comment: pair.comment,
-				spaceBefore: pair.spaceBefore
-			})
+			value: newValue
 		});
 		return rebuildMap(node, newItems);
 	}

package/YamlNode.js

@@ -120,12 +120,19 @@ var YamlScalar = class extends Schema.TaggedClass()("YamlScalar", {
 * A YAML alias AST node, referencing a previously defined anchor by name
 * (without the leading `*`).
 *
+* Carries the same comment triple as every other node class — see
+* {@link YamlScalar} for the field semantics. An alias is a node like any
+* other and a comment can legally sit above or after one.
+*
 * @public
 */
 var YamlAlias = class extends Schema.TaggedClass()("YamlAlias", {
 	name: Schema.String,
 	offset: Schema.Number,
-	length: Schema.Number
+	length: Schema.Number,
+	commentBefore: Schema.optionalKey(Schema.String),
+	comment: Schema.optionalKey(Schema.String),
+	spaceBefore: Schema.optionalKey(Schema.Boolean)
 }) {
 	/** See `YamlScalar.find`. Pure. */
 	find(path) {
@@ -168,20 +175,18 @@ const YamlNode = Schema.suspend(() => Schema.Union([
 * A YAML key-value pair AST node, representing one entry within a mapping.
 * `value` is `null` when absent (e.g. `key:` with no value).
 *
-* - `commentBefore` — own-line comment text directly above the pair's key
-*   (multiple consecutive comment lines join with `\n`).
-* - `comment` — trailing comment text on the pair's line (strictly trailing).
-* - `spaceBefore` — `true` when a blank line precedes the pair (and its
-*   `commentBefore` block, when present) in the source.
+* A pair carries **no comment fields**. Comments belong to the pair's `key`
+* and `value` nodes, which have one comment slot each: an own-line comment
+* above the entry leads the `key`, and a trailing comment on the entry's line
+* follows the `value`. Two slots rather than one is what lets `a: # kc` keep
+* its comment where the author wrote it instead of relocating it onto the
+* value's line.
 *
 * @public
 */
 var YamlPair = class extends Schema.TaggedClass()("YamlPair", {
 	key: Schema.suspend(() => YamlNode),
-	value: Schema.NullOr(Schema.suspend(() => YamlNode)),
-	commentBefore: Schema.optionalKey(Schema.String),
-	comment: Schema.optionalKey(Schema.String),
-	spaceBefore: Schema.optionalKey(Schema.Boolean)
+	value: Schema.NullOr(Schema.suspend(() => YamlNode))
 }) {};
 /**
 * A YAML mapping AST node, representing a collection of {@link YamlPair}

package/YamlVisitor.js

@@ -76,17 +76,17 @@ function* walkDocument(doc, text) {
 		depth,
 		diagnostic: YamlDiagnostic.fromRaw(raw, text)
 	});
-	if (doc.comment !== void 0) yield YamlVisitorEvent.Comment({
+	if (doc.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
 		path,
 		depth,
-		text: doc.comment,
+		text: doc.commentBefore,
 		placement: "leading"
 	});
 	if (doc.contents !== null) yield* walkNode(doc.contents, path, depth);
-	if (doc.commentAfter !== void 0) yield YamlVisitorEvent.Comment({
+	if (doc.comment !== void 0) yield YamlVisitorEvent.Comment({
 		path,
 		depth,
-		text: doc.commentAfter,
+		text: doc.comment,
 		placement: "trailing"
 	});
 	yield YamlVisitorEvent.DocumentEnd({
@@ -116,12 +116,25 @@ function* walkNode(node, path, depth) {
 			...node.tag !== void 0 ? { tag: node.tag } : {},
 			...node.anchor !== void 0 ? { anchor: node.anchor } : {}
 		});
-	} else if (node instanceof YamlAlias) yield YamlVisitorEvent.Alias({
-		path,
-		depth,
-		name: node.name
-	});
-	else if (node instanceof YamlMap) {
+	} else if (node instanceof YamlAlias) {
+		if (node.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.commentBefore,
+			placement: "leading"
+		});
+		if (node.comment !== void 0) yield YamlVisitorEvent.Comment({
+			path,
+			depth,
+			text: node.comment,
+			placement: "trailing"
+		});
+		yield YamlVisitorEvent.Alias({
+			path,
+			depth,
+			name: node.name
+		});
+	} else if (node instanceof YamlMap) {
 		if (node.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
 			path,
 			depth,
@@ -181,18 +194,6 @@ function* walkPair(pair, parentPath, depth) {
 	const resolvedValue = pair.value instanceof YamlScalar ? pair.value.value : null;
 	const keySegment = typeof resolvedKey === "string" ? resolvedKey : typeof resolvedKey === "number" ? resolvedKey : String(resolvedKey);
 	const pairPath = [...parentPath, keySegment];
-	if (pair.commentBefore !== void 0) yield YamlVisitorEvent.Comment({
-		path: pairPath,
-		depth,
-		text: pair.commentBefore,
-		placement: "leading"
-	});
-	if (pair.comment !== void 0) yield YamlVisitorEvent.Comment({
-		path: pairPath,
-		depth,
-		text: pair.comment,
-		placement: "trailing"
-	});
 	yield YamlVisitorEvent.Pair({
 		path: pairPath,
 		depth,

package/index.d.ts

@@ -727,11 +727,18 @@ declare const YamlAlias_base: Schema.Class<YamlAlias, Schema.TaggedStruct<"YamlA
   readonly name: Schema.String;
   readonly offset: Schema.Number;
   readonly length: Schema.Number;
+  readonly commentBefore: Schema.optionalKey<Schema.String>;
+  readonly comment: Schema.optionalKey<Schema.String>;
+  readonly spaceBefore: Schema.optionalKey<Schema.Boolean>;
 }>, {}>;
 /**
  * A YAML alias AST node, referencing a previously defined anchor by name
  * (without the leading `*`).
  *
+ * Carries the same comment triple as every other node class — see
+ * {@link YamlScalar} for the field semantics. An alias is a node like any
+ * other and a comment can legally sit above or after one.
+ *
  * @public
  */
 declare class YamlAlias extends YamlAlias_base {
@@ -797,19 +804,17 @@ type YamlNode = YamlScalar | YamlMap | YamlSeq | YamlAlias;
 declare const YamlPair_base: Schema.Class<YamlPair, Schema.TaggedStruct<"YamlPair", {
   readonly key: Schema.suspend<Schema.Codec<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAliasEncoded | YamlMapEncoded | YamlScalarEncoded | YamlSeqEncoded, never, never>>;
   readonly value: Schema.NullOr<Schema.suspend<Schema.Codec<YamlAlias | YamlMap | YamlScalar | YamlSeq, YamlAliasEncoded | YamlMapEncoded | YamlScalarEncoded | YamlSeqEncoded, never, never>>>;
-  readonly commentBefore: Schema.optionalKey<Schema.String>;
-  readonly comment: Schema.optionalKey<Schema.String>;
-  readonly spaceBefore: Schema.optionalKey<Schema.Boolean>;
 }>, {}>;
 /**
  * A YAML key-value pair AST node, representing one entry within a mapping.
  * `value` is `null` when absent (e.g. `key:` with no value).
  *
- * - `commentBefore` — own-line comment text directly above the pair's key
- *   (multiple consecutive comment lines join with `\n`).
- * - `comment` — trailing comment text on the pair's line (strictly trailing).
- * - `spaceBefore` — `true` when a blank line precedes the pair (and its
- *   `commentBefore` block, when present) in the source.
+ * A pair carries **no comment fields**. Comments belong to the pair's `key`
+ * and `value` nodes, which have one comment slot each: an own-line comment
+ * above the entry leads the `key`, and a trailing comment on the entry's line
+ * follows the `value`. Two slots rather than one is what lets `a: # kc` keep
+ * its comment where the author wrote it instead of relocating it onto the
+ * value's line.
  *
  * @public
  */
@@ -905,8 +910,8 @@ declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
   readonly errors: Schema.$Array<typeof YamlDiagnostic>;
   readonly warnings: Schema.$Array<typeof YamlDiagnostic>;
   readonly directives: Schema.$Array<typeof YamlDirective>;
+  readonly commentBefore: Schema.optionalKey<Schema.String>;
   readonly comment: Schema.optionalKey<Schema.String>;
-  readonly commentAfter: Schema.optionalKey<Schema.String>;
   readonly hasDocumentStart: Schema.optionalKey<Schema.Boolean>;
   readonly hasDocumentEnd: Schema.optionalKey<Schema.Boolean>;
   readonly hasDocumentStartTab: Schema.optionalKey<Schema.Boolean>;
@@ -914,12 +919,14 @@ declare const YamlDocument_base: Schema.Class<YamlDocument, Schema.Struct<{
 /**
  * A parsed YAML document: the root {@link (YamlNode:type)} (or `null` when
  * empty), recovered `errors` and `warnings` as {@link YamlDiagnostic} data,
- * the {@link YamlDirective} list, the optional document-level comments
- * (`comment` is the LEADING header block, `commentAfter` the trailing block
- * after the content or the `...` marker — the reference `yaml` package calls
- * these `commentBefore`/`comment`; the naming here keeps the pre-existing
- * `comment`-as-header field stable), and the `---`/`...` framing flags
- * (absent flags read as `false`).
+ * the {@link YamlDirective} list, the optional document-level comments and the
+ * `---`/`...` framing flags (absent flags read as `false`).
+ *
+ * `commentBefore` is a header block sitting AHEAD of a `---` marker; `comment`
+ * is the trailing block after the content or the `...` marker. A header with
+ * no marker, or one after the marker, belongs to the content rather than the
+ * document — it leads the root node, or the first entry when there is no
+ * marker to separate it from the item stream.
  *
  * Construct via `YamlDocument.parse` / `parseAll`; `YamlDocument.make` is for
  * synthetic documents.

package/internal/composer/block.js

@@ -1,6 +1,6 @@
-import { YamlMap, YamlPair, YamlScalar, YamlSeq } from "../../YamlNode.js";
+import { YamlAlias, YamlMap, YamlPair, YamlScalar, YamlSeq } from "../../YamlNode.js";
 import { checkAnchorOnAlias, getAnchorName, makeAlias, registerAnchor } from "./anchors.js";
-import { blankAboveIsKeepChompContent, columnAt, hasBlankLineAbove, isOwnLineAt, joinComments, rawCommentText, sameLineSpan, withCommentFields } from "./comments.js";
+import { blankAboveIsKeepChompContent, columnAt, hasBlankLineAbove, isAfterIndicatorOnly, isOwnLineAt, joinComments, rawCommentText, sameLineSpan, withCommentFields } from "./comments.js";
 import { enterNesting, exitNesting, hasMeta, hasNonWhitespaceBeforeOnLine, lineCol, lineIndentColumn, sameLine } from "./state.js";
 import { blockMapStartsWithValueSep, classifyPlainNumeric, collectMultilineKey, collectMultilinePlainScalar, findFirstContent, findLastContent, findNextContentInList, findNextSignificantChild, findValueSepOffset, getScalarStyle, hasValueSepAfterInList, hasValueSepBetween, hasValueSepThroughPlainScalars, makeScalar, resolveScalar, shouldPreserveRaw } from "./scalars.js";
 
@@ -507,6 +507,29 @@ function buildPairs(items, pairs, text, escaped) {
 	let lastNode;
 	let contentColumn = -1;
 	const nodeEnd = (n) => n.offset + n.length;
+	/**
+	* Rebuild `pair` with `text` appended to the trailing comment of whichever
+	* node owns the pair's last line: the value when present, otherwise the key.
+	*/
+	const withTrailingComment = (pair, text, onKey = false) => pair.value !== null && !onKey ? new YamlPair({
+		key: pair.key,
+		value: withCommentFields(pair.value, { comment: text })
+	}) : new YamlPair({
+		key: withCommentFields(pair.key, { comment: text }),
+		value: pair.value
+	});
+	/**
+	* Finish a pair: the pending leading fields go to its KEY node, the entry's
+	* trailing comment to whichever node owns the last line. The one place the
+	* node-level split is applied, so no construction site has to know it.
+	*/
+	const pushPair = (pair, leading, trailing, trailingOnKey = false) => {
+		const withLeading = Object.keys(leading).length === 0 ? pair : new YamlPair({
+			key: withCommentFields(pair.key, leading),
+			value: pair.value
+		});
+		return trailing === void 0 ? withLeading : withTrailingComment(withLeading, trailing, trailingOnKey);
+	};
 	const noteContentColumn = (offset) => {
 		if (contentColumn < 0 && offset >= 0) contentColumn = columnAt(text, offset);
 	};
@@ -544,15 +567,9 @@ function buildPairs(items, pairs, text, escaped) {
 		if (item.kind === "comment") {
 			const cOff = item.offset ?? -1;
 			const cText = item.comment ?? "";
-			if (!(cOff < 0 ? true : isOwnLineAt(text, cOff)) && pairs.length > 0) {
+			if (!(cOff < 0 ? true : isOwnLineAt(text, cOff) || isAfterIndicatorOnly(text, cOff)) && pairs.length > 0) {
 				const last = pairs[pairs.length - 1];
-				if (last) pairs[pairs.length - 1] = new YamlPair({
-					key: last.key,
-					value: last.value,
-					...last.commentBefore !== void 0 ? { commentBefore: last.commentBefore } : {},
-					comment: last.comment !== void 0 ? `${last.comment}\n${cText}` : cText,
-					...last.spaceBefore !== void 0 ? { spaceBefore: last.spaceBefore } : {}
-				});
+				if (last) pairs[pairs.length - 1] = withTrailingComment(last, cText);
 			} else {
 				const blankAbove = cOff >= 0 && hasBlankLineAbove(text, cOff) && !blankAboveIsKeepChompContent(text, cOff, lastNode);
 				if (blankAbove && pending.length === 0 && lastEnd >= 0) pendingSpace = true;
@@ -578,20 +595,18 @@ function buildPairs(items, pairs, text, escaped) {
 				length: 0
 			});
 			if (valueNode) {
-				pairs.push(new YamlPair({
+				pairs.push(pushPair(new YamlPair({
 					key: nullKey,
-					value: valueNode.node ?? null,
-					...pendingFields
-				}));
+					value: valueNode.node ?? null
+				}), pendingFields, void 0));
 				i = valueNode.nextIdx;
 				lastEnd = valueNode.node ? nodeEnd(valueNode.node) : valueSepOffset + 1;
 				lastNode = valueNode.node ?? void 0;
 			} else {
-				pairs.push(new YamlPair({
+				pairs.push(pushPair(new YamlPair({
 					key: nullKey,
-					value: null,
-					...pendingFields
-				}));
+					value: null
+				}), pendingFields, void 0));
 				lastEnd = valueSepOffset + 1;
 				lastNode = void 0;
 			}
@@ -629,32 +644,26 @@ function buildPairs(items, pairs, text, escaped) {
 					for (const c of valueResult.sameLineComments) pairTrailing = joinComments(pairTrailing, c);
 					let valNode = valueResult.node;
 					if (valNode !== null && valueResult.leadingComments.length > 0) valNode = withCommentFields(valNode, { commentBefore: valueResult.leadingComments.join("\n") });
-					pairs.push(new YamlPair({
+					pairs.push(pushPair(new YamlPair({
 						key: keyOrNull(),
-						value: valNode,
-						...pendingFields,
-						...pairTrailing !== void 0 ? { comment: pairTrailing } : {}
-					}));
+						value: valNode
+					}), pendingFields, pairTrailing, keyIsSimple(keyNode) && (valNode === null || !sameLineSpan(text, sepOffset, valNode.offset))));
 					i = valueResult.nextIdx;
 					lastEnd = valNode ? nodeEnd(valNode) : sepOffset + 1;
 					lastNode = valNode ?? void 0;
 				} else {
-					pairs.push(new YamlPair({
+					pairs.push(pushPair(new YamlPair({
 						key: keyOrNull(),
-						value: null,
-						...pendingFields,
-						...pairTrailing !== void 0 ? { comment: pairTrailing } : {}
-					}));
+						value: null
+					}), pendingFields, pairTrailing));
 					lastEnd = sepOffset + 1;
 					lastNode = void 0;
 				}
 			} else {
-				pairs.push(new YamlPair({
+				pairs.push(pushPair(new YamlPair({
 					key: keyOrNull(),
-					value: null,
-					...pendingFields,
-					...pairTrailing !== void 0 ? { comment: pairTrailing } : {}
-				}));
+					value: null
+				}), pendingFields, pairTrailing));
 				lastEnd = keyNode ? nodeEnd(keyNode) : lastEnd;
 				if (keyNode) lastNode = keyNode;
 			}
@@ -679,6 +688,17 @@ function buildPairs(items, pairs, text, escaped) {
 	}
 	return withLeadingBlank(pending);
 }
+/**
+* True when a key renders in implicit `key: value` form, so the `:` sits on
+* the key's own line. A multi-line or block-scalar key forces the explicit
+* `? key` / `: value` spelling, where the `:` gets a line of its own.
+*/
+function keyIsSimple(keyNode) {
+	if (keyNode instanceof YamlAlias) return true;
+	if (!(keyNode instanceof YamlScalar)) return false;
+	if (typeof keyNode.value === "string" && keyNode.value.includes("\n")) return false;
+	return keyNode.style !== "block-literal" && keyNode.style !== "block-folded";
+}
 function consumeValueNode(items, startIdx, text, sepOffset) {
 	let peek = startIdx;
 	while (peek < items.length && items[peek]?.kind === "comment") peek++;
@@ -687,13 +707,17 @@ function consumeValueNode(items, startIdx, text, sepOffset) {
 	let i = startIdx;
 	const sameLineComments = [];
 	const leadingComments = [];
+	let firstOwnLineIdx = -1;
 	while (i < items.length) {
 		const item = items[i];
 		if (!item) break;
 		if (item.kind === "comment") {
 			const cText = item.comment ?? "";
 			if (item.offset !== void 0 && sameLineSpan(text, sepOffset, item.offset)) sameLineComments.push(cText);
-			else leadingComments.push(cText);
+			else {
+				if (firstOwnLineIdx < 0) firstOwnLineIdx = i;
+				leadingComments.push(cText);
+			}
 			i++;
 			continue;
 		}
@@ -705,6 +729,12 @@ function consumeValueNode(items, startIdx, text, sepOffset) {
 		};
 		break;
 	}
+	if (firstOwnLineIdx >= 0) return {
+		node: null,
+		nextIdx: firstOwnLineIdx,
+		sameLineComments,
+		leadingComments: []
+	};
 	return i > startIdx ? {
 		node: null,
 		nextIdx: i,
@@ -723,10 +753,12 @@ function consumeValueNode(items, startIdx, text, sepOffset) {
 */
 function consumeValueNodeForNullKey(items, startIdx, text, valueSepOffset) {
 	let i = startIdx;
+	let firstOwnLineIdx = -1;
 	while (i < items.length) {
 		const item = items[i];
 		if (!item) break;
 		if (item.kind === "comment") {
+			if (firstOwnLineIdx < 0 && item.offset !== void 0 && !sameLineSpan(text, valueSepOffset, item.offset)) firstOwnLineIdx = i;
 			i++;
 			continue;
 		}
@@ -742,6 +774,10 @@ function consumeValueNodeForNullKey(items, startIdx, text, valueSepOffset) {
 		}
 		break;
 	}
+	if (firstOwnLineIdx >= 0) return {
+		node: null,
+		nextIdx: firstOwnLineIdx
+	};
 	return i > startIdx ? {
 		node: null,
 		nextIdx: i

package/internal/composer/comments.js

@@ -1,4 +1,4 @@
-import { YamlMap, YamlScalar, YamlSeq } from "../../YamlNode.js";
+import { YamlAlias, YamlMap, YamlScalar, YamlSeq } from "../../YamlNode.js";
 
 //#region src/internal/composer/comments.ts
 /** True when there is no line break between `start` and `end` in `text`. */
@@ -24,6 +24,31 @@ function isOwnLineAt(text, offset) {
 	return true;
 }
 /**
+* True when the only thing before `offset` on its line is a block indicator —
+* `?`, `:` or `-` — plus whitespace. Such a comment sits on an indicator line
+* with its node BELOW, so it leads that node rather than trailing whatever
+* came before (`? # c` / ` - seq1`). Without this, the `? ` prefix makes the
+* comment look like a trailing comment on the previous entry.
+*/
+function isAfterIndicatorOnly(text, offset) {
+	let i = offset - 1;
+	let sawIndicator = false;
+	while (i >= 0) {
+		const ch = text[i];
+		if (ch === " " || ch === "	") {
+			i--;
+			continue;
+		}
+		if (!sawIndicator && (ch === "?" || ch === "-" || ch === ":")) {
+			sawIndicator = true;
+			i--;
+			continue;
+		}
+		return sawIndicator && (ch === "\n" || ch === "\r");
+	}
+	return sawIndicator;
+}
+/**
 * True when the line immediately above the line containing `offset` is blank
 * (empty or horizontal whitespace only). Purely local — see
 * {@link isOwnLineAt} for why span-based gap checks are not used.
@@ -133,8 +158,8 @@ function columnAt(text, offset) {
 /**
 * Rebuild `node` with the given comment fields merged in (existing fields are
 * kept unless overridden; `commentBefore`/`comment` join with a newline when
-* both sides are present). Aliases are returned unchanged — they carry no
-* comment fields.
+* both sides are present). Every node class carries the triple, aliases
+* included.
 */
 function withCommentFields(node, fields) {
 	if (node instanceof YamlScalar) return new YamlScalar({
@@ -170,7 +195,12 @@ function withCommentFields(node, fields) {
 		offset: node.offset,
 		length: node.length
 	});
-	return node;
+	return new YamlAlias({
+		name: node.name,
+		...mergedCommentFields(node, fields),
+		offset: node.offset,
+		length: node.length
+	});
 }
 function mergedCommentFields(existing, incoming) {
 	const commentBefore = incoming.commentBefore !== void 0 ? existing.commentBefore !== void 0 ? `${existing.commentBefore}\n${incoming.commentBefore}` : incoming.commentBefore : existing.commentBefore;
@@ -184,4 +214,4 @@ function mergedCommentFields(existing, incoming) {
 }
 
 //#endregion
-export { blankAboveIsKeepChompContent, blankLineAboveStart, columnAt, hasBlankLineAbove, hasBlankLineBelow, isOwnLineAt, joinComments, rawCommentText, sameLineSpan, withCommentFields };
+export { blankAboveIsKeepChompContent, blankLineAboveStart, columnAt, hasBlankLineAbove, hasBlankLineBelow, isAfterIndicatorOnly, isOwnLineAt, joinComments, rawCommentText, sameLineSpan, withCommentFields };

package/internal/composer/document.js

@@ -1,7 +1,7 @@
 import { YamlAlias, YamlMap, YamlPair, YamlScalar, YamlSeq } from "../../YamlNode.js";
 import { parseCSTAll } from "../cst-parser.js";
 import { checkAnchorOnAlias, getAnchorName, makeAlias, registerAnchor } from "./anchors.js";
-import { hasBlankLineAbove, hasBlankLineBelow, rawCommentText } from "./comments.js";
+import { hasBlankLineAbove, hasBlankLineBelow, rawCommentText, withCommentFields } from "./comments.js";
 import { clearMeta, commentProps, createState, hasMeta, sameLine } from "./state.js";
 import { parseDirective, validateTagHandlesInDocument } from "./tags.js";
 import { collectMultilinePlainScalar, findNextContentChild, getScalarStyle, hasBlockMapAfterInList, hasValueSepAfter, indexOfChild, makeScalar, resolveScalar } from "./scalars.js";
@@ -134,7 +134,10 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 	let documentComment;
 	let documentCommentAfter;
 	let lastLeadingCommentOffset = -1;
+	let lastAfterMarkerCommentOffset = -1;
 	let sawDocEndMarker = false;
+	let sawDocStartMarker = false;
+	let afterMarkerComment;
 	const hasDocStart = children.some((c) => c.type === "whitespace" && c.source === "---");
 	let i = 0;
 	const meta = {};
@@ -171,6 +174,7 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 		if (child.type === "newline" && hasMeta(meta)) sawNewlineSinceMeta = true;
 		if (child.type === "whitespace" || child.type === "newline") {
 			if (child.type === "whitespace" && child.source === "...") sawDocEndMarker = true;
+			if (child.type === "whitespace" && child.source === "---") sawDocStartMarker = true;
 			if (child.type === "whitespace" && (child.source === "]" || child.source === "}")) state.errors.push({
 				code: "MalformedFlowCollection",
 				message: `Unexpected flow indicator '${child.source}' at document level`,
@@ -182,9 +186,15 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 		}
 		if (child.type === "comment" && contents === null && !sawDocEndMarker) {
 			const text = rawCommentText(child.source);
-			if (documentComment !== void 0 && hasBlankLineAbove(state.text, child.offset)) documentComment = `${documentComment}\n`;
-			documentComment = documentComment === void 0 ? text : `${documentComment}\n${text}`;
-			lastLeadingCommentOffset = child.offset;
+			if (sawDocStartMarker) {
+				if (afterMarkerComment !== void 0 && hasBlankLineAbove(state.text, child.offset)) afterMarkerComment = `${afterMarkerComment}\n`;
+				afterMarkerComment = afterMarkerComment === void 0 ? text : `${afterMarkerComment}\n${text}`;
+				lastAfterMarkerCommentOffset = child.offset;
+			} else {
+				if (documentComment !== void 0 && hasBlankLineAbove(state.text, child.offset)) documentComment = `${documentComment}\n`;
+				documentComment = documentComment === void 0 ? text : `${documentComment}\n${text}`;
+				lastLeadingCommentOffset = child.offset;
+			}
 			i++;
 			continue;
 		}
@@ -411,17 +421,32 @@ function composeDocument(cst, state, hasSubsequentDocuments = false, nextDocCst)
 		}
 	}
 	if (documentComment !== void 0 && contents !== null && hasBlankLineBelow(state.text, lastLeadingCommentOffset)) documentComment = `${documentComment}\n`;
+	if (afterMarkerComment !== void 0 && contents !== null && hasBlankLineBelow(state.text, lastAfterMarkerCommentOffset)) afterMarkerComment = `${afterMarkerComment}\n`;
 	state.escapedComments.length = 0;
+	if (documentCommentAfter === void 0 && contents !== null && contents.comment !== void 0) {
+		if ((contents instanceof YamlMap || contents instanceof YamlSeq) && contents.style !== "flow") {
+			documentCommentAfter = contents.comment;
+			contents = stripOwnComment(contents);
+		}
+	}
+	let headerForDocument;
+	let decorated = contents;
+	if (documentComment !== void 0) {
+		if (hasDocStart || contents === null) headerForDocument = documentComment;
+		else decorated = attachHeaderToFirstEntry(contents, documentComment);
+	}
+	if (afterMarkerComment !== void 0 && decorated !== null) decorated = withCommentFields(decorated, { commentBefore: afterMarkerComment });
+	else if (afterMarkerComment !== void 0) headerForDocument = headerForDocument === void 0 ? afterMarkerComment : `${headerForDocument}\n${afterMarkerComment}`;
 	return {
-		contents,
+		contents: decorated,
 		errors: [...state.errors],
 		warnings: [...state.warnings],
 		directives,
 		hasDocumentStart: hasDocStart,
 		hasDocumentEnd: hasDocEnd,
 		hasDocumentStartTab: hasDocStartTab,
-		...documentComment !== void 0 ? { comment: documentComment } : {},
-		...documentCommentAfter !== void 0 ? { commentAfter: documentCommentAfter } : {}
+		...headerForDocument !== void 0 ? { commentBefore: headerForDocument } : {},
+		...documentCommentAfter !== void 0 ? { comment: documentCommentAfter } : {}
 	};
 }
 /**
@@ -598,8 +623,7 @@ function decorateSourceMultiline(node, text) {
 	if (node instanceof YamlMap) {
 		const newItems = node.items.map((pair) => new YamlPair({
 			key: decorateSourceMultiline(pair.key, text) ?? pair.key,
-			value: pair.value === null ? null : decorateSourceMultiline(pair.value, text),
-			...commentProps(pair)
+			value: pair.value === null ? null : decorateSourceMultiline(pair.value, text)
 		}));
 		const multiline = isSourceMultiline(text, node.offset, node.length);
 		return new YamlMap({
@@ -637,8 +661,8 @@ function decorateDocumentSourceMultiline(doc, text) {
 		errors: doc.errors,
 		warnings: doc.warnings,
 		directives: doc.directives,
+		...doc.commentBefore !== void 0 ? { commentBefore: doc.commentBefore } : {},
 		...doc.comment !== void 0 ? { comment: doc.comment } : {},
-		...doc.commentAfter !== void 0 ? { commentAfter: doc.commentAfter } : {},
 		hasDocumentStart: doc.hasDocumentStart,
 		hasDocumentEnd: doc.hasDocumentEnd,
 		hasDocumentStartTab: doc.hasDocumentStartTab
@@ -709,6 +733,72 @@ function composeAllDocuments(text, options) {
 		streamErrors: crossDocState.errors
 	};
 }
+/**
+* Attach a marker-less document header to the FIRST entry of the content — the
+* first pair's key for a mapping, the first item for a sequence, the node
+* itself for a scalar. Without a `---` boundary the header is just the first
+* own-line comment in the document's item stream, so it forward-attributes
+* like any other.
+*/
+function attachHeaderToFirstEntry(contents, header) {
+	if (contents instanceof YamlMap && contents.items.length > 0) {
+		const first = contents.items[0];
+		const items = [...contents.items];
+		items[0] = new YamlPair({
+			key: withCommentFields(first.key, { commentBefore: header }),
+			value: first.value
+		});
+		return new YamlMap({
+			items,
+			style: contents.style,
+			...contents.tag !== void 0 ? { tag: contents.tag } : {},
+			...contents.anchor !== void 0 ? { anchor: contents.anchor } : {},
+			...contents.commentBefore !== void 0 ? { commentBefore: contents.commentBefore } : {},
+			...contents.comment !== void 0 ? { comment: contents.comment } : {},
+			...contents.spaceBefore !== void 0 ? { spaceBefore: contents.spaceBefore } : {},
+			...contents.sourceMultiline !== void 0 ? { sourceMultiline: contents.sourceMultiline } : {},
+			offset: contents.offset,
+			length: contents.length
+		});
+	}
+	if (contents instanceof YamlSeq && contents.items.length > 0) {
+		const items = [...contents.items];
+		items[0] = withCommentFields(items[0], { commentBefore: header });
+		return new YamlSeq({
+			items,
+			style: contents.style,
+			...contents.tag !== void 0 ? { tag: contents.tag } : {},
+			...contents.anchor !== void 0 ? { anchor: contents.anchor } : {},
+			...contents.commentBefore !== void 0 ? { commentBefore: contents.commentBefore } : {},
+			...contents.comment !== void 0 ? { comment: contents.comment } : {},
+			...contents.spaceBefore !== void 0 ? { spaceBefore: contents.spaceBefore } : {},
+			...contents.sourceMultiline !== void 0 ? { sourceMultiline: contents.sourceMultiline } : {},
+			offset: contents.offset,
+			length: contents.length
+		});
+	}
+	return withCommentFields(contents, { commentBefore: header });
+}
+/** Rebuild a collection without its own trailing `comment`. */
+function stripOwnComment(node) {
+	const shared = {
+		style: node.style,
+		...node.tag !== void 0 ? { tag: node.tag } : {},
+		...node.anchor !== void 0 ? { anchor: node.anchor } : {},
+		...node.commentBefore !== void 0 ? { commentBefore: node.commentBefore } : {},
+		...node.spaceBefore !== void 0 ? { spaceBefore: node.spaceBefore } : {},
+		...node.sourceMultiline !== void 0 ? { sourceMultiline: node.sourceMultiline } : {},
+		offset: node.offset,
+		length: node.length
+	};
+	return node instanceof YamlMap ? new YamlMap({
+		items: node.items,
+		...shared
+	}) : new YamlSeq({
+		items: node.items,
+		...shared
+	});
+}
 
 //#endregion
 export { EMPTY_DOCUMENT, composeAllDocuments, composeDocument, composeFirstDocument, composeFirstDocumentCounted, validateCrossDocumentDirectives };

package/internal/composer/flow.js

@@ -77,7 +77,7 @@ function validateFlowContentIndent(cst, state, parentBlockColumn) {
 				i++;
 				continue;
 			}
-			if (i - lineStart <= parentBlockColumn) {
+			if (i - lineStart <= parentBlockColumn && !isClosersOnly(text, i, end)) {
 				state.errors.push({
 					code: "InvalidIndentation",
 					message: "Flow content continuation line must be indented past the parent block",
@@ -91,6 +91,26 @@ function validateFlowContentIndent(cst, state, parentBlockColumn) {
 		i++;
 	}
 }
+/**
+* True when everything from `start` to the end of that line (bounded by `end`)
+* is flow closing punctuation — `}`, `]`, separating commas and whitespace.
+* Such a line closes the collection rather than carrying content, so the
+* continuation-indent floor does not apply to it.
+*/
+function isClosersOnly(text, start, end) {
+	let sawCloser = false;
+	for (let i = start; i < end && i < text.length; i++) {
+		const ch = text[i];
+		if (ch === "\n") break;
+		if (ch === "}" || ch === "]") {
+			sawCloser = true;
+			continue;
+		}
+		if (ch === "," || ch === " " || ch === "	" || ch === "\r") continue;
+		return false;
+	}
+	return sawCloser;
+}
 function composeFlowMap(cst, state, meta, parentBlockColumn) {
 	if (!enterNesting(state, cst)) return new YamlMap({
 		items: [],

package/internal/stringifier.js

@@ -487,10 +487,7 @@ function normalizeNodeTags(node, tagMap) {
 	if (node instanceof YamlMap) return new YamlMap({
 		items: node.items.map((pair) => new YamlPair({
 			key: normalizeNodeTags(pair.key, tagMap),
-			value: pair.value ? normalizeNodeTags(pair.value, tagMap) : null,
-			...pair.commentBefore !== void 0 ? { commentBefore: pair.commentBefore } : {},
-			...pair.comment !== void 0 ? { comment: pair.comment } : {},
-			...pair.spaceBefore !== void 0 ? { spaceBefore: pair.spaceBefore } : {}
+			value: pair.value ? normalizeNodeTags(pair.value, tagMap) : null
 		})),
 		style: node.style,
 		...node.tag ? { tag: normalizeTag(node.tag, tagMap) } : {},
@@ -643,6 +640,63 @@ function unescapeCommentLine(line) {
 function commentBlockLines(comment) {
 	return comment.split("\n").map((l) => l === "" ? "" : `#${unescapeCommentLine(l)}`);
 }
+/**
+* Splice a trailing comment onto the FIRST line of an already-rendered node —
+* for a block scalar, the header line, which is the one line of the scalar
+* that legally carries a `#` comment.
+*/
+function withHeaderComment(rendered, comment) {
+	const nl = rendered.indexOf("\n");
+	return nl === -1 ? `${rendered}${renderTrailingComment(comment)}` : `${rendered.slice(0, nl)}${renderTrailingComment(comment)}${rendered.slice(nl)}`;
+}
+/**
+* The leading comment block of a mapping entry. Under the node-level comment
+* model it lives on the entry's KEY node, not on the pair.
+*/
+function pairLeading(pair) {
+	return pair.key.commentBefore;
+}
+/**
+* The trailing comment of a mapping entry: it belongs to whichever node owns
+* the entry's last line — the value when there is one, otherwise the key. For
+* a block-scalar value that line is the HEADER line, which is why a block
+* scalar's header comment needs no separate concept.
+*/
+function pairTrailing(pair) {
+	return (pair.value ?? pair.key).comment;
+}
+/** True when a blank line preceded the entry (recorded on its KEY node). */
+function pairSpaceBefore(pair) {
+	return pair.key.spaceBefore;
+}
+/**
+* The trailing comment to place on an entry's own line, given how its value
+* actually rendered.
+*
+* A collection's `comment` field carries its TERMINAL comment run — the
+* own-line comments after its last entry — and the collection emits those
+* itself, after that last entry. Only when the collection renders on a single
+* line (inline flow, `a: {b: 1} # t`) is its `comment` the entry's trailing
+* comment. Reading it unconditionally emits the same comment twice: once on
+* the entry's line and again as the terminal run.
+*/
+function entryTrailing(pair, ctx) {
+	if (pair.key.comment !== void 0) return pair.key.comment;
+	const owner = pair.value ?? pair.key;
+	if (rendersAcrossLines(owner, ctx)) return void 0;
+	return owner.comment;
+}
+/**
+* True when `node` renders across more than one line, so its own `comment` is
+* a terminal run rather than something that can sit on the entry's line.
+*/
+function rendersAcrossLines(node, ctx) {
+	if (!(node instanceof YamlMap || node instanceof YamlSeq)) return false;
+	if (node.items.length === 0) return false;
+	if ((ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : node.style ?? ctx.defaultCollectionStyle) === "block" || node.sourceMultiline === true) return true;
+	if (ctx.forceDefaultStyles) return false;
+	return node instanceof YamlMap ? node.items.some((p) => pairLeading(p) !== void 0 || (p.value ?? p.key).comment !== void 0 || pairSpaceBefore(p) === true) : node.items.some((item) => item.commentBefore !== void 0 || item.comment !== void 0 || item.spaceBefore === true);
+}
 /** Render a trailing comment for appending after content on the same line. */
 function renderTrailingComment(comment) {
 	return ` #${comment.split("\n").map(unescapeCommentLine).join(" ")}`;
@@ -664,6 +718,14 @@ function pushExplicitKeyValueLines(lines, valNode, ctx, depth, pad) {
 		return lines.length - 1;
 	}
 	const valLines = stringifyNodeLines(valNode, ctx, depth + 1);
+	const valueLeading = !ctx.forceDefaultStyles ? valNode.commentBefore : void 0;
+	if (valueLeading !== void 0) {
+		const colonIdx = lines.length;
+		lines.push(":");
+		for (const cl of commentBlockLines(valueLeading)) lines.push(cl === "" ? "" : `${pad}${cl}`);
+		for (const vl of valLines) lines.push(vl === "" ? "" : `${pad}${vl}`);
+		return colonIdx;
+	}
 	if (valLines.length === 1) {
 		lines.push(`: ${valLines[0]}`);
 		return lines.length - 1;
@@ -674,15 +736,9 @@ function pushExplicitKeyValueLines(lines, valNode, ctx, depth, pad) {
 	const isInlineQuoted = valNode instanceof YamlScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""));
 	if (isBlockScalarHeader || isInlineQuoted) {
 		const headerIdx = lines.length;
-		if (isBlockScalarHeader) {
-			const scalarComment = !ctx.forceDefaultStyles && valNode instanceof YamlScalar ? valNode.comment : void 0;
-			lines.push(scalarComment !== void 0 ? `: ${first}${renderTrailingComment(scalarComment)}` : `: ${first}`);
-			for (let v = 1; v < valLines.length; v++) lines.push(valLines[v]);
-			return scalarComment !== void 0 ? -1 : headerIdx;
-		}
 		lines.push(`: ${first}`);
 		for (let v = 1; v < valLines.length; v++) lines.push(valLines[v]);
-		return lines.length - 1;
+		return isBlockScalarHeader ? headerIdx : lines.length - 1;
 	}
 	if (first.startsWith("-")) {
 		lines.push(`: ${first}`);
@@ -718,17 +774,19 @@ function stringifyMapNodeLines(node, ctx, depth) {
 	}
 	if (style === "flow") {
 		const flowPrefix = buildMetadataPrefix(node.tag, node.anchor);
-		if (!ctx.forceDefaultStyles && (node.comment !== void 0 || items.some((p) => p.commentBefore !== void 0 || p.comment !== void 0 || p.spaceBefore === true))) {
+		if (!ctx.forceDefaultStyles && (items.some((p) => pairLeading(p) !== void 0 || pairTrailing(p) !== void 0 || pairSpaceBefore(p) === true) || node.comment !== void 0 && node.sourceMultiline === true)) {
 			const flowPad = " ".repeat(ctx.indent);
 			const flowLines = [flowPrefix ? `${flowPrefix} {` : "{"];
 			for (let fi = 0; fi < items.length; fi++) {
 				const pair = items[fi];
-				if (pair.spaceBefore === true) flowLines.push("");
-				if (pair.commentBefore !== void 0) for (const cl of commentBlockLines(pair.commentBefore)) flowLines.push(cl === "" ? "" : `${flowPad}${cl}`);
+				if (pairSpaceBefore(pair) === true) flowLines.push("");
+				const flowLeading = pairLeading(pair);
+				if (flowLeading !== void 0) for (const cl of commentBlockLines(flowLeading)) flowLines.push(cl === "" ? "" : `${flowPad}${cl}`);
 				const keyStr = pair.key ? stringifyMappingKeyLines(pair.key, ctx, depth + 1).join(" ") : "null";
 				const valStr = pair.value ? stringifyNodeLines(pair.value, ctx, depth + 1).join(" ") : "null";
 				const comma = fi < items.length - 1 ? "," : "";
-				const trailing = pair.comment !== void 0 ? renderTrailingComment(pair.comment) : "";
+				const flowTrailing = pairTrailing(pair);
+				const trailing = flowTrailing !== void 0 ? renderTrailingComment(flowTrailing) : "";
 				flowLines.push(`${flowPad}${keyStr}: ${valStr}${comma}${trailing}`);
 			}
 			if (node.comment !== void 0) for (const cl of commentBlockLines(node.comment)) flowLines.push(cl === "" ? "" : `${flowPad}${cl}`);
@@ -750,10 +808,13 @@ function stringifyMapNodeLines(node, ctx, depth) {
 		lines[idx] = `${lines[idx]}${renderTrailingComment(comment)}`;
 	};
 	/** A value node's own leading comment block, or undefined. */
-	const valueLeading = (valNode) => emitComments && !(valNode instanceof YamlAlias) ? valNode.commentBefore : void 0;
+	const valueLeading = (valNode) => emitComments ? valNode.commentBefore : void 0;
 	for (const pair of items) {
-		if (emitComments && pair.spaceBefore === true) lines.push("");
-		if (emitComments && pair.commentBefore !== void 0) for (const cl of commentBlockLines(pair.commentBefore)) lines.push(cl);
+		if (emitComments && pairSpaceBefore(pair) === true) lines.push("");
+		const leading = emitComments ? pairLeading(pair) : void 0;
+		const keyOwnComment = emitComments ? pair.key.comment : void 0;
+		const valueOwnComment = emitComments && pair.value !== null ? pair.value.comment : void 0;
+		if (leading !== void 0) for (const cl of commentBlockLines(leading)) lines.push(cl);
 		const keyIsScalarWithNewline = pair.key instanceof YamlScalar && (typeof pair.key.value === "string" && pair.key.value.includes("\n") || pair.key.style === "block-literal" || pair.key.style === "block-folded");
 		if ((pair.key instanceof YamlMap || pair.key instanceof YamlSeq) && pair.key.items.length > 0 || keyIsScalarWithNewline) {
 			const keyLines = stringifyNodeLines(pair.key, ctx, depth + 1);
@@ -765,7 +826,7 @@ function stringifyMapNodeLines(node, ctx, depth) {
 			const contPad = firstIsMetaOnly || keyIsBlockScalar ? "" : EXPLICIT_COMPACT_PAD;
 			for (let k = 1; k < keyLines.length; k++) lines.push(`${contPad}${keyLines[k]}`);
 			const inlineIdx = pushExplicitKeyValueLines(lines, pair.value, ctx, depth, pad);
-			appendTrailing(inlineIdx >= 0 ? inlineIdx : keyLines.length === 1 ? explicitKeyLineIdx : -1, pair.comment);
+			appendTrailing(inlineIdx >= 0 ? inlineIdx : keyLines.length === 1 ? explicitKeyLineIdx : -1, entryTrailing(pair, ctx));
 			continue;
 		}
 		let resolvedKeyStr;
@@ -776,7 +837,7 @@ function stringifyMapNodeLines(node, ctx, depth) {
 			lines.push(`? ${keyStr}`);
 			const spillKeyLineIdx = lines.length - 1;
 			const inlineIdx = pushExplicitKeyValueLines(lines, pair.value, ctx, depth, pad);
-			appendTrailing(inlineIdx >= 0 ? inlineIdx : spillKeyLineIdx, pair.comment);
+			appendTrailing(inlineIdx >= 0 ? inlineIdx : spillKeyLineIdx, entryTrailing(pair, ctx));
 			continue;
 		}
 		const keyIsAnchoredOrTaggedEmpty = pair.key instanceof YamlScalar && pair.key.length === 0 && (pair.key.value === null || pair.key.value === void 0 || pair.key.value === "") && (pair.key.anchor !== void 0 || pair.key.tag !== void 0);
@@ -788,7 +849,7 @@ function stringifyMapNodeLines(node, ctx, depth) {
 			const isRootFlowMap = ctx.parentPosition === void 0 && node.style === "flow" && node.sourceMultiline === true;
 			if (ctx.forceDefaultStyles && isRootFlowMap && isPlainKey && keyIsNonEmpty) lines.push(`${keyStr}${sep} null`);
 			else lines.push(`${keyStr}${sep}`);
-			appendTrailing(lines.length - 1, pair.comment);
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
 			continue;
 		}
 		const valLines = stringifyNodeLines(valNode, {
@@ -800,7 +861,7 @@ function stringifyMapNodeLines(node, ctx, depth) {
 			const seqMeta = buildMetadataPrefix(valNode.tag, valNode.anchor);
 			const startIdx = seqMeta ? 1 : 0;
 			lines.push(seqMeta ? `${keyStr}${sep} ${seqMeta}` : `${keyStr}${sep}`);
-			appendTrailing(lines.length - 1, pair.comment);
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
 			if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(ctx.indentSequences ? `${pad}${cl}` : cl);
 			for (let i = startIdx; i < valLines.length; i++) {
 				const vl = valLines[i];
@@ -810,47 +871,57 @@ function stringifyMapNodeLines(node, ctx, depth) {
 			const mapMeta = buildMetadataPrefix(valNode.tag, valNode.anchor);
 			const startIdx = mapMeta ? 1 : 0;
 			lines.push(mapMeta ? `${keyStr}${sep} ${mapMeta}` : `${keyStr}${sep}`);
-			appendTrailing(lines.length - 1, pair.comment);
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
 			if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(`${pad}${cl}`);
 			for (let i = startIdx; i < valLines.length; i++) lines.push(valLines[i] === "" ? "" : `${pad}${valLines[i]}`);
-		} else if (valLines.length === 1 && valLeading !== void 0) {
+		} else if (valLines.length === 1 && (valLeading !== void 0 || keyOwnComment !== void 0)) {
 			lines.push(`${keyStr}${sep}`);
-			appendTrailing(lines.length - 1, pair.comment);
-			for (const cl of commentBlockLines(valLeading)) lines.push(`${pad}${cl}`);
+			appendTrailing(lines.length - 1, keyOwnComment);
+			if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(`${pad}${cl}`);
 			lines.push(valLines[0] === "" ? "" : `${pad}${valLines[0]}`);
+			appendTrailing(lines.length - 1, valueOwnComment);
 		} else if (valLines.length === 1) {
 			lines.push(valLines[0] === "" ? `${keyStr}${sep}` : `${keyStr}${sep} ${valLines[0]}`);
-			appendTrailing(lines.length - 1, pair.comment);
+			appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
 		} else {
 			const first = valLines[0];
 			const firstStripped = stripScalarMetadataPrefix(first);
 			const isBlockScalarHeader = firstStripped.startsWith("|") || firstStripped.startsWith(">");
 			const isInlineQuoted = valNode instanceof YamlScalar && (firstStripped.startsWith("'") || firstStripped.startsWith("\""));
 			if (isBlockScalarHeader || isInlineQuoted) {
-				const scalarComment = isBlockScalarHeader && valNode instanceof YamlScalar ? valNode.comment : void 0;
-				if (scalarComment !== void 0 && pair.comment !== void 0) {
+				if (valLeading !== void 0) {
 					lines.push(`${keyStr}${sep}`);
-					appendTrailing(lines.length - 1, pair.comment);
-					const headerIdx = lines.length;
+					for (const cl of commentBlockLines(valLeading)) lines.push(cl === "" ? "" : `${pad}${cl}`);
+					const spilledIdx = lines.length;
 					lines.push(`${pad}${first}`);
 					for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
-					appendTrailing(headerIdx, scalarComment);
-				} else {
-					const headerIdx = lines.length;
-					lines.push(`${keyStr}${sep} ${first}`);
+					appendTrailing(isBlockScalarHeader ? spilledIdx : lines.length - 1, entryTrailing(pair, ctx));
+					continue;
+				}
+				const keyComment = !ctx.forceDefaultStyles ? pair.key.comment : void 0;
+				const scalarComment = isBlockScalarHeader && valNode instanceof YamlScalar ? valNode.comment : void 0;
+				if (keyComment !== void 0 && scalarComment !== void 0) {
+					lines.push(`${keyStr}${sep}`);
+					appendTrailing(lines.length - 1, keyComment);
+					const spilledIdx = lines.length;
+					lines.push(`${pad}${first}`);
 					for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
-					if (isBlockScalarHeader) appendTrailing(headerIdx, scalarComment ?? pair.comment);
-					else appendTrailing(lines.length - 1, pair.comment);
+					appendTrailing(spilledIdx, scalarComment);
+					continue;
 				}
+				const headerIdx = lines.length;
+				lines.push(`${keyStr}${sep} ${first}`);
+				for (let i = 1; i < valLines.length; i++) lines.push(valLines[i]);
+				appendTrailing(isBlockScalarHeader ? headerIdx : lines.length - 1, entryTrailing(pair, ctx));
 			} else {
 				const mapMeta = valNode instanceof YamlMap && (ctx.forceDefaultStyles ? ctx.defaultCollectionStyle : valNode.style ?? ctx.defaultCollectionStyle) === "block" ? buildMetadataPrefix(valNode.tag, valNode.anchor) : void 0;
 				if (mapMeta) {
 					lines.push(`${keyStr}${sep} ${mapMeta}`);
-					appendTrailing(lines.length - 1, pair.comment);
+					appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
 					for (let i = 1; i < valLines.length; i++) lines.push(valLines[i] === "" ? "" : `${pad}${valLines[i]}`);
 				} else {
 					lines.push(`${keyStr}${sep}`);
-					appendTrailing(lines.length - 1, pair.comment);
+					appendTrailing(lines.length - 1, entryTrailing(pair, ctx));
 					if (valLeading !== void 0) for (const cl of commentBlockLines(valLeading)) lines.push(`${pad}${cl}`);
 					for (const vl of valLines) lines.push(vl === "" ? "" : `${pad}${vl}`);
 				}
@@ -906,13 +977,13 @@ function stringifySeqNodeLines(node, ctx, depth) {
 	}
 	const emitComments = !ctx.forceDefaultStyles;
 	const itemFields = (item) => {
-		if (!emitComments || item instanceof YamlAlias) return void 0;
+		if (!emitComments) return void 0;
 		if (item.commentBefore === void 0 && item.comment === void 0 && item.spaceBefore !== true) return void 0;
 		return item;
 	};
 	if (style === "flow") {
 		const flowPrefix = buildMetadataPrefix(node.tag, node.anchor);
-		if (emitComments && (node.comment !== void 0 || items.some((it) => itemFields(it) !== void 0))) {
+		if (emitComments && (items.some((it) => itemFields(it) !== void 0) || node.comment !== void 0 && node.sourceMultiline === true)) {
 			const flowPad = " ".repeat(ctx.indent);
 			const flowLines = [flowPrefix ? `${flowPrefix} [` : "["];
 			for (let fi = 0; fi < items.length; fi++) {
@@ -998,7 +1069,7 @@ function stringifyDocument(doc, options) {
 	const ctx = createContext(options);
 	const finalNewline = options?.finalNewline ?? true;
 	let contents = doc.contents;
-	const docCommentRaw = ctx.forceDefaultStyles ? void 0 : doc.comment;
+	const docCommentRaw = ctx.forceDefaultStyles ? void 0 : doc.commentBefore;
 	const docComment = docCommentRaw !== void 0 ? commentBlockLines(docCommentRaw).join("\n") : void 0;
 	if (ctx.forceDefaultStyles && contents) {
 		contents = stripNodeComments(contents);
@@ -1010,28 +1081,31 @@ function stringifyDocument(doc, options) {
 			if (doc.hasDocumentStart) return `---\n${doc.hasDocumentEnd ? "...\n" : ""}`;
 			return "";
 		}
-		if (docComment !== void 0 || doc.commentAfter !== void 0 || doc.hasDocumentStart === true || doc.hasDocumentEnd === true) {
+		if (docComment !== void 0 || doc.comment !== void 0 || doc.hasDocumentStart === true || doc.hasDocumentEnd === true) {
 			const parts = [];
 			if (docComment !== void 0) parts.push(`${docComment}\n`);
 			if (doc.hasDocumentStart) parts.push("---\n");
 			if (doc.hasDocumentEnd) parts.push("...\n");
-			if (doc.commentAfter !== void 0) parts.push(`${commentBlockLines(doc.commentAfter).join("\n")}\n`);
+			if (doc.comment !== void 0) parts.push(`${commentBlockLines(doc.comment).join("\n")}\n`);
 			const out = parts.join("");
 			return finalNewline ? out : out.replace(/\n$/, "");
 		}
 		return finalNewline ? "null\n" : "null";
 	}
 	const result = stringifyNodeLines(contents, ctx, 0).join("\n");
+	const rootHeaderComment = !ctx.forceDefaultStyles && contents instanceof YamlScalar && (contents.style === "block-literal" || contents.style === "block-folded") ? contents.comment : void 0;
+	const rendered = rootHeaderComment === void 0 ? result : withHeaderComment(result, rootHeaderComment);
 	const needsTerminatorForKeepChomp = ctx.forceDefaultStyles && endsWithKeepChomp(result);
 	const needsTerminatorForAnchoredPlainScalar = ctx.forceDefaultStyles && doc.hasDocumentStart && contents instanceof YamlScalar && contents.style === "plain" && contents.anchor !== void 0 && !contents.tag;
 	const looksLikeDirectiveContinuation = contents instanceof YamlScalar && typeof contents.value === "string" && / %[A-Z]/.test(contents.value);
 	const needsTerminatorForMultilinePlainScalar = ctx.forceDefaultStyles && doc.hasDocumentStart && contents instanceof YamlScalar && contents.style === "plain" && contents.sourceMultiline === true && looksLikeDirectiveContinuation;
 	const needsTerminatorForDocStartTab = ctx.forceDefaultStyles && doc.hasDocumentStartTab === true;
 	const docEndMarker = doc.hasDocumentEnd || needsTerminatorForKeepChomp || needsTerminatorForAnchoredPlainScalar || needsTerminatorForMultilinePlainScalar || needsTerminatorForDocStartTab ? "...\n" : "";
-	const docCommentAfter = ctx.forceDefaultStyles || doc.commentAfter === void 0 ? void 0 : commentBlockLines(doc.commentAfter).join("\n");
+	const docCommentAfter = ctx.forceDefaultStyles || doc.comment === void 0 ? void 0 : commentBlockLines(doc.comment).join("\n");
 	const docEndFull = docCommentAfter !== void 0 ? `${docEndMarker}${docCommentAfter}\n` : docEndMarker;
-	const body = finalNewline || docEndFull !== "" ? `${result}\n` : result;
+	const body = finalNewline || docEndFull !== "" ? `${rendered}\n` : rendered;
 	const docEnd = finalNewline || docEndFull === "" ? docEndFull : docEndFull.replace(/\n$/, "");
+	const rootLeading = !ctx.forceDefaultStyles && contents !== null && contents.commentBefore !== void 0 ? `${commentBlockLines(contents.commentBefore).join("\n")}\n` : "";
 	if (doc.hasDocumentStart) {
 		const rootTag = contents && "tag" in contents ? contents.tag : void 0;
 		const rootAnchor = contents && "anchor" in contents ? contents.anchor : void 0;
@@ -1048,13 +1122,15 @@ function stringifyDocument(doc, options) {
 			if (bodyClean.startsWith(metaLinePrefix)) bodyClean = bodyClean.slice(metaLinePrefix.length);
 			else if (bodyClean.startsWith(metaInlinePrefix)) bodyClean = bodyClean.slice(metaInlinePrefix.length);
 			const docStart = `--- ${metaStr}`;
-			const sep = isCollection ? "\n" : " ";
-			return docComment ? `${docComment}\n${docStart}${sep}${bodyClean}${docEnd}` : `${docStart}${sep}${bodyClean}${docEnd}`;
+			const metaBody = rootLeading === "" ? `${isCollection ? "\n" : " "}${bodyClean}` : `\n${rootLeading}${bodyClean}`;
+			return docComment ? `${docComment}\n${docStart}${metaBody}${docEnd}` : `${docStart}${metaBody}${docEnd}`;
 		}
-		if (isScalar) return docComment ? `${docComment}\n--- ${body}${docEnd}` : `--- ${body}${docEnd}`;
-		return docComment ? `${docComment}\n---\n${body}${docEnd}` : `---\n${body}${docEnd}`;
+		if (isScalar && rootLeading === "") return docComment ? `${docComment}\n--- ${body}${docEnd}` : `--- ${body}${docEnd}`;
+		const afterMarker = `---\n${rootLeading}${body}${docEnd}`;
+		return docComment ? `${docComment}\n${afterMarker}` : afterMarker;
 	}
-	return docComment ? `${docComment}\n${body}${docEnd}` : `${body}${docEnd}`;
+	const plain = `${rootLeading}${body}${docEnd}`;
+	return docComment ? `${docComment}\n${plain}` : plain;
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/yaml",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"private": false,
 	"description": "Zero-dependency YAML parsing, editing, formatting and linting as Effect schemas.",
 	"keywords": [
@@ -41,7 +41,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"effect": "4.0.0-beta.107"
+		"effect": "4.0.0-rc.109"
 	},
 	"engines": {
 		"node": ">=24.11.0"