@effected/markdown 0.19.0 → 0.21.0

package/Frontmatter.js

@@ -1,8 +1,8 @@
 import { MarkdownEdit } from "./MarkdownEdit.js";
 import { FrontmatterFormat } from "./MarkdownNode.js";
-import { Effect, Schema } from "effect";
+import { Effect, Option, Schema } from "effect";
 
-//#region src/Frontmatter.ts
+// src/Frontmatter.ts
 /**
 * Indicates that a frontmatter codec was handed a capture of a different
 * format — a yaml codec applied to a `+++` toml capture, for example.
@@ -212,7 +212,7 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	*/
 	static schema(schema, codec) {
 		return (document) => {
-			const node = document.frontmatter;
+			const node = Option.getOrUndefined(document.frontmatter);
 			return node === void 0 ? Effect.fail(new FrontmatterMissingError({ reason: document.hasFrontmatterBlock ? "captureDisabled" : "absent" })) : codec.decode(node).pipe(Effect.flatMap((data) => Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new FrontmatterValidationError({ issue: error.issue }))))));
 		};
 	}
@@ -258,7 +258,7 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	*/
 	static set(schema, codec) {
 		return (document, data) => {
-			const node = document.frontmatter;
+			const node = Option.getOrUndefined(document.frontmatter);
 			if (node !== void 0 && node.format !== codec.format) return Effect.fail(new FrontmatterFormatMismatchError({
 				expected: codec.format,
 				actual: node.format
@@ -303,5 +303,4 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	}
 };
 
-//#endregion
 export { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, MarkdownFrontmatter };

package/FrontmatterResolver.js

@@ -1,6 +1,6 @@
-import { Effect, Result, Schema } from "effect";
+import { Effect, Predicate, Result, Schema } from "effect";
 
-//#region src/FrontmatterResolver.ts
+// src/FrontmatterResolver.ts
 /**
 * A `$schema` declaration referencing a schema by URL — any string containing
 * `://`.
@@ -140,7 +140,6 @@ const parseVersionSegments = (version) => {
 	if (!/^\d+(\.\d+){0,2}$/.test(version)) return;
 	return version.split(".").map((segment) => Number.parseInt(segment, 10));
 };
-const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
 * The `$schema` declaration classifier and the package's one built-in
 * resolver implementation.
@@ -184,7 +183,7 @@ var SchemaResolver = class SchemaResolver {
 				version
 			}));
 		}
-		if (isMapping(value)) return Result.succeed(new SchemaDeclarationInline({ document: value }));
+		if (Predicate.isObject(value)) return Result.succeed(new SchemaDeclarationInline({ document: value }));
 		return Result.fail(new SchemaDeclarationInvalidError({
 			reason: "the declaration is neither a string nor a mapping",
 			value
@@ -206,7 +205,7 @@ var SchemaResolver = class SchemaResolver {
 	*   tolerated, or the typed error.
 	*/
 	static declarationOf(data, options) {
-		if (!isMapping(data) || !Object.hasOwn(data, "$schema")) return options?.requireDeclaration === true ? Result.fail(new SchemaDeclarationMissingError()) : Result.succeed(void 0);
+		if (!Predicate.isObject(data) || !Object.hasOwn(data, "$schema")) return options?.requireDeclaration === true ? Result.fail(new SchemaDeclarationMissingError()) : Result.succeed(void 0);
 		return SchemaResolver.classify(data.$schema);
 	}
 	/**
@@ -267,5 +266,4 @@ var SchemaResolver = class SchemaResolver {
 	}
 };
 
-//#endregion
 export { SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError };

package/FrontmatterSource.js

@@ -2,7 +2,7 @@ import { FrontmatterFormat } from "./MarkdownNode.js";
 import { scanRawFrontmatter } from "./internal/blocks/frontmatter.js";
 import { Effect, Schema } from "effect";
 
-//#region src/FrontmatterSource.ts
+// src/FrontmatterSource.ts
 /**
 * The three line-terminator spellings a fence line may end with. Recorded by
 * {@link FrontmatterSource.split} as fidelity — what the source's fence
@@ -169,5 +169,4 @@ var FrontmatterSource = class {
 	}
 };
 
-//#endregion
 export { FrontmatterNewline, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit };

package/JsonFrontmatter.js

@@ -2,7 +2,7 @@ import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismat
 import { Effect } from "effect";
 import { Jsonc } from "@effected/jsonc";
 
-//#region src/JsonFrontmatter.ts
+// src/JsonFrontmatter.ts
 /**
 * The json frontmatter codec, over `@effected/jsonc`.
 *
@@ -42,5 +42,4 @@ const JsonFrontmatter = {
 	})))
 };
 
-//#endregion
 export { JsonFrontmatter };

package/Markdown.js

@@ -6,7 +6,7 @@ import { stringifyBlocks } from "./internal/stringify.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
 
-//#region src/Markdown.ts
+// src/Markdown.ts
 /**
 * The markdown dialects the parser can be pointed at. `"gfm"` — CommonMark
 * 0.31.2 plus the GitHub extensions (tables, strikethrough, autolink
@@ -426,5 +426,4 @@ var Markdown = class Markdown {
 	static MarkdownFromString = Markdown.fromString();
 };
 
-//#endregion
 export { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError, parsePassResult };

package/MarkdownDiagnostic.js

@@ -1,7 +1,7 @@
 import { MARKDOWN_PARSE_ERROR_CODES } from "./internal/carriers.js";
 import { Schema } from "effect";
 
-//#region src/MarkdownDiagnostic.ts
+// src/MarkdownDiagnostic.ts
 /**
 * Error codes `Markdown.parse`/`MarkdownDocument.parse` can fail with.
 * Currently exactly one, `"NestingDepthExceeded"`, the hardening-guard trip;
@@ -84,5 +84,4 @@ function lineChar(text, offset) {
 	};
 }
 
-//#endregion
 export { MarkdownDiagnostic, MarkdownParseErrorCode };

package/MarkdownDocument.js

@@ -6,9 +6,9 @@ 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";
+import { Effect, Option, Result, Schema } from "effect";
 
-//#region src/MarkdownDocument.ts
+// src/MarkdownDocument.ts
 /**
 * A heading-delimited span from {@link MarkdownDocument.sections}: the
 * heading, its depth, the source `range` the section occupies and the
@@ -167,19 +167,26 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	definitions: Schema.ReadonlyMap(Schema.String, Definition)
 }) {
 	/**
-	* The document's frontmatter capture, or `undefined` when there is none.
+	* The document's frontmatter capture, or `Option.none()` when there is
+	* none.
 	*
 	* @remarks
 	* Derived from the tree rather than stored: a {@link Frontmatter} node can
 	* only ever sit at the head of `root.children` (the capture fires at most
 	* once, at offset 0), so the tree is the single source of truth and the
-	* accessor can never disagree with it. `undefined` covers both a document
-	* with no frontmatter block and one parsed with the capture toggle off —
-	* {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
+	* accessor can never disagree with it. `Option.none()` covers both a
+	* document with no frontmatter block and one parsed with the capture toggle
+	* off — {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
+	*
+	* An `Option` rather than `Frontmatter | undefined` because this is a
+	* lookup that can miss, and the kit's lookups return `Option` — the same
+	* shape as the sibling format packages' tree lookups (`JsoncNode.find`,
+	* `YamlNode.find`). A derived getter is a lookup, not a data field: it
+	* recomputes from the tree on every access.
 	*/
 	get frontmatter() {
 		const head = this.root.children[0];
-		return head !== void 0 && head.type === "frontmatter" ? head : void 0;
+		return head !== void 0 && head.type === "frontmatter" ? Option.some(head) : Option.none();
 	}
 	/**
 	* Whether the source opens with a well-formed frontmatter block —
@@ -187,10 +194,10 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	*
 	* @remarks
 	* The structural signal that disambiguates the `frontmatter` accessor's
-	* `undefined`: capture is opt-in (`MarkdownParseOptions.frontmatter`
+	* `Option.none()`: capture is opt-in (`MarkdownParseOptions.frontmatter`
 	* defaults off), so a document whose source visibly starts with `---` can
 	* still carry no capture node — spec-correct CommonMark reads the fences as
-	* a thematic break plus content. `frontmatter === undefined` with
+	* a thematic break plus content. An empty `frontmatter` with
 	* `hasFrontmatterBlock === true` means exactly "parsed with capture off";
 	* with `false` it means the source genuinely has no block.
 	*
@@ -274,11 +281,12 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	* document repeatedly should bind `document.sections` once instead.
 	*
 	* @param options - Depth restriction.
-	* @returns The first matching section, or `undefined`.
+	* @returns The first matching section, or `Option.none()` when no section
+	*   matches.
 	*/
 	firstSection(options) {
 		const depth = options?.depth;
-		return this.sections.find((section) => depth === void 0 || section.depth === depth);
+		return Option.fromUndefinedOr(this.sections.find((section) => depth === void 0 || section.depth === depth));
 	}
 	/**
 	* The first section whose heading matches, in document order.
@@ -295,7 +303,8 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	*
 	* @param match - A string, a RegExp, or a predicate.
 	* @param options - Depth restriction, applied before matching.
-	* @returns The first matching section, or `undefined`.
+	* @returns The first matching section, or `Option.none()` when no section
+	*   matches.
 	*/
 	sectionByHeading(match, options) {
 		const depth = options?.depth;
@@ -303,7 +312,7 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 			match.lastIndex = 0;
 			return match.test(section.text.trim());
 		} : (section) => match(section.text, section);
-		return this.sections.find((section) => (depth === void 0 || section.depth === depth) && matches(section));
+		return Option.fromUndefinedOr(this.sections.find((section) => (depth === void 0 || section.depth === depth) && matches(section)));
 	}
 	/**
 	* Every link-bearing node in the document, in document order: links,
@@ -343,7 +352,7 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 		return entries;
 	}
 	find(selector) {
-		return findInTree(this.root, 0, selectorPredicate(selector));
+		return Option.fromUndefinedOr(findInTree(this.root, 0, selectorPredicate(selector)));
 	}
 	findAll(selector) {
 		const predicate = selectorPredicate(selector);
@@ -391,5 +400,4 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	static parse = Effect.fn("MarkdownDocument.parse")((text, options) => Effect.fromResult(MarkdownDocument.parseResult(text, options)));
 };
 
-//#endregion
 export { DocumentSection, MarkdownDocument };

package/MarkdownEdit.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 
-//#region src/MarkdownEdit.ts
+// src/MarkdownEdit.ts
 /**
 * A range within a markdown document, expressed as a zero-based character
 * `offset` and a `length` in UTF-16 code units. Pass to `MarkdownFormat.format`
@@ -52,5 +52,4 @@ var MarkdownEdit = class extends Schema.Class("MarkdownEdit")({
 	}
 };
 
-//#endregion
 export { MarkdownEdit, MarkdownRange };

package/MarkdownFormat.js

@@ -3,7 +3,7 @@ import { BulletChar, EmphasisChar, FenceChar, HeadingStyle, Paragraph, Root, Tex
 import { Markdown, MarkdownDialect, MarkdownParseOptions } from "./Markdown.js";
 import { Effect, Result, Schema } from "effect";
 
-//#region src/MarkdownFormat.ts
+// src/MarkdownFormat.ts
 /**
 * The two ways CommonMark spells a code block: `fenced` (a backtick or tilde
 * fence) and `indented` (four-space indentation).
@@ -511,5 +511,4 @@ var MarkdownFormat = class MarkdownFormat {
 	});
 };
 
-//#endregion
 export { CodeBlockStyle, MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode };

package/MarkdownNode.js

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 
-//#region src/MarkdownNode.ts
+// src/MarkdownNode.ts
 /**
 * A single point in a source document: 1-based `line` and `column`, 0-based
 * `offset`.
@@ -854,5 +854,4 @@ const MarkdownNode = Schema.suspend(() => Schema.Union([
 	TableContent
 ]));
 
-//#endregion
 export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterFormat, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, MarkdownNode, MdxFlowExpression, MdxJsxAttribute, MdxJsxAttributeContent, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, MdxTextExpression, MdxjsEsm, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar };

package/MarkdownTransform.js

@@ -1,6 +1,6 @@
 import { rootHeadingBounds } from "./internal/sectionBounds.js";
 
-//#region src/MarkdownTransform.ts
+// src/MarkdownTransform.ts
 /**
 * Pure, total tree-to-tree transforms over the markdown node classes. Not
 * instantiable.
@@ -163,5 +163,4 @@ function mapNode(node, handlers) {
 	return handler === void 0 ? current : handler(current);
 }
 
-//#endregion
 export { MarkdownTransform };

package/MarkdownVisitor.js

@@ -1,7 +1,7 @@
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { Data, Stream } from "effect";
 
-//#region src/MarkdownVisitor.ts
+// src/MarkdownVisitor.ts
 /**
 * Constructors and matchers for the `MarkdownVisitorEvent` union (e.g.
 * `MarkdownVisitorEvent.Enter({ node, path, depth })`,
@@ -11,8 +11,9 @@ import { Data, Stream } from "effect";
 */
 const MarkdownVisitorEvent = Data.taggedEnum();
 /**
-* Walks a parsed markdown tree as a lazy `Stream` of `Enter`/`Exit` events in
-* document pre-order. Not instantiable.
+* Walks a parsed markdown tree as a lazy sequence of `Enter`/`Exit` events in
+* document pre-order — synchronously with {@link MarkdownVisitor.walk}, or as
+* a `Stream` with {@link MarkdownVisitor.visit}. Not instantiable.
 *
 * @example
 * ```ts
@@ -32,9 +33,52 @@ const MarkdownVisitorEvent = Data.taggedEnum();
 *
 * @public
 */
-var MarkdownVisitor = class {
+var MarkdownVisitor = class MarkdownVisitor {
 	constructor() {}
 	/**
+	* Walk `root` synchronously, as a lazy `Iterable` of `MarkdownVisitorEvent`
+	* in document pre-order: `Enter` and `Exit` for every node including the
+	* root and every leaf. The primitive {@link MarkdownVisitor.visit} is
+	* defined in terms of, so the two yield the same events in the same order.
+	*
+	* @remarks
+	* For callers that cannot suspend — a lint rule whose host calls it
+	* synchronously, a getter, a non-Effect adapter. Events are produced on
+	* demand: a `for…of` that `break`s stops the walk without visiting the
+	* rest of the tree. The iterable is re-iterable — every `[Symbol.iterator]()`
+	* call starts a fresh walk from the root, so binding the result once and
+	* iterating it twice walks the tree twice, independently.
+	*
+	* Not named `walkResult`: it returns no `Result`, and the walk has no
+	* failure channel to put in one. A hand-constructed tree nested past the
+	* depth cap surfaces as a terminal `MarkdownVisitorEvent` `Error` event
+	* carrying a `NestingDepthExceeded` {@link MarkdownDiagnostic}, after which
+	* nothing is yielded — the same posture as `visit`. A tree produced by
+	* `Markdown.parse` or decoded by `Mdast.fromMdast` can never trip it.
+	*
+	* @example
+	* ```ts
+	* import { Markdown, MarkdownVisitor } from "@effected/markdown";
+	* import { Result } from "effect";
+	*
+	* const root = Result.getOrThrow(Markdown.parseResult("# Hi\n\ntext\n"));
+	* const entered: Array<string> = [];
+	* for (const event of MarkdownVisitor.walk(root)) {
+	*   if (event._tag === "Enter") entered.push(event.node.type);
+	* }
+	* console.log(entered);
+	* // => ["root", "heading", "text", "paragraph", "text"]
+	* ```
+	*
+	* @param root - The tree to walk.
+	* @returns A lazy, re-iterable `Iterable` of `MarkdownVisitorEvent`.
+	*/
+	static walk(root) {
+		return { [Symbol.iterator]() {
+			return walkNode(root, [], 0);
+		} };
+	}
+	/**
 	* Create a lazy `Stream` of `MarkdownVisitorEvent` walking `root` in
 	* document pre-order: `Enter` and `Exit` for every node including the
 	* root and every leaf. Events are produced on demand, so combining with
@@ -44,28 +88,24 @@ var MarkdownVisitor = class {
 	* @remarks
 	* Infallible at the type level. A tree produced by `Markdown.parse` can
 	* never trip the walk's depth guard — the parser refuses deeper input —
-	* but a decoded foreign tree (`Mdast.fromMdast`) can; the trip surfaces
-	* as a terminal `MarkdownVisitorEvent` `Error` event carrying a
-	* `NestingDepthExceeded` {@link MarkdownDiagnostic}, mirroring the typed
-	* failure `Markdown.stringify` produces for the same tree.
+	* and neither can a decoded foreign tree (`Mdast.fromMdast`), because the
+	* decode boundary refuses it first; only a hand-constructed tree can trip
+	* the guard. The trip surfaces as a terminal `MarkdownVisitorEvent`
+	* `Error` event carrying a `NestingDepthExceeded` {@link MarkdownDiagnostic},
+	* mirroring the typed failure `Markdown.stringify` produces for the same
+	* tree.
+	*
+	* Defined as `Stream.fromIterable(MarkdownVisitor.walk(root))`: every run
+	* of the stream walks afresh, and the two forms never diverge.
 	*
 	* @param root - The tree to walk.
 	* @returns A lazy `Stream` of `MarkdownVisitorEvent`, infallible at the type
 	*   level.
 	*/
 	static visit(root) {
-		return Stream.fromIterable(walkIterable(root));
+		return Stream.fromIterable(MarkdownVisitor.walk(root));
 	}
 };
-/** Lazy per-subscription iterable so each run of the stream walks afresh. */
-function walkIterable(root) {
-	return { [Symbol.iterator]() {
-		return walk(root)[Symbol.iterator]();
-	} };
-}
-function* walk(root) {
-	yield* walkNode(root, [], 0);
-}
 function* walkNode(node, path, depth) {
 	if (depth > 256) {
 		yield MarkdownVisitorEvent.Error({
@@ -105,5 +145,4 @@ function* walkNode(node, path, depth) {
 	});
 }
 
-//#endregion
 export { MarkdownVisitor, MarkdownVisitorEvent };

package/Mdast.js

@@ -1,8 +1,9 @@
 import { Root } from "./MarkdownNode.js";
 import { unescapeString } from "./internal/unescape.js";
-import { Effect, Result, Schema } from "effect";
+import { GuardExceeded, isGuardExceeded } from "./internal/carriers.js";
+import { Effect, Predicate, Result, Schema, SchemaIssue } from "effect";
 
-//#region src/Mdast.ts
+// src/Mdast.ts
 /**
 * Indicates that foreign mdast input failed to decode into the package's
 * node classes.
@@ -286,10 +287,9 @@ const admittedFields = {
 	mdxTextExpression: ["value"],
 	mdxjsEsm: ["value"]
 };
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const completePoint = (value) => isRecord(value) && typeof value.line === "number" && typeof value.column === "number" && typeof value.offset === "number";
+const completePoint = (value) => Predicate.isObject(value) && typeof value.line === "number" && typeof value.column === "number" && typeof value.offset === "number";
 const normalizePosition = (value) => {
-	if (isRecord(value) && completePoint(value.start) && completePoint(value.end)) {
+	if (Predicate.isObject(value) && completePoint(value.start) && completePoint(value.end)) {
 		const start = value.start;
 		const end = value.end;
 		return {
@@ -307,8 +307,9 @@ const normalizePosition = (value) => {
 	}
 	return sentinelPosition;
 };
-const normalizeNode = (value) => {
-	if (!isRecord(value) || typeof value.type !== "string") return value;
+const normalizeNode = (value, depth = 0) => {
+	if (!Predicate.isObject(value) || typeof value.type !== "string") return value;
+	if (depth > 256) throw new GuardExceeded("NestingDepthExceeded", 256, depth, 0);
 	const type = value.type;
 	const format = frontmatterTypes.get(type);
 	if (format !== void 0) return {
@@ -321,7 +322,7 @@ const normalizeNode = (value) => {
 		type,
 		name: value.name,
 		attributes: Array.isArray(value.attributes) ? value.attributes.map(normalizeMdxAttribute) : value.attributes,
-		children: Array.isArray(value.children) ? value.children.map(normalizeNode) : value.children,
+		children: Array.isArray(value.children) ? value.children.map((child) => normalizeNode(child, depth + 1)) : value.children,
 		position: normalizePosition(value.position)
 	};
 	const admitted = admittedFields[type];
@@ -335,12 +336,12 @@ const normalizeNode = (value) => {
 		const code = normalized.value;
 		normalized.value = code.endsWith("\n") ? code : `${code}\n`;
 	}
-	if (Array.isArray(value.children)) normalized.children = value.children.map(normalizeNode);
+	if (Array.isArray(value.children)) normalized.children = value.children.map((child) => normalizeNode(child, depth + 1));
 	normalized.position = normalizePosition(value.position);
 	return normalized;
 };
 const normalizeMdxAttribute = (value) => {
-	if (!isRecord(value) || typeof value.type !== "string") return value;
+	if (!Predicate.isObject(value) || typeof value.type !== "string") return value;
 	if (value.type === "mdxJsxExpressionAttribute") return {
 		type: "mdxJsxExpressionAttribute",
 		value: value.value,
@@ -353,7 +354,7 @@ const normalizeMdxAttribute = (value) => {
 			name: value.name,
 			position: normalizePosition(value.position)
 		};
-		if (raw !== void 0) normalized.value = isRecord(raw) && raw.type === "mdxJsxAttributeValueExpression" ? {
+		if (raw !== void 0) normalized.value = Predicate.isObject(raw) && raw.type === "mdxJsxAttributeValueExpression" ? {
 			type: "mdxJsxAttributeValueExpression",
 			value: raw.value,
 			position: normalizePosition(raw.position)
@@ -452,12 +453,27 @@ var Mdast = class Mdast {
 	* plain tree built for `Markdown.stringify` can carry it straight in. A
 	* value outside `"canonical" | "literal"` fails the decode typed.
 	*
+	* **Nesting is capped at 256 levels below the root**, the same cap the
+	* parser and `Markdown.stringify` enforce. A tree with any node deeper
+	* than that, leaves included, fails typed with a `SchemaIssue.InvalidValue`
+	* issue before the schema decode runs, so hostile depth is never a defect.
+	* Because leaves count, a document the parser accepts can still be
+	* refused here: `"> ".repeat(255) + "x"` parses, but its `text` leaf sits
+	* at depth 257, and `Markdown.stringify` refuses that tree too.
+	*
 	* @param input - A plain mdast tree, typically a `root`.
 	* @returns A `Result` succeeding with the decoded {@link Root}, or
 	*   failing with {@link MdastDecodeError} carrying the structured issue.
 	*/
 	static fromMdastResult(input) {
-		return Result.mapError(decodeRoot(normalizeNode(input)), (error) => new MdastDecodeError({ issue: error.issue }));
+		let normalized;
+		try {
+			normalized = normalizeNode(input);
+		} catch (error) {
+			if (!isGuardExceeded(error)) throw error;
+			return Result.fail(new MdastDecodeError({ issue: new SchemaIssue.InvalidValue({ message: error.message }) }));
+		}
+		return Result.mapError(decodeRoot(normalized), (error) => new MdastDecodeError({ issue: error.issue }));
 	}
 	/**
 	* Decode foreign plain mdast into the package's node classes. Defined in
@@ -520,5 +536,4 @@ function nodeText(node, includeImageAlt, includeHtml) {
 	return "";
 }
 
-//#endregion
 export { Mdast, MdastDecodeError };

package/README.md

@@ -85,7 +85,7 @@ Every parse has a synchronous twin — `MarkdownDocument.parseResult` and `Markd
 
 ```ts
 import { MarkdownDocument, MarkdownFormat } from "@effected/markdown";
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
 
 const source = `# Release notes
 
@@ -94,7 +94,7 @@ See the [changelog](./CHANGELOG.md).
 
 const program = Effect.gen(function* () {
   const doc = yield* MarkdownDocument.parse(source);
-  const label = doc.find("text")!;
+  const label = Option.getOrThrow(doc.find("text"));
   return yield* MarkdownFormat.modifyToString(doc, label, "Release notes (2026)");
 });
 
@@ -104,7 +104,7 @@ Effect.runPromise(program).then(console.log);
 // See the [changelog](./CHANGELOG.md).
 ```
 
-`find` walks the tree in document pre-order and returns the document's own node, so the match feeds `modify` by identity. Replacements are literal strings or node fragments, and both render through the canonical stringifier, so a modified document re-parses cleanly by construction — you cannot splice in raw markdown that reopens a fence or breaks a table.
+`find` walks the tree in document pre-order and returns the document's own node inside an `Option` — `Option.none()` when nothing matches — so the match feeds `modify` by identity. Replacements are literal strings or node fragments, and both render through the canonical stringifier, so a modified document re-parses cleanly by construction — you cannot splice in raw markdown that reopens a fence or breaks a table.
 
 `MarkdownFormat.format` handles the other half: conservative marker normalization, never content rewriting. It converts heading style, bullet character, emphasis marker, fence character, thematic-break character and code-block style, and skips any conversion that would not be safe rather than attempting it cleverly:
 
@@ -198,11 +198,11 @@ Effect.runPromise(program).then(console.log);
 // [ "./CHANGELOG.md", "https://example.com/docs" ]
 ```
 
-`headings` lists every heading wherever it sits, including inside blockquotes and list items. `sections` are delimited by root-level headings only, and each section's range spans its subsections, so the edit layer can splice a whole section out in one edit. `firstSection` and `sectionByHeading` find one `DocumentSection` without scanning `sections` yourself — the second matches on an exact trimmed heading string, a `RegExp`, or a predicate, and both accept `{ depth }` to restrict to one heading level:
+`headings` lists every heading wherever it sits, including inside blockquotes and list items. `sections` are delimited by root-level headings only, and each section's range spans its subsections, so the edit layer can splice a whole section out in one edit. `firstSection` and `sectionByHeading` find one `DocumentSection` without scanning `sections` yourself — the second matches on an exact trimmed heading string, a `RegExp`, or a predicate, and both accept `{ depth }` to restrict to one heading level. Both return an `Option`, as every lookup in the kit does (the `frontmatter` accessor and `find` too):
 
 ```ts
 import { MarkdownDocument } from "@effected/markdown";
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
 
 const source = `# Changelog
 
@@ -217,7 +217,10 @@ Initial release.
 
 const program = Effect.gen(function* () {
   const doc = yield* MarkdownDocument.parse(source);
-  return doc.sectionByHeading("1.2.3", { depth: 2 })?.body.trim();
+  return Option.match(doc.sectionByHeading("1.2.3", { depth: 2 }), {
+    onNone: () => "no such release",
+    onSome: (section) => section.body.trim(),
+  });
 });
 
 Effect.runPromise(program).then(console.log);
@@ -226,7 +229,7 @@ Effect.runPromise(program).then(console.log);
 
 `DocumentSection.body` is the section without its heading, and it is deliberately untrimmed — exactly the bytes `bodyRange` describes — so callers write `.body.trim()` when they want the tidy form.
 
-For anything the accessors do not cover, `find` and `findAll` walk the whole tree in document pre-order. A string selector matches the node's `type` and narrows the result — `doc.findAll("heading")` is `ReadonlyArray<Heading>`, `doc.find("table")` is `Table | undefined` — and a type-guard predicate narrows the same way. The nodes come back by identity, so `doc.findAll("heading")[1]` addresses the second heading for `MarkdownFormat.modify` without raw child indexing.
+For anything the accessors do not cover, `find` and `findAll` walk the whole tree in document pre-order. A string selector matches the node's `type` and narrows the result — `doc.findAll("heading")` is `ReadonlyArray<Heading>`, `doc.find("table")` is `Option<Table>` — and a type-guard predicate narrows the same way. The nodes come back by identity, so `doc.findAll("heading")[1]` addresses the second heading for `MarkdownFormat.modify` without raw child indexing.
 
 `MarkdownVisitor.visit` streams the same walk as `Enter`/`Exit` events carrying the node, its child-index path and its depth:
 
@@ -246,6 +249,21 @@ Effect.runPromise(program).then(console.log);
 //   "Exit:text", "Exit:emphasis", "Enter:text", "Exit:text", "Exit:paragraph", "Exit:root" ]
 ```
 
+`MarkdownVisitor.walk` is the same walk as a synchronous, lazy `Iterable` — the primitive `visit` is defined in terms of — for code that cannot suspend, such as a lint rule a host calls synchronously. Each iteration walks afresh from the root, and a `for…of` that `break`s stops the walk:
+
+```ts
+import { Markdown, MarkdownVisitor } from "@effected/markdown";
+import { Result } from "effect";
+
+const root = Result.getOrThrow(Markdown.parseResult("# Title\n\nA *b* c\n"));
+const headings: Array<number> = [];
+for (const event of MarkdownVisitor.walk(root)) {
+  if (event._tag === "Enter" && event.node.type === "heading") headings.push(event.node.depth);
+}
+console.log(headings);
+// [ 1 ]
+```
+
 ## mdast interop
 
 The node classes already use mdast's type names and field shapes; `Mdast.toMdast` strips the fidelity fields this package adds — bullet characters, fence style, ATX-versus-setext spelling — (keeping only a `Text` node's `escapeStyle` when set, see [Literal text](#literal-text)) and emits plain spec-valid mdast JSON that the remark ecosystem consumes directly, including `mdast-util-to-hast` if you want hast:
@@ -364,7 +382,7 @@ To *normalize* an existing document to different choices, use `MarkdownFormat` w
 - `FrontmatterSource` — string-level frontmatter `split`/`join` over the same closed fence grammar, byte-exact boundaries, no parsing of value or body; for bodies the CommonMark engine should not touch.
 - `MarkdownEdit` / `MarkdownRange` (with `applyAll`) — the non-mutating text-edit vocabulary, field-identical to `@effected/jsonc`'s, `@effected/yaml`'s and `@effected/toml`'s.
 - `MarkdownFormat` — `format`/`formatToString` compute conservative marker-normalization edits; `modify`/`modifyToString` replace a node by identity through the canonical stringifier.
-- `MarkdownVisitor` — walk a parsed tree as a lazy `Stream` of `Enter`/`Exit` events with child-index paths and depth.
+- `MarkdownVisitor` — walk a parsed tree as `Enter`/`Exit` events with child-index paths and depth: synchronously as a lazy `Iterable` (`walk`), or as a `Stream` (`visit`).
 - `Mdast` — `toMdast` projects to plain mdast JSON; `fromMdast`/`fromMdastResult` admit a foreign mdast tree with validation.
 - `MarkdownFrontmatter.schema` plus the `YamlFrontmatter`, `TomlFrontmatter` and `JsonFrontmatter` codecs — typed frontmatter decoding over optional per-format peers, with four separately catchable failure modes and a `FrontmatterMissingReason` on the absent one.
 - `SchemaResolver` — classify a frontmatter `$schema` declaration into `ByUrl`/`ByPath`/`Inline`/`ByName` and resolve names against a registry, with no IO and no dependencies.

package/TomlFrontmatter.js

@@ -2,7 +2,7 @@ import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismat
 import { Effect } from "effect";
 import { Toml } from "@effected/toml";
 
-//#region src/TomlFrontmatter.ts
+// src/TomlFrontmatter.ts
 /**
 * The toml frontmatter codec, over `@effected/toml`.
 *
@@ -40,5 +40,4 @@ const TomlFrontmatter = {
 	})))
 };
 
-//#endregion
 export { TomlFrontmatter };

package/YamlFrontmatter.js

@@ -2,7 +2,7 @@ import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismat
 import { Effect } from "effect";
 import { Yaml } from "@effected/yaml";
 
-//#region src/YamlFrontmatter.ts
+// src/YamlFrontmatter.ts
 /**
 * The yaml frontmatter codec, over `@effected/yaml`.
 *
@@ -41,5 +41,4 @@ const YamlFrontmatter = {
 	})))
 };
 
-//#endregion
 export { YamlFrontmatter };