@effected/markdown 0.17.0 → 0.19.0

package/Markdown.js

@@ -2,7 +2,7 @@ import { Root } from "./MarkdownNode.js";
 import { isGuardExceeded, isRawMarkdownError } from "./internal/carriers.js";
 import { parseBlocks } from "./internal/blockParser.js";
 import { parsePhrasingText } from "./internal/phrasing.js";
-import { stringifyTree } from "./internal/stringify.js";
+import { stringifyBlocks } from "./internal/stringify.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
@@ -256,11 +256,20 @@ var Markdown = class Markdown {
 	*/
 	static parsePhrasing = Effect.fn("Markdown.parsePhrasing")((text, options) => Effect.fromResult(Markdown.parsePhrasingResult(text, options)));
 	/**
-	* Serialize a {@link Root} tree to canonical markdown, synchronously, as a
-	* `Result`. The pure primitive twin of {@link Markdown.stringify}, on the
-	* same terms as {@link Markdown.parseResult}.
+	* Serialize a {@link Root} tree, or a single {@link (FlowContent:type)} node, to
+	* canonical markdown, synchronously, as a `Result`. The pure primitive twin
+	* of {@link Markdown.stringify}, on the same terms as
+	* {@link Markdown.parseResult}.
 	*
 	* @remarks
+	* **A single flow node is defined as its one-child document**: passing
+	* `node` is exactly `stringifyResult(Root.make({ children: [node] }))` —
+	* the same code path, the same trailing `\n`, the same canonical choices.
+	* This lets a caller serialize one block (a table, a section's paragraph,
+	* an MDX flow element) without building the wrapper by hand.
+	* `Frontmatter` and `MdxjsEsm` are deliberately not admitted alone — each
+	* is meaningful only at a document's root — so wrap them in a `Root`.
+	*
 	* Canonical serialization: fidelity fields (marker characters, fence
 	* style, heading spelling) win when present; documented canonical
 	* defaults apply when absent. One default surprises: a language-less
@@ -343,13 +352,13 @@ var Markdown = class Markdown {
 	* trip on a tree nesting past the depth cap fails, and only synthesized
 	* or decoded trees can nest that far.
 	*
-	* @param root - The document tree to serialize.
+	* @param node - The document tree, or a single flow node, to serialize.
 	* @returns A `Result` succeeding with markdown source, or failing with
 	*   {@link MarkdownStringifyError}.
 	*/
-	static stringifyResult(root) {
+	static stringifyResult(node) {
 		try {
-			return Result.succeed(stringifyTree(root));
+			return Result.succeed(stringifyBlocks(node.type === "root" ? node.children : [node]));
 		} catch (caught) {
 			if (isGuardExceeded(caught)) return Result.fail(new MarkdownStringifyError({ diagnostic: MarkdownDiagnostic.make({
 				code: caught.reason,
@@ -363,9 +372,9 @@ var Markdown = class Markdown {
 		}
 	}
 	/**
-	* Serialize a {@link Root} tree to canonical markdown. Defined in terms of
-	* {@link Markdown.stringifyResult} — synchronous callers can use that
-	* variant directly.
+	* Serialize a {@link Root} tree, or a single {@link (FlowContent:type)} node, to
+	* canonical markdown. Defined in terms of {@link Markdown.stringifyResult}
+	* — synchronous callers can use that variant directly.
 	*
 	* @remarks
 	* The canonical form is a **stability commitment** and safe to assert
@@ -381,11 +390,14 @@ var Markdown = class Markdown {
 	* `escapeStyle`, an emitter instruction rather than a source spelling,
 	* which the boundary admits.
 	*
-	* @param root - The document tree to serialize.
+	* A single flow node serializes exactly as its one-child document does;
+	* see {@link Markdown.stringifyResult}.
+	*
+	* @param node - The document tree, or a single flow node, to serialize.
 	* @returns An `Effect` that succeeds with markdown source, or fails with
 	*   {@link MarkdownStringifyError}.
 	*/
-	static stringify = Effect.fn("Markdown.stringify")((root) => Effect.fromResult(Markdown.stringifyResult(root)));
+	static stringify = Effect.fn("Markdown.stringify")((node) => Effect.fromResult(Markdown.stringifyResult(node)));
 	/**
 	* A `Schema<Root, string>` decoding markdown source into a {@link Root}
 	* tree and encoding a tree back to canonical markdown via

package/MarkdownDocument.js

@@ -5,6 +5,7 @@ import { preprocessLines } from "./internal/preprocess.js";
 import { normalizeLabelText } from "./internal/references.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { parsePassResult } from "./Markdown.js";
+import { rootHeadingBounds } from "./internal/sectionBounds.js";
 import { Effect, Result, Schema } from "effect";
 
 //#region src/MarkdownDocument.ts
@@ -239,43 +240,9 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	get sections() {
 		const blocks = this.root.children;
 		const sections = [];
-		const headings = [];
-		for (let index = 0; index < blocks.length; index += 1) {
-			const block = blocks[index];
-			if (block !== void 0 && block.type === "heading") headings.push({
-				index,
-				node: block
-			});
-		}
-		const nextByDepth = [
-			void 0,
-			void 0,
-			void 0,
-			void 0,
-			void 0,
-			void 0,
-			void 0
-		];
-		const boundaryByHeading = new Array(headings.length);
-		for (let index = headings.length - 1; index >= 0; index -= 1) {
-			const current = headings[index]?.node;
-			if (current === void 0) continue;
-			let boundary;
-			for (let depth = 1; depth <= current.depth; depth += 1) {
-				const candidate = nextByDepth[depth];
-				if (candidate !== void 0 && (boundary === void 0 || candidate < boundary)) boundary = candidate;
-			}
-			boundaryByHeading[index] = boundary;
-			nextByDepth[current.depth] = index;
-		}
-		for (let index = 0; index < headings.length; index += 1) {
-			const current = headings[index];
-			if (current === void 0) continue;
-			const block = current.node;
-			const boundaryHeading = boundaryByHeading[index];
-			const boundaryNode = boundaryHeading === void 0 ? void 0 : headings[boundaryHeading]?.node;
+		for (const { heading: block, index, end } of rootHeadingBounds(blocks)) {
+			const boundaryNode = blocks[end];
 			const boundary = boundaryNode === void 0 ? this.source.length : boundaryNode.position.start.offset;
-			const end = boundaryHeading === void 0 ? blocks.length : headings[boundaryHeading]?.index ?? blocks.length;
 			const start = block.position.start.offset;
 			const bodyStart = block.position.end.offset;
 			sections.push(new DocumentSection({
@@ -285,7 +252,7 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 					offset: start,
 					length: boundary - start
 				}),
-				children: blocks.slice(current.index + 1, end).filter((child) => child.type !== "frontmatter" && child.type !== "mdxjsEsm"),
+				children: blocks.slice(index + 1, end).filter((child) => child.type !== "frontmatter" && child.type !== "mdxjsEsm"),
 				text: phrasingText(block.children),
 				bodyRange: MarkdownRange.make({
 					offset: bodyStart,

package/MarkdownTransform.js

@@ -0,0 +1,167 @@
+import { rootHeadingBounds } from "./internal/sectionBounds.js";
+
+//#region src/MarkdownTransform.ts
+/**
+* Pure, total tree-to-tree transforms over the markdown node classes. Not
+* instantiable.
+*
+* @remarks
+* Every method returns a plain value — none has an error channel. They work
+* on a tree, never on source text, so they compose with
+* {@link Markdown.stringify} for output and with each other; offset-splice
+* editing stays the job of `MarkdownFormat` and `MarkdownEdit`.
+*
+* @example
+* ```ts
+* import { LinkReference, Markdown, MarkdownTransform } from "@effected/markdown";
+* import { Result } from "effect";
+*
+* const parsed = Markdown.parseResult("# Title\n\nSee [docs](https://example.com).\n");
+* if (Result.isSuccess(parsed)) {
+*   const shifted = MarkdownTransform.shiftHeadings(parsed.success, 1);
+*   const rewritten = MarkdownTransform.map(shifted, {
+*     link: (link) =>
+*       LinkReference.make({ identifier: "docs", referenceType: "full", children: link.children }),
+*   });
+*   Markdown.stringifyResult(rewritten); // "## Title\n\nSee [docs][docs].\n"
+* }
+* ```
+*
+* @public
+*/
+var MarkdownTransform = class {
+	constructor() {}
+	static map(node, handlers) {
+		return mapNode(node, handlers);
+	}
+	/**
+	* Shift every heading's depth by `by`, clamped into `[min, max]`.
+	*
+	* @remarks
+	* The new depth is `clamp(depth + by, min ?? 1, max ?? 6)`. A heading
+	* whose new depth exceeds 2 loses `headingStyle: "setext"` (the key is
+	* omitted), since setext spells depths 1 and 2 only; it then serializes
+	* as ATX. A heading whose depth does not change, and needs no setext
+	* drop, keeps its identity; structural sharing follows
+	* {@link MarkdownTransform.(map:1)}, on which this is built. Accepts any node,
+	* including a lone {@link Heading}.
+	*
+	* Built on `map`, it recurses the same way: a hand-built tree nested far
+	* deeper than anything `Markdown.parse` or `Mdast.fromMdast` produces can
+	* overflow the call stack.
+	*
+	* @param node - The node whose headings to shift.
+	* @param by - The signed depth offset; must be an integer.
+	* @param options - Optional {@link ShiftHeadingsOptions} clamp bounds.
+	* @returns The node with headings shifted.
+	* @throws `RangeError` when `by` is not an integer, or `min` / `max` is not
+	*   a heading depth or `min > max` — a wiring error, not a data error.
+	*/
+	static shiftHeadings(node, by, options) {
+		if (!Number.isInteger(by)) throw new RangeError(`MarkdownTransform.shiftHeadings: by must be an integer, got ${by}`);
+		const min = options?.min ?? 1;
+		const max = options?.max ?? 6;
+		if (!isHeadingDepth(min) || !isHeadingDepth(max) || min > max) throw new RangeError(`MarkdownTransform.shiftHeadings: invalid depth bounds min=${min} max=${max}`);
+		return mapNode(node, { heading: (heading) => {
+			const depth = Math.min(max, Math.max(min, heading.depth + by));
+			const dropSetext = depth > 2 && heading.headingStyle === "setext";
+			if (depth === heading.depth && !dropSetext) return heading;
+			const { headingStyle, ...rest } = heading;
+			const ctor = heading.constructor;
+			return new ctor({
+				...rest,
+				depth,
+				...headingStyle !== void 0 && !dropSetext ? { headingStyle } : {}
+			}, { disableChecks: true });
+		} });
+	}
+	/**
+	* Locate the root-level sections of one heading depth by child index —
+	* no source text needed, so it works on a tree a
+	* `MarkdownTransform.map` has reshaped.
+	*
+	* @remarks
+	* Returns the root-level headings of exactly `depth` whose index lies in
+	* `[start, end)`, in document order. Each section ends at the next
+	* root-level heading of equal or shallower depth, or at `end` — the same
+	* boundary rule as `MarkdownDocument.sections`, from one shared
+	* implementation. The window is what lets a caller nest: find the depth-2
+	* blocks, then the depth-3 sections inside one block's
+	* `[headingIndex + 1, end)`.
+	*
+	* **A shallower heading ends a section too.** Querying depth 2 on
+	* `## Features`, a list, a stray `# Top` and another list yields one span
+	* whose `end` is the `# Top` heading's index, so neither `# Top` nor the
+	* list after it belongs to the section. That is the outline reading. A
+	* caller that wants each section to run to the next heading of the SAME
+	* depth (slicing a changeset or changelog by entry, where a stray H1 is
+	* content) computes each body's end from the next span's `headingIndex`
+	* instead, or the window's end for the last span, as in the example.
+	*
+	* @example
+	* Bodies that run to the next same-depth heading:
+	*
+	* ```ts
+	* import { Markdown, MarkdownTransform } from "@effected/markdown";
+	* import { Result } from "effect";
+	*
+	* const root = Result.getOrThrow(Markdown.parseResult("## Features\n\n- a\n\n# Top\n\n- b\n"));
+	* const spans = MarkdownTransform.sections(root, { depth: 2 });
+	* // spans[0].end === 2: the outline section stops at `# Top`
+	* const bodies = spans.map((span, index) =>
+	*   root.children.slice(span.headingIndex + 1, spans[index + 1]?.headingIndex ?? root.children.length),
+	* );
+	* // bodies[0] holds the first list, `# Top` and the second list
+	* ```
+	*
+	* @param root - The tree whose root-level headings delimit sections.
+	* @param options - The {@link SectionSpanOptions} depth and window.
+	* @returns The matching {@link SectionSpan}s, in document order.
+	* @throws `RangeError` when `depth` is not an integer from 1 to 6, when
+	*   `start` or `end` is not an integer in `[0, root.children.length]`, or
+	*   when `start > end`.
+	*/
+	static sections(root, options) {
+		if (!isHeadingDepth(options.depth)) throw new RangeError(`MarkdownTransform.sections: depth must be a heading depth 1-6, got ${options.depth}`);
+		const length = root.children.length;
+		const start = options.start ?? 0;
+		const end = options.end ?? length;
+		if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end > length || start > end) throw new RangeError(`MarkdownTransform.sections: invalid window start=${start} end=${end} for ${length} children`);
+		const spans = [];
+		for (const bound of rootHeadingBounds(root.children)) {
+			if (bound.index < start || bound.index >= end || bound.heading.depth !== options.depth) continue;
+			spans.push({
+				heading: bound.heading,
+				headingIndex: bound.index,
+				end: Math.min(bound.end, end)
+			});
+		}
+		return spans;
+	}
+};
+const isHeadingDepth = (value) => Number.isInteger(value) && value >= 1 && value <= 6;
+function mapNode(node, handlers) {
+	let current = node;
+	if ("children" in node) {
+		const children = node.children;
+		let next;
+		for (let index = 0; index < children.length; index += 1) {
+			const child = children[index];
+			const mapped = mapNode(child, handlers);
+			if (next === void 0 && mapped !== child) next = children.slice(0, index);
+			next?.push(mapped);
+		}
+		if (next !== void 0) {
+			const ctor = node.constructor;
+			current = new ctor({
+				...node,
+				children: next
+			}, { disableChecks: true });
+		}
+	}
+	const handler = handlers[current.type];
+	return handler === void 0 ? current : handler(current);
+}
+
+//#endregion
+export { MarkdownTransform };

package/Mdast.js

@@ -469,7 +469,56 @@ var Mdast = class Mdast {
 	*   fails with {@link MdastDecodeError}.
 	*/
 	static fromMdast = Effect.fn("Mdast.fromMdast")((input) => Effect.fromResult(Mdast.fromMdastResult(input)));
+	/**
+	* The plain-text content of a node, defined as `mdast-util-to-string`
+	* applied to the node's {@link Mdast.toMdast} projection.
+	*
+	* @remarks
+	* A node carrying a string `value` yields it (an `html` node only when
+	* `includeHtml`); an `image` or `imageReference` yields its non-empty
+	* `alt` when `includeImageAlt`; a node with children yields the
+	* concatenation of its children's text; anything else — a `break`, a
+	* `thematicBreak`, a `definition` — yields `""`. Both options default to
+	* `true`. Pure and total.
+	*
+	* **Values are read as the projection spells them.** The one value the
+	* projection changes is a `code` node's: this package keeps the final line
+	* ending of a code block's content, plain mdast does not, so `toText`
+	* strips it exactly as {@link Mdast.toMdast} does — `"let x"`, not
+	* `"let x\n"`, for a fenced block holding one line.
+	*
+	* This is the remark-ecosystem derivation, and it deliberately differs
+	* from the display derivation behind `DocumentHeading.text` and
+	* `DocumentSection.text`, which render a hard break as a space and drop
+	* raw HTML. Reach for `toText` when matching what remark tooling computes
+	* (slugs, search indexes); reach for the document accessors for display.
+	*
+	* The walk recurses once per nesting level. Every tree `Markdown.parse` or
+	* `Mdast.fromMdast` produces stays within the package's nesting cap, but a
+	* hand-built tree nested far deeper than that can overflow the call stack.
+	*
+	* @param node - The node to flatten.
+	* @param options - Optional {@link MdastToTextOptions}.
+	* @returns The node's text content.
+	*/
+	static toText(node, options) {
+		return nodeText(node, options?.includeImageAlt ?? true, options?.includeHtml ?? true);
+	}
 };
+/** `mdast-util-to-string`'s `one`, over the node classes as `toMdast` projects them. */
+function nodeText(node, includeImageAlt, includeHtml) {
+	if ("value" in node) {
+		if (node.type === "html") return includeHtml ? node.value : "";
+		return node.type === "code" ? stripFinalLineEnding(node.value) : node.value;
+	}
+	if (includeImageAlt && "alt" in node && node.alt) return node.alt;
+	if ("children" in node) {
+		let text = "";
+		for (const child of node.children) text += nodeText(child, includeImageAlt, includeHtml);
+		return text;
+	}
+	return "";
+}
 
 //#endregion
 export { Mdast, MdastDecodeError };

package/index.d.ts

@@ -1204,11 +1204,20 @@ export declare class Markdown {
    */
   static readonly parsePhrasing: (text: string, options?: MarkdownParseOptions | undefined) => Effect.Effect<readonly PhrasingContent[], MarkdownParseError, never>;
   /**
-   * Serialize a {@link Root} tree to canonical markdown, synchronously, as a
-   * `Result`. The pure primitive twin of {@link Markdown.stringify}, on the
-   * same terms as {@link Markdown.parseResult}.
+   * Serialize a {@link Root} tree, or a single {@link (FlowContent:type)} node, to
+   * canonical markdown, synchronously, as a `Result`. The pure primitive twin
+   * of {@link Markdown.stringify}, on the same terms as
+   * {@link Markdown.parseResult}.
    *
    * @remarks
+   * **A single flow node is defined as its one-child document**: passing
+   * `node` is exactly `stringifyResult(Root.make({ children: [node] }))` —
+   * the same code path, the same trailing `\n`, the same canonical choices.
+   * This lets a caller serialize one block (a table, a section's paragraph,
+   * an MDX flow element) without building the wrapper by hand.
+   * `Frontmatter` and `MdxjsEsm` are deliberately not admitted alone — each
+   * is meaningful only at a document's root — so wrap them in a `Root`.
+   *
    * Canonical serialization: fidelity fields (marker characters, fence
    * style, heading spelling) win when present; documented canonical
    * defaults apply when absent. One default surprises: a language-less
@@ -1291,15 +1300,15 @@ export declare class Markdown {
    * trip on a tree nesting past the depth cap fails, and only synthesized
    * or decoded trees can nest that far.
    *
-   * @param root - The document tree to serialize.
+   * @param node - The document tree, or a single flow node, to serialize.
    * @returns A `Result` succeeding with markdown source, or failing with
    *   {@link MarkdownStringifyError}.
    */
-  static stringifyResult(root: Root): Result.Result<string, MarkdownStringifyError>;
+  static stringifyResult(node: Root | FlowContent): Result.Result<string, MarkdownStringifyError>;
   /**
-   * Serialize a {@link Root} tree to canonical markdown. Defined in terms of
-   * {@link Markdown.stringifyResult} — synchronous callers can use that
-   * variant directly.
+   * Serialize a {@link Root} tree, or a single {@link (FlowContent:type)} node, to
+   * canonical markdown. Defined in terms of {@link Markdown.stringifyResult}
+   * — synchronous callers can use that variant directly.
    *
    * @remarks
    * The canonical form is a **stability commitment** and safe to assert
@@ -1315,11 +1324,14 @@ export declare class Markdown {
    * `escapeStyle`, an emitter instruction rather than a source spelling,
    * which the boundary admits.
    *
-   * @param root - The document tree to serialize.
+   * A single flow node serializes exactly as its one-child document does;
+   * see {@link Markdown.stringifyResult}.
+   *
+   * @param node - The document tree, or a single flow node, to serialize.
    * @returns An `Effect` that succeeds with markdown source, or fails with
    *   {@link MarkdownStringifyError}.
    */
-  static readonly stringify: (root: Root) => Effect.Effect<string, MarkdownStringifyError, never>;
+  static readonly stringify: (node: Root | FlowContent) => Effect.Effect<string, MarkdownStringifyError, never>;
   /**
    * A `Schema<Root, string>` decoding markdown source into a {@link Root}
    * tree and encoding a tree back to canonical markdown via
@@ -2661,6 +2673,251 @@ export declare class MarkdownFormat {
   static readonly modifyToString: (document: MarkdownDocument, target: MarkdownNode, replacement: string | MarkdownNode) => Effect.Effect<string, MarkdownModificationError, never>;
 }
 //#endregion
+//#region src/MarkdownTransform.d.ts
+/**
+ * The node `type` tags whose handler may change the node's type — the
+ * phrasing-only types, i.e. every member of `PhrasingContent` that is
+ * not also flow content.
+ *
+ * @remarks
+ * `html` is excluded: an `html` node is both phrasing and flow content, so it
+ * can sit in a `Root`, `Blockquote` or `ListItem` child list, where only flow
+ * content is valid. Its handler must therefore return an `Html`.
+ *
+ * @public
+ */
+type MarkdownPhrasingOnlyType = Exclude<PhrasingContent, FlowContent>["type"];
+/**
+ * The handler table for `MarkdownTransform.map`: at most one function
+ * per node `type` tag, each receiving the node narrowed to its class.
+ *
+ * @remarks
+ * A handler for a phrasing-only type (see {@link MarkdownPhrasingOnlyType})
+ * may return any {@link (PhrasingContent:type)} — turning a `link` into a
+ * `linkReference`, say. That is sound because every parent of a phrasing
+ * node holds `PhrasingContent` children, so any phrasing node is valid in its
+ * place. Every other handler must return a node of its own type, which keeps
+ * `map` total: no handler can put a node where its parent forbids it.
+ *
+ * @public
+ */
+type MarkdownTransformHandlers = { readonly [T in MarkdownNodeType]?: (node: MarkdownNodeOfType<T>) => T extends MarkdownPhrasingOnlyType ? PhrasingContent : MarkdownNodeOfType<T>; };
+/**
+ * What `MarkdownTransform.map` returns for an input of type `N`: any
+ * `PhrasingContent` when `N` is phrasing-only (its handler may change
+ * its type), otherwise `N` itself.
+ *
+ * @public
+ */
+type MarkdownTransformResult<N extends MarkdownNode> = N extends Exclude<PhrasingContent, FlowContent> ? PhrasingContent : N;
+/**
+ * Options for {@link MarkdownTransform.shiftHeadings}: the inclusive depth
+ * range shifted headings are clamped into.
+ *
+ * @public
+ */
+interface ShiftHeadingsOptions {
+  /** The shallowest depth a shifted heading may take. Defaults to `1`. */
+  readonly min?: HeadingDepth;
+  /** The deepest depth a shifted heading may take. Defaults to `6`. */
+  readonly max?: HeadingDepth;
+}
+/**
+ * Options for {@link MarkdownTransform.sections}: the heading depth to match
+ * and the window of `root.children` indexes to search.
+ *
+ * @public
+ */
+interface SectionSpanOptions {
+  /** The exact heading depth to match. */
+  readonly depth: HeadingDepth;
+  /** The first child index searched, inclusive. Defaults to `0`. */
+  readonly start?: number;
+  /** The child index the search stops at, exclusive. Defaults to `root.children.length`. */
+  readonly end?: number;
+}
+/**
+ * A root-level section located by index: the heading, its index in
+ * `root.children`, and the exclusive index its section ends at. The body is
+ * the children at `[headingIndex + 1, end)`.
+ *
+ * @public
+ */
+interface SectionSpan {
+  readonly heading: Heading;
+  readonly headingIndex: number;
+  readonly end: number;
+}
+/**
+ * Pure, total tree-to-tree transforms over the markdown node classes. Not
+ * instantiable.
+ *
+ * @remarks
+ * Every method returns a plain value — none has an error channel. They work
+ * on a tree, never on source text, so they compose with
+ * {@link Markdown.stringify} for output and with each other; offset-splice
+ * editing stays the job of `MarkdownFormat` and `MarkdownEdit`.
+ *
+ * @example
+ * ```ts
+ * import { LinkReference, Markdown, MarkdownTransform } from "@effected/markdown";
+ * import { Result } from "effect";
+ *
+ * const parsed = Markdown.parseResult("# Title\n\nSee [docs](https://example.com).\n");
+ * if (Result.isSuccess(parsed)) {
+ *   const shifted = MarkdownTransform.shiftHeadings(parsed.success, 1);
+ *   const rewritten = MarkdownTransform.map(shifted, {
+ *     link: (link) =>
+ *       LinkReference.make({ identifier: "docs", referenceType: "full", children: link.children }),
+ *   });
+ *   Markdown.stringifyResult(rewritten); // "## Title\n\nSee [docs][docs].\n"
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class MarkdownTransform {
+  private constructor();
+  /**
+   * Rebuild a tree by applying `handlers` to its nodes, bottom-up.
+   *
+   * @remarks
+   * **Walk order is a contract:** post-order, children left to right. A
+   * handler sees its node with its children ALREADY transformed, and
+   * handlers are called in document order of the nodes' closing positions,
+   * so a stateful handler can rely on it — deduplicating while keeping the
+   * first occurrence, or remembering the last paragraph seen. The input
+   * node itself is visited last.
+   *
+   * **Structural sharing:** a subtree no handler changed is returned as the
+   * same instance (`===`), so `map(node, {})` returns `node`. A parent whose
+   * children changed is rebuilt with only `children` swapped — every other
+   * field, including `position`, kept as it was. A rebuilt parent therefore
+   * carries its ORIGINAL `position`: offsets into the pre-transform source,
+   * which no longer describe the transformed tree.
+   *
+   * **Handler typing keeps the map total.** A handler for a phrasing-only
+   * type ({@link MarkdownPhrasingOnlyType}) may return any phrasing node —
+   * a `link` may become a `linkReference` — because every parent of a
+   * phrasing node holds phrasing children. Every other handler must return a
+   * node of its own type. `html` is the one phrasing type excluded from the
+   * type-changing set: it is a member of BOTH the phrasing and the flow
+   * unions, so an `html` node can be a child of a `Root`, `Blockquote` or
+   * `ListItem`, where only flow content is valid — its handler must return
+   * an `Html`, and `map` of an `Html` returns an `Html`. See
+   * {@link MarkdownTransformHandlers}. A handler that throws propagates the
+   * exception unchanged; `map` has no error channel of its own.
+   *
+   * The walk recurses once per nesting level. Every tree `Markdown.parse` or
+   * `Mdast.fromMdast` produces stays within the package's nesting cap, but a
+   * hand-built tree nested far deeper than that can overflow the call stack.
+   *
+   * **Two signatures.** This one covers every node whose handler cannot
+   * change its type — a `Root`, any flow node, a list item, a table row or
+   * cell, an `html` node — and returns `N` itself, so a generic caller
+   * constrained to, say, `Root | FlowContent` gets its own type parameter
+   * back. A lone phrasing-only node resolves to the second signature, whose
+   * result widens to `PhrasingContent`.
+   *
+   * @param node - The node to transform — typically a {@link Root}.
+   * @param handlers - At most one function per node `type` tag.
+   * @returns The transformed node, of the input's own type: `node` itself
+   *   when nothing changed.
+   */
+  static map<N extends Exclude<MarkdownNode, Exclude<PhrasingContent, FlowContent>>>(node: N, handlers: MarkdownTransformHandlers): N;
+  /**
+   * Rebuild a tree by applying `handlers` to its nodes, bottom-up — the
+   * signature for any node, including a lone phrasing-only node whose own
+   * handler may change its type.
+   *
+   * @remarks
+   * Walk order, structural sharing, handler typing and the recursion limit
+   * are exactly as documented on the first signature. The difference is the
+   * result type, {@link MarkdownTransformResult}: for a phrasing-only node
+   * (a `link`, `text`, `emphasis`, ...) it is any `PhrasingContent`, since
+   * that node's handler may return, say, a `linkReference` for a `link`. For
+   * every other node it is `N`, but a caller holding a node of a known
+   * non-phrasing type resolves to the first signature, which returns `N`
+   * without the conditional type.
+   *
+   * @param node - Any node.
+   * @param handlers - At most one function per node `type` tag.
+   * @returns The transformed node: `node` itself when nothing changed.
+   */
+  static map<N extends MarkdownNode>(node: N, handlers: MarkdownTransformHandlers): MarkdownTransformResult<N>;
+  /**
+   * Shift every heading's depth by `by`, clamped into `[min, max]`.
+   *
+   * @remarks
+   * The new depth is `clamp(depth + by, min ?? 1, max ?? 6)`. A heading
+   * whose new depth exceeds 2 loses `headingStyle: "setext"` (the key is
+   * omitted), since setext spells depths 1 and 2 only; it then serializes
+   * as ATX. A heading whose depth does not change, and needs no setext
+   * drop, keeps its identity; structural sharing follows
+   * {@link MarkdownTransform.(map:1)}, on which this is built. Accepts any node,
+   * including a lone {@link Heading}.
+   *
+   * Built on `map`, it recurses the same way: a hand-built tree nested far
+   * deeper than anything `Markdown.parse` or `Mdast.fromMdast` produces can
+   * overflow the call stack.
+   *
+   * @param node - The node whose headings to shift.
+   * @param by - The signed depth offset; must be an integer.
+   * @param options - Optional {@link ShiftHeadingsOptions} clamp bounds.
+   * @returns The node with headings shifted.
+   * @throws `RangeError` when `by` is not an integer, or `min` / `max` is not
+   *   a heading depth or `min > max` — a wiring error, not a data error.
+   */
+  static shiftHeadings<N extends MarkdownNode>(node: N, by: number, options?: ShiftHeadingsOptions): N;
+  /**
+   * Locate the root-level sections of one heading depth by child index —
+   * no source text needed, so it works on a tree a
+   * `MarkdownTransform.map` has reshaped.
+   *
+   * @remarks
+   * Returns the root-level headings of exactly `depth` whose index lies in
+   * `[start, end)`, in document order. Each section ends at the next
+   * root-level heading of equal or shallower depth, or at `end` — the same
+   * boundary rule as `MarkdownDocument.sections`, from one shared
+   * implementation. The window is what lets a caller nest: find the depth-2
+   * blocks, then the depth-3 sections inside one block's
+   * `[headingIndex + 1, end)`.
+   *
+   * **A shallower heading ends a section too.** Querying depth 2 on
+   * `## Features`, a list, a stray `# Top` and another list yields one span
+   * whose `end` is the `# Top` heading's index, so neither `# Top` nor the
+   * list after it belongs to the section. That is the outline reading. A
+   * caller that wants each section to run to the next heading of the SAME
+   * depth (slicing a changeset or changelog by entry, where a stray H1 is
+   * content) computes each body's end from the next span's `headingIndex`
+   * instead, or the window's end for the last span, as in the example.
+   *
+   * @example
+   * Bodies that run to the next same-depth heading:
+   *
+   * ```ts
+   * import { Markdown, MarkdownTransform } from "@effected/markdown";
+   * import { Result } from "effect";
+   *
+   * const root = Result.getOrThrow(Markdown.parseResult("## Features\n\n- a\n\n# Top\n\n- b\n"));
+   * const spans = MarkdownTransform.sections(root, { depth: 2 });
+   * // spans[0].end === 2: the outline section stops at `# Top`
+   * const bodies = spans.map((span, index) =>
+   *   root.children.slice(span.headingIndex + 1, spans[index + 1]?.headingIndex ?? root.children.length),
+   * );
+   * // bodies[0] holds the first list, `# Top` and the second list
+   * ```
+   *
+   * @param root - The tree whose root-level headings delimit sections.
+   * @param options - The {@link SectionSpanOptions} depth and window.
+   * @returns The matching {@link SectionSpan}s, in document order.
+   * @throws `RangeError` when `depth` is not an integer from 1 to 6, when
+   *   `start` or `end` is not an integer in `[0, root.children.length]`, or
+   *   when `start > end`.
+   */
+  static sections(root: Root, options: SectionSpanOptions): ReadonlyArray<SectionSpan>;
+}
+//#endregion
 //#region src/MarkdownVisitor.d.ts
 /**
  * The discriminated union of markdown visitor events, in document pre-order.
@@ -2872,6 +3129,17 @@ interface MdastNode {
   readonly type: string;
   readonly [key: string]: unknown;
 }
+/**
+ * Options for {@link Mdast.toText}, matching `mdast-util-to-string`'s.
+ *
+ * @public
+ */
+interface MdastToTextOptions {
+  /** Whether an `image` or `imageReference` contributes its `alt` text. Defaults to `true`. */
+  readonly includeImageAlt?: boolean;
+  /** Whether an `html` node contributes its raw value. Defaults to `true`. */
+  readonly includeHtml?: boolean;
+}
 declare const MdastDecodeError_base: Schema.Class<MdastDecodeError, Schema.TaggedStruct<"MdastDecodeError", {
   /** The structured schema issue. Never a string. */
   readonly issue: Schema.Defect;
@@ -2993,6 +3261,39 @@ export declare class Mdast {
    *   fails with {@link MdastDecodeError}.
    */
   static readonly fromMdast: (input: unknown) => Effect.Effect<Root, MdastDecodeError, never>;
+  /**
+   * The plain-text content of a node, defined as `mdast-util-to-string`
+   * applied to the node's {@link Mdast.toMdast} projection.
+   *
+   * @remarks
+   * A node carrying a string `value` yields it (an `html` node only when
+   * `includeHtml`); an `image` or `imageReference` yields its non-empty
+   * `alt` when `includeImageAlt`; a node with children yields the
+   * concatenation of its children's text; anything else — a `break`, a
+   * `thematicBreak`, a `definition` — yields `""`. Both options default to
+   * `true`. Pure and total.
+   *
+   * **Values are read as the projection spells them.** The one value the
+   * projection changes is a `code` node's: this package keeps the final line
+   * ending of a code block's content, plain mdast does not, so `toText`
+   * strips it exactly as {@link Mdast.toMdast} does — `"let x"`, not
+   * `"let x\n"`, for a fenced block holding one line.
+   *
+   * This is the remark-ecosystem derivation, and it deliberately differs
+   * from the display derivation behind `DocumentHeading.text` and
+   * `DocumentSection.text`, which render a hard break as a space and drop
+   * raw HTML. Reach for `toText` when matching what remark tooling computes
+   * (slugs, search indexes); reach for the document accessors for display.
+   *
+   * The walk recurses once per nesting level. Every tree `Markdown.parse` or
+   * `Mdast.fromMdast` produces stays within the package's nesting cap, but a
+   * hand-built tree nested far deeper than that can overflow the call stack.
+   *
+   * @param node - The node to flatten.
+   * @param options - Optional {@link MdastToTextOptions}.
+   * @returns The node's text content.
+   */
+  static toText(node: MarkdownNode, options?: MdastToTextOptions): string;
 }
 //#endregion
 //#region src/TomlFrontmatter.d.ts
@@ -3046,5 +3347,5 @@ export declare const TomlFrontmatter: FrontmatterCodec;
  */
 export declare const YamlFrontmatter: FrontmatterCodec;
 //#endregion
-export type { DocumentHeading, DocumentLink, FrontmatterCodec, FrontmatterResolveError, FrontmatterSchemaError, FrontmatterSchemaResolver, FrontmatterWriteError, LinkBearingNode, MarkdownNodeOfType, MarkdownNodeType, MarkdownPath, MarkdownRangeLike, MarkdownSegment, MdastNode, SectionHeadingMatch, SectionQueryOptions };
+export type { DocumentHeading, DocumentLink, FrontmatterCodec, FrontmatterResolveError, FrontmatterSchemaError, FrontmatterSchemaResolver, FrontmatterWriteError, LinkBearingNode, MarkdownNodeOfType, MarkdownNodeType, MarkdownPath, MarkdownPhrasingOnlyType, MarkdownRangeLike, MarkdownSegment, MarkdownTransformHandlers, MarkdownTransformResult, MdastNode, MdastToTextOptions, SectionHeadingMatch, SectionQueryOptions, SectionSpan, SectionSpanOptions, ShiftHeadingsOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -8,9 +8,10 @@ import { MarkdownDiagnostic, MarkdownParseErrorCode } from "./MarkdownDiagnostic
 import { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError } from "./Markdown.js";
 import { DocumentSection, MarkdownDocument } from "./MarkdownDocument.js";
 import { CodeBlockStyle, MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode } from "./MarkdownFormat.js";
+import { MarkdownTransform } from "./MarkdownTransform.js";
 import { MarkdownVisitor, MarkdownVisitorEvent } from "./MarkdownVisitor.js";
 import { Mdast, MdastDecodeError } from "./Mdast.js";
 import { TomlFrontmatter } from "./TomlFrontmatter.js";
 import { YamlFrontmatter } from "./YamlFrontmatter.js";
 
-export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterNewline, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, MdxFlowExpression, MdxJsxAttribute, MdxJsxAttributeContent, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, MdxTextExpression, MdxjsEsm, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterNewline, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit, FrontmatterValidationError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, MarkdownRange, MarkdownStringifyError, MarkdownTransform, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, MdxFlowExpression, MdxJsxAttribute, MdxJsxAttributeContent, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, MdxTextExpression, MdxjsEsm, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };

package/internal/sectionBounds.js

@@ -0,0 +1,44 @@
+//#region src/internal/sectionBounds.ts
+/**
+* Every root-level heading of `children`, in document order, paired with the
+* child index its section ends at.
+*/
+const rootHeadingBounds = (children) => {
+	const headings = [];
+	for (let index = 0; index < children.length; index += 1) {
+		const block = children[index];
+		if (block !== void 0 && block.type === "heading") headings.push({
+			index,
+			node: block
+		});
+	}
+	const nextByDepth = [
+		void 0,
+		void 0,
+		void 0,
+		void 0,
+		void 0,
+		void 0,
+		void 0
+	];
+	const bounds = new Array(headings.length);
+	for (let index = headings.length - 1; index >= 0; index -= 1) {
+		const current = headings[index];
+		if (current === void 0) continue;
+		let boundary;
+		for (let depth = 1; depth <= current.node.depth; depth += 1) {
+			const candidate = nextByDepth[depth];
+			if (candidate !== void 0 && (boundary === void 0 || candidate < boundary)) boundary = candidate;
+		}
+		bounds[index] = {
+			heading: current.node,
+			index: current.index,
+			end: boundary === void 0 ? children.length : headings[boundary]?.index ?? children.length
+		};
+		nextByDepth[current.node.depth] = index;
+	}
+	return bounds;
+};
+
+//#endregion
+export { rootHeadingBounds };

package/internal/stringify.js

@@ -824,21 +824,19 @@ const serializeBlocks = (children, state, tight = false) => {
 	return out;
 };
 /**
-* Serialize a document tree to canonical markdown source.
-*
-* Throws the raw `GuardExceeded` carrier when the tree nests past
-* `MAX_NESTING_DEPTH`; the facade materializes the typed error. Output is
-* empty for an empty root and ends with exactly one newline otherwise.
+* Serialize a root-level block list — the one path behind both a whole
+* `Root` and a lone flow node (`[node]`), so the two cannot diverge. Builds
+* no wrapper node, so nothing here can fail a schema constructor.
 */
-const stringifyTree = (root) => {
+const stringifyBlocks = (children) => {
 	const state = {
 		depth: 0,
 		jsxDepth: 0,
-		mdx: treeContainsMdx(root)
+		mdx: children.some((child) => treeContainsMdx(child))
 	};
-	const body = serializeBlocks(root.children, state);
+	const body = serializeBlocks(children, state);
 	return body === "" ? "" : `${body}\n`;
 };
 
 //#endregion
-export { stringifyTree };
+export { stringifyBlocks };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/markdown",
-	"version": "0.17.0",
+	"version": "0.19.0",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [
@@ -39,9 +39,9 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.17.0",
-		"@effected/toml": "^0.13.0",
-		"@effected/yaml": "^0.21.0",
+		"@effected/jsonc": "^0.18.0",
+		"@effected/toml": "^0.14.0",
+		"@effected/yaml": "^0.22.0",
 		"effect": "^4.0.0"
 	},
 	"peerDependenciesMeta": {