@effected/markdown 0.3.0 → 0.4.1

package/Frontmatter.js

@@ -69,22 +69,43 @@ var FrontmatterEncodeError = class extends Schema.TaggedErrorClass()("Frontmatte
 	}
 };
 /**
+* Why a frontmatter decoder found no capture on a document.
+*
+* @remarks
+* `"absent"` — the source genuinely has no frontmatter block.
+* `"captureDisabled"` — the source opens with a well-formed frontmatter
+* block, but the document carries no capture node: it was parsed without
+* `frontmatter: true` (the toggle defaults off), so spec-correct CommonMark
+* read the fences as ordinary content.
+*
+* @public
+*/
+const FrontmatterMissingReason = Schema.Literals(["absent", "captureDisabled"]);
+/**
 * Indicates that a document handed to a frontmatter decoder carries no
 * frontmatter capture.
 *
 * @remarks
-* Raised when the document genuinely has no frontmatter block — including
-* when it has one in the source but was parsed with the capture toggle off
-* (`MarkdownParseOptions.frontmatter` defaults to `false`). Cause-free: there
-* is nothing to diagnose beyond the absence itself. Consumers wanting
-* optional semantics can `Effect.catchTag("FrontmatterMissingError", ...)`
-* to a default.
+* `reason` distinguishes the two ways this happens: `"absent"` when the
+* source genuinely has no frontmatter block, `"captureDisabled"` when the
+* source opens with one but the document was parsed with the capture toggle
+* off (`MarkdownParseOptions.frontmatter` defaults to `false`) — the fix
+* there is parsing with `frontmatter: true`, not editing the document. The
+* discriminant is computed from the same structural signal
+* `MarkdownDocument.hasFrontmatterBlock` exposes, so the error and the
+* accessor can never disagree.
+*
+* Cause-free: there is nothing to diagnose beyond the absence itself.
+* Consumers wanting optional semantics can
+* `Effect.catchTag("FrontmatterMissingError", ...)` to a default.
 *
 * @public
 */
-var FrontmatterMissingError = class extends Schema.TaggedErrorClass()("FrontmatterMissingError", {}) {
+var FrontmatterMissingError = class extends Schema.TaggedErrorClass()("FrontmatterMissingError", { 
+/** Why there is no capture: no block at all, or capture left off. */
+reason: FrontmatterMissingReason }) {
 	get message() {
-		return "the document has no frontmatter capture; was it parsed with `frontmatter: true`?";
+		return this.reason === "captureDisabled" ? "the source opens with a frontmatter block, but it was not captured; parse with `frontmatter: true`" : "the document has no frontmatter block";
 	}
 };
 /**
@@ -157,7 +178,8 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	* The decoder reads the document's frontmatter capture (parse with
 	* `frontmatter: true` — the toggle defaults off), decodes its raw value
 	* through the codec, then validates the data against `schema`. Each stage
-	* fails typed: no capture is {@link FrontmatterMissingError}, a
+	* fails typed: no capture is {@link FrontmatterMissingError} (its `reason`
+	* says whether the block is genuinely absent or capture was left off), a
 	* wrong-format codec is {@link FrontmatterFormatMismatchError}, unparseable
 	* content is {@link FrontmatterDecodeError}, and schema-invalid data is
 	* {@link FrontmatterValidationError} carrying the structured issue.
@@ -178,7 +200,7 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 	static schema(schema, codec) {
 		return (document) => {
 			const node = document.frontmatter;
-			return node === void 0 ? Effect.fail(new FrontmatterMissingError()) : codec.decode(node).pipe(Effect.flatMap((data) => Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new FrontmatterValidationError({ issue: error.issue }))))));
+			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 }))))));
 		};
 	}
 	/**
@@ -269,4 +291,4 @@ var MarkdownFrontmatter = class MarkdownFrontmatter {
 };
 
 //#endregion
-export { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, MarkdownFrontmatter };
+export { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, MarkdownFrontmatter };

package/Markdown.js

@@ -28,7 +28,9 @@ const MarkdownDialect = Schema.Literals(["commonmark", "gfm"]);
 * spec-conformant reading must hold unless a consumer opts in. Enabled, the
 * engine captures `---`/`+++`/`---json` blocks at offset 0 into a raw
 * `Frontmatter` head node — decoding it is the frontmatter codec modules'
-* job.
+* job. Parsed with the toggle off, such a document reports no frontmatter —
+* `MarkdownDocument.hasFrontmatterBlock` tells "no block in the source"
+* apart from "parsed with capture off".
 *
 * @public
 */
@@ -181,10 +183,14 @@ var Markdown = class Markdown {
 	* @remarks
 	* Canonical serialization: fidelity fields (marker characters, fence
 	* style, heading spelling) win when present; documented canonical
-	* defaults apply when absent. The output re-parses to a render-equivalent
-	* document — the corpus-pinned contract — but is not a byte-level
-	* round-trip of any original source; surgical editing goes through the
-	* offset-splice edit layer instead.
+	* defaults apply when absent. One default surprises: a language-less
+	* `Code` node with no explicit `fenceChar` serializes as an
+	* **indented** code block — set `fenceChar` (or a `lang`) on the node for
+	* a fence, or normalize afterward with
+	* `MarkdownFormattingOptions.codeBlockStyle: "fenced"`. The output
+	* re-parses to a render-equivalent document — the corpus-pinned
+	* contract — but is not a byte-level round-trip of any original source;
+	* surgical editing goes through the offset-splice edit layer instead.
 	*
 	* Failure is rare by design, symmetric with parse: only a hardening-guard
 	* trip on a tree nesting past the depth cap fails, and only synthesized

package/MarkdownDocument.js

@@ -1,6 +1,8 @@
 import { MarkdownRange } from "./MarkdownEdit.js";
 import { Definition, Root } from "./MarkdownNode.js";
+import { preprocessLines } from "./internal/preprocess.js";
 import { normalizeLabelText } from "./internal/references.js";
+import { scanFrontmatter } from "./internal/blocks/frontmatter.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { parsePassResult } from "./Markdown.js";
 import { Effect, Result, Schema } from "effect";
@@ -113,10 +115,7 @@ const phrasingText = (nodes) => {
 		case "strong":
 		case "delete":
 		case "link":
-		case "linkReference":
-			out += phrasingText(node.children);
-			break;
-		default: break;
+		case "linkReference": out += phrasingText(node.children);
 	}
 	return out;
 };
@@ -164,13 +163,38 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 	* 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.
+	* with no frontmatter block and one parsed with the capture toggle off —
+	* {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
 	*/
 	get frontmatter() {
 		const head = this.root.children[0];
 		return head !== void 0 && head.type === "frontmatter" ? head : void 0;
 	}
 	/**
+	* Whether the source opens with a well-formed frontmatter block —
+	* regardless of how the document was parsed.
+	*
+	* @remarks
+	* The structural signal that disambiguates the `frontmatter` accessor's
+	* `undefined`: 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
+	* `hasFrontmatterBlock === true` means exactly "parsed with capture off";
+	* with `false` it means the source genuinely has no block.
+	*
+	* Derived, not stored: the getter runs the **same** pre-scan the parser
+	* runs when capture is enabled (the closed fence grammar — `---` yaml,
+	* `+++` toml, `---json` json; an unclosed fence is not frontmatter), so it
+	* is `true` exactly when parsing this source with `frontmatter: true`
+	* would produce a capture node, and the two can never drift. Like the
+	* other navigation accessors it recomputes per access — bind it once when
+	* checking repeatedly.
+	*/
+	get hasFrontmatterBlock() {
+		return scanFrontmatter(preprocessLines(this.source), this.source) !== null;
+	}
+	/**
 	* Every heading in the document, in document order, wherever it sits —
 	* including headings nested inside blockquotes and list items.
 	*
@@ -313,7 +337,6 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 					});
 					break;
 				}
-				default: break;
 			}
 		});
 		return entries;

package/MarkdownFormat.js

@@ -5,6 +5,19 @@ import { Effect, Result, Schema } from "effect";
 
 //#region src/MarkdownFormat.ts
 /**
+* The two ways CommonMark spells a code block: `fenced` (a backtick or tilde
+* fence) and `indented` (four-space indentation).
+*
+* @remarks
+* A formatting target for {@link MarkdownFormattingOptions}, not a node
+* fidelity field: on a {@link Code} node the two spellings are told apart by
+* the presence or absence of `fenceChar`/`fenceLength`, and a language-less
+* node with neither serializes as an **indented** block by default.
+*
+* @public
+*/
+const CodeBlockStyle = Schema.Literals(["fenced", "indented"]);
+/**
 * Options controlling formatting: which concrete-syntax markers to normalize,
 * plus the parse knobs (`dialect`, `frontmatter`) the formatter parses the
 * source with (same defaults as `Markdown.parse`). Every marker option is
@@ -12,7 +25,25 @@ import { Effect, Result, Schema } from "effect";
 *
 * Day-one scope is marker normalization only — heading style, bullet
 * character, emphasis/strong marker, fence character, thematic-break
-* character. Content is never rewritten, rewrapped or reflowed.
+* character, code-block style. Content is never rewritten, rewrapped or
+* reflowed.
+*
+* @remarks
+* `codeBlockStyle` is the opt-in that converts between the two code-block
+* spellings for **language-less** blocks (a block with a `lang` has no
+* indented spelling and is never touched). It exists because the default
+* surprises: absent this option, a language-less code block keeps its
+* spelling — and a language-less {@link Code} node with no explicit
+* `fenceChar` **serializes as an indented block** through
+* `Markdown.stringify`. `"fenced"` rewrites indented blocks to fences (the
+* fence character follows `fenceChar` when also set, backtick otherwise);
+* `"indented"` rewrites language-less fences to indented form where provably
+* safe. Like every other option, hazardous conversions are skipped, never
+* attempted: both directions apply to root-level, flush-left blocks only,
+* and the `"indented"` direction additionally skips blocks whose indented
+* spelling would lazily continue a paragraph, be absorbed into a preceding
+* list or footnote definition, merge with an adjacent code block, or fail
+* representability (empty, or blank first/last lines).
 *
 * @public
 */
@@ -23,7 +54,8 @@ var MarkdownFormattingOptions = class extends Schema.Class("MarkdownFormattingOp
 	bulletChar: Schema.optionalKey(BulletChar),
 	emphasisChar: Schema.optionalKey(EmphasisChar),
 	fenceChar: Schema.optionalKey(FenceChar),
-	thematicBreakChar: Schema.optionalKey(ThematicBreakChar)
+	thematicBreakChar: Schema.optionalKey(ThematicBreakChar),
+	codeBlockStyle: Schema.optionalKey(CodeBlockStyle)
 }) {};
 /**
 * Error codes `MarkdownFormat.modify` can fail with.
@@ -193,6 +225,51 @@ const formatFence = (source, emit, node, target) => {
 	while (end - closeLength > start + openLength && source[end - closeLength - 1] === fidelity) closeLength++;
 	if (closeLength >= 3) emit.push(node, end - closeLength, closeLength, target.repeat(newLength));
 };
+/** A line that is empty or holds only spaces and tabs. */
+const BLANK_LINE = /^[ \t]*$/;
+/** Whether a sibling is a code block with no info string (either spelling). */
+const isLanguagelessCode = (node) => node.type === "code" && node.lang === void 0 && node.meta === void 0;
+/**
+* Convert a language-less code block toward the requested style. Returns
+* whether a whole-block conversion edit was emitted, so the caller can keep
+* `formatFence` off a span this conversion already rewrote.
+*
+* Both directions are whole-block rewrites, so both are restricted to
+* root-level, flush-left blocks — a container's continuation-line prefix
+* (`> `, list indentation) is not reproducible by a single splice. The
+* indented direction carries the re-parse hazards an indented block is
+* subject to and skips each one: it cannot follow a non-blank line (lazy
+* paragraph continuation), a list or footnote definition absorbs it as item
+* continuation, an adjacent language-less code block would merge with it
+* across the blank line, and an empty value or one with blank first/last
+* lines (or interior whitespace-only lines, which blankness would erase) has
+* no indented spelling at all.
+*/
+const formatCodeBlockStyle = (source, emit, node, parent, siblings, index, target, fenceChar) => {
+	if (node.lang !== void 0 || node.meta !== void 0) return false;
+	if (parent === void 0 || parent.type !== "root") return false;
+	const { start, end } = spanOf(node);
+	if (lineStartOf(source, start) !== start) return false;
+	const value = node.value.endsWith("\n") ? node.value.slice(0, -1) : node.value;
+	if (target === "fenced") {
+		if (node.fenceChar !== void 0) return false;
+		const char = fenceChar ?? "`";
+		const fence = char.repeat(Math.max(3, longestRun(value, char) + 1));
+		emit.push(node, start, end - start, `${fence}\n${value}\n${fence}`);
+		return true;
+	}
+	if (node.fenceChar === void 0) return false;
+	const lines = value === "" ? [] : value.split("\n");
+	if (lines.length === 0 || BLANK_LINE.test(lines[0]) || BLANK_LINE.test(lines[lines.length - 1])) return false;
+	if (lines.some((line) => line !== "" && BLANK_LINE.test(line))) return false;
+	if (!previousLineBlank(source, start)) return false;
+	const previous = index > 0 ? siblings[index - 1] : void 0;
+	const next = index + 1 < siblings.length ? siblings[index + 1] : void 0;
+	if (previous !== void 0 && (previous.type === "list" || previous.type === "footnoteDefinition")) return false;
+	if (previous !== void 0 && isLanguagelessCode(previous) || next !== void 0 && isLanguagelessCode(next)) return false;
+	emit.push(node, start, end - start, lines.map((line) => line === "" ? "" : `    ${line}`).join("\n"));
+	return true;
+};
 const FLOW_TYPES = /* @__PURE__ */ new Set([
 	"blockquote",
 	"code",
@@ -279,12 +356,18 @@ var MarkdownFormat = class MarkdownFormat {
 	/**
 	* Compute marker-normalization edits per the requested
 	* {@link MarkdownFormattingOptions}: heading style, bullet character,
-	* emphasis/strong marker, fence character and thematic-break character,
-	* each only where the node's concrete syntax differs from the target and
-	* the rewrite is provably safe. Content is never touched. `range`
-	* restricts edits to the nodes intersecting it (the owning-node
-	* intersection posture, matching toml). Non-mutating — apply with
-	* `MarkdownEdit.applyAll` (or use {@link MarkdownFormat.formatToString}).
+	* emphasis/strong marker, fence character, thematic-break character and
+	* code-block style, each only where the node's concrete syntax differs
+	* from the target and the rewrite is provably safe. Content is never
+	* touched. `range` restricts edits to the nodes intersecting it (the
+	* owning-node intersection posture, matching toml). Non-mutating — apply
+	* with `MarkdownEdit.applyAll` (or use
+	* {@link MarkdownFormat.formatToString}).
+	*
+	* Note the code-block default: absent `codeBlockStyle`, a language-less
+	* code block keeps whichever spelling it has — `fenceChar` alone
+	* normalizes existing fences and deliberately leaves indented blocks
+	* indented.
 	*/
 	static format(text, range, options) {
 		const parsed = Markdown.parseResult(text, MarkdownParseOptions.make({
@@ -293,12 +376,14 @@ var MarkdownFormat = class MarkdownFormat {
 		}));
 		if (Result.isFailure(parsed)) return [];
 		const emit = new FormatEmitter(text);
-		walk(parsed.success, void 0, [], 0, (node, _parent, siblings, index) => {
+		walk(parsed.success, void 0, [], 0, (node, parent, siblings, index) => {
 			if (options?.thematicBreakChar !== void 0 && node.type === "thematicBreak") formatThematicBreak(text, emit, node, options.thematicBreakChar);
 			if (options?.headingStyle !== void 0 && node.type === "heading") formatHeading(text, emit, node, options.headingStyle);
 			if (options?.bulletChar !== void 0 && node.type === "list") formatList(text, emit, node, siblings, index, options.bulletChar);
 			if (options?.emphasisChar !== void 0 && isEmphasisLike(node)) formatEmphasis(text, emit, node, siblings, index, options.emphasisChar);
-			if (options?.fenceChar !== void 0 && node.type === "code") formatFence(text, emit, node, options.fenceChar);
+			if (node.type === "code") {
+				if (!(options?.codeBlockStyle !== void 0 && formatCodeBlockStyle(text, emit, node, parent, siblings, index, options.codeBlockStyle, options.fenceChar)) && options?.fenceChar !== void 0) formatFence(text, emit, node, options.fenceChar);
+			}
 		});
 		return (range === void 0 ? emit.edits : emit.edits.filter((edit) => Math.max(edit.nodeStart, range.offset) <= Math.min(edit.nodeEnd, range.offset + range.length))).map((edit) => MarkdownEdit.make({
 			offset: edit.offset,
@@ -377,4 +462,4 @@ var MarkdownFormat = class MarkdownFormat {
 };
 
 //#endregion
-export { MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode };
+export { CodeBlockStyle, MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode };

package/MarkdownNode.js

@@ -347,6 +347,12 @@ var ThematicBreak = class extends Schema.Class("ThematicBreak")({
 * for fenced blocks and **absent for indented blocks** — their absence is how
 * the two are told apart on the way back out.
 *
+* A consequence worth knowing before it surprises: a language-less `Code`
+* node with no explicit `fenceChar` **serializes as an indented block**
+* through `Markdown.stringify`. To get a fence, set `fenceChar` on the node
+* (or a `lang`, which forces one), or format the emitted source with
+* `MarkdownFormattingOptions.codeBlockStyle: "fenced"`.
+*
 * @public
 */
 var Code = class extends Schema.Class("Code")({
@@ -454,7 +460,7 @@ var List = class extends Schema.Class("List")({
 	ordered: Schema.optionalKey(Schema.Boolean),
 	start: Schema.optionalKey(Schema.Number),
 	spread: Schema.optionalKey(Schema.Boolean),
-	children: Schema.Array(Schema.suspend(() => ListItem)),
+	children: Schema.Array(Schema.suspend(() => ListContent)),
 	position: NodePosition,
 	bulletChar: Schema.optionalKey(BulletChar),
 	delimiter: Schema.optionalKey(ListDelimiter)
@@ -493,9 +499,19 @@ var TableCell = class extends Schema.Class("TableCell")({
 * content — the cells in a {@link TableRow}. A one-member union, kept because
 * mdast names the category.
 *
+* A REAL `Schema.Union`, not a bare suspended class reference, and the
+* wrapper is load-bearing: `make` passes an already-constructed class
+* instance through a union member untouched, while a class-typed field
+* re-runs construction on every element of the array. On a 30k-row table
+* that re-construction was 1137ms for the single `Table.make` call against
+* 9ms through the union (measured; the pathological suite's "tables" case is
+* the regression instrument). The `children` fields of `TableRow`, `Table`
+* and `List` point at these category unions for exactly that reason — do not
+* "simplify" them back to the member class.
+*
 * @public
 */
-const RowContent = Schema.suspend(() => TableCell);
+const RowContent = Schema.suspend(() => Schema.Union([TableCell]));
 /**
 * TableRow — one row of a {@link Table}: the labels of the columns if it is
 * the table's first row, a data row otherwise.
@@ -504,17 +520,18 @@ const RowContent = Schema.suspend(() => TableCell);
 */
 var TableRow = class extends Schema.Class("TableRow")({
 	type: Schema.tag("tableRow"),
-	children: Schema.Array(Schema.suspend(() => TableCell)),
+	children: Schema.Array(Schema.suspend(() => RowContent)),
 	position: NodePosition
 }) {};
 /**
 * The union of every node that may appear where mdast expects **table**
 * content — the rows in a {@link Table}. A one-member union, kept because
-* mdast names the category.
+* mdast names the category — and a real `Schema.Union` for the construction
+* pass-through documented on `RowContent`.
 *
 * @public
 */
-const TableContent = Schema.suspend(() => TableRow);
+const TableContent = Schema.suspend(() => Schema.Union([TableRow]));
 /**
 * Table — GFM two-dimensional data.
 *
@@ -528,7 +545,7 @@ const TableContent = Schema.suspend(() => TableRow);
 var Table = class extends Schema.Class("Table")({
 	type: Schema.tag("table"),
 	align: Schema.optionalKey(Schema.Array(Schema.NullOr(TableAlign))),
-	children: Schema.Array(Schema.suspend(() => TableRow)),
+	children: Schema.Array(Schema.suspend(() => TableContent)),
 	position: NodePosition
 }) {};
 /**
@@ -557,11 +574,12 @@ const FlowContent = Schema.suspend(() => Schema.Union([
 /**
 * The union of every node that may appear where mdast expects **list**
 * content. A one-member union, kept because mdast names the category and
-* later dialects widen it.
+* later dialects widen it — and a real `Schema.Union` for the construction
+* pass-through documented on `RowContent`.
 *
 * @public
 */
-const ListContent = Schema.suspend(() => ListItem);
+const ListContent = Schema.suspend(() => Schema.Union([ListItem]));
 /**
 * The frontmatter formats the capture recognizes, keyed by their opening
 * fence: `---` is yaml, `+++` is toml and `---json` is json.

package/README.md

@@ -106,7 +106,7 @@ Effect.runPromise(program).then(console.log);
 
 `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.
 
-`MarkdownFormat.format` handles the other half: conservative marker normalization, never content rewriting. It converts heading style, bullet character, emphasis marker, fence character and thematic-break character, and skips any conversion that would not be safe rather than attempting it cleverly:
+`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:
 
 ```ts
 import { MarkdownFormat, MarkdownFormattingOptions } from "@effected/markdown";
@@ -136,6 +136,8 @@ console.log(MarkdownFormat.format(source, undefined, options));
 
 `format` is pure and total, and the edits are non-mutating data — hand them to `MarkdownEdit.applyAll`, or send them to an editor as a text-edit payload.
 
+`codeBlockStyle` is the option to know about before you hit its default: absent it, a language-less code block keeps whichever spelling it already has, and a language-less `Code` node with no `fenceChar` serializes as an *indented* block. `"fenced"` rewrites indented blocks to fences, `"indented"` goes the other way where the result provably re-parses the same, and both directions apply to root-level flush-left blocks only. A block with a language has no indented spelling and is never touched.
+
 ## Frontmatter
 
 Frontmatter capture is opt-in, because enabling it changes how a document opening with `---` parses: CommonMark reads `---\ntitle: x\n---` as a thematic break and a setext heading, and that spec-conformant reading holds unless you ask for something else. Turn it on and compose your schema with a codec for typed gray-matter parity:
@@ -166,6 +168,8 @@ Effect.runPromise(program).then(console.log);
 
 Each stage fails typed and separately: no capture is a `FrontmatterMissingError` (catch the tag for optional semantics), a codec handed the wrong fence is a `FrontmatterFormatMismatchError`, unparseable content is a `FrontmatterDecodeError` carrying the format package's own positioned failure structurally, and schema-invalid data is a `FrontmatterValidationError` carrying the structured issue tree rather than a stringified rendering.
 
+Because capture is opt-in, "there is no frontmatter" has two meanings, and `FrontmatterMissingError.reason` tells them apart: `"absent"` when the source genuinely has no block, `"captureDisabled"` when it opens with one but was parsed with the toggle off — where the fix is a parse option, not a document edit. `MarkdownDocument.hasFrontmatterBlock` answers the same question directly, by re-running the parser's own pre-scan, so the accessor and the error can never disagree.
+
 The three codecs — `YamlFrontmatter` (`---`), `TomlFrontmatter` (`+++`) and `JsonFrontmatter` (`---json`) — are free-standing named exports, one module each, deliberately never collected into a namespace object. Naming one codec is what pulls in its format engine, so a JSON-frontmatter consumer never pays for the yaml parser.
 
 Frontmatter blocks can also describe their own schema. `SchemaResolver.classify` sorts a `$schema` value into a tagged union — `ByUrl`, `ByPath`, `Inline` and `ByName` — and `SchemaResolver.fromRegistry` resolves `ByName` declarations like `skill@2.1.0` against schemas you register. URLs, paths and inline documents are carried as data and never fetched: this is a pure package and it performs no IO.
@@ -192,7 +196,33 @@ 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.
+`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:
+
+```ts
+import { MarkdownDocument } from "@effected/markdown";
+import { Effect } from "effect";
+
+const source = `# Changelog
+
+## 1.2.3
+
+Fixed a bug.
+
+## 1.2.2
+
+Initial release.
+`;
+
+const program = Effect.gen(function* () {
+  const doc = yield* MarkdownDocument.parse(source);
+  return doc.sectionByHeading("1.2.3", { depth: 2 })?.body.trim();
+});
+
+Effect.runPromise(program).then(console.log);
+// Fixed a bug.
+```
+
+`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.
 
@@ -234,13 +264,13 @@ if (Result.isSuccess(parsed)) {
 ## Features
 
 - `Markdown` — `parse`/`stringify` as `Effect`s with typed `MarkdownParseError`/`MarkdownStringifyError` channels, the pure `parseResult`/`stringifyResult` twins for synchronous callers, and the `MarkdownFromString` two-way codec.
-- `MarkdownDocument` — source, tree, diagnostics and the link-definition index, plus the derived `headings`, `sections` and `links` accessors, the `find`/`findAll` tree queries over type-narrowed selectors, and the `frontmatter` capture.
+- `MarkdownDocument` — source, tree, diagnostics and the link-definition index, plus the derived `headings`, `sections` and `links` accessors, the `firstSection`/`sectionByHeading` finders over a `DocumentSection` (heading, depth, range, body), the `find`/`findAll` tree queries over type-narrowed selectors, and the `frontmatter` capture with `hasFrontmatterBlock` to tell an absent block from an uncaptured one.
 - The mdast-shaped node classes — the CommonMark types plus GFM's `delete`, `table`, `tableRow`, `tableCell`, `footnoteDefinition`, `footnoteReference` and task-list `checked`, each carrying unist positions with byte offsets and this package's fidelity fields. `position` defaults to the zero-width synthetic sentinel, so a replacement fragment constructs in one line — `Text.make({ value: "shipped" })`.
 - `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.
 - `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.
+- `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.
 - `MarkdownDiagnostic` — the structured diagnostic (`code`, `message`, `offset`, `length`, `line`, `character`) every typed error carries, shaped identically to the sibling packages'.
 

package/index.d.ts

@@ -388,6 +388,12 @@ declare const Code_base: Schema.Class<Code, Schema.Struct<{
  * for fenced blocks and **absent for indented blocks** — their absence is how
  * the two are told apart on the way back out.
  *
+ * A consequence worth knowing before it surprises: a language-less `Code`
+ * node with no explicit `fenceChar` **serializes as an indented block**
+ * through `Markdown.stringify`. To get a fence, set `fenceChar` on the node
+ * (or a `lang`, which forces one), or format the emitted source with
+ * `MarkdownFormattingOptions.codeBlockStyle: "fenced"`.
+ *
  * @public
  */
 declare class Code extends Code_base {}
@@ -534,6 +540,16 @@ declare class TableCell extends TableCell_base {}
  * content — the cells in a {@link TableRow}. A one-member union, kept because
  * mdast names the category.
  *
+ * A REAL `Schema.Union`, not a bare suspended class reference, and the
+ * wrapper is load-bearing: `make` passes an already-constructed class
+ * instance through a union member untouched, while a class-typed field
+ * re-runs construction on every element of the array. On a 30k-row table
+ * that re-construction was 1137ms for the single `Table.make` call against
+ * 9ms through the union (measured; the pathological suite's "tables" case is
+ * the regression instrument). The `children` fields of `TableRow`, `Table`
+ * and `List` point at these category unions for exactly that reason — do not
+ * "simplify" them back to the member class.
+ *
  * @public
  */
 declare const RowContent: Schema.Codec<RowContent>;
@@ -558,7 +574,8 @@ declare class TableRow extends TableRow_base {}
 /**
  * The union of every node that may appear where mdast expects **table**
  * content — the rows in a {@link Table}. A one-member union, kept because
- * mdast names the category.
+ * mdast names the category — and a real `Schema.Union` for the construction
+ * pass-through documented on `RowContent`.
  *
  * @public
  */
@@ -609,7 +626,8 @@ type FlowContent = Blockquote | Code | Definition | FootnoteDefinition | Heading
 /**
  * The union of every node that may appear where mdast expects **list**
  * content. A one-member union, kept because mdast names the category and
- * later dialects widen it.
+ * later dialects widen it — and a real `Schema.Union` for the construction
+ * pass-through documented on `RowContent`.
  *
  * @public
  */
@@ -808,7 +826,9 @@ declare const MarkdownParseOptions_base: Schema.Class<MarkdownParseOptions, Sche
  * spec-conformant reading must hold unless a consumer opts in. Enabled, the
  * engine captures `---`/`+++`/`---json` blocks at offset 0 into a raw
  * `Frontmatter` head node — decoding it is the frontmatter codec modules'
- * job.
+ * job. Parsed with the toggle off, such a document reports no frontmatter —
+ * `MarkdownDocument.hasFrontmatterBlock` tells "no block in the source"
+ * apart from "parsed with capture off".
  *
  * @public
  */
@@ -917,10 +937,14 @@ declare class Markdown {
    * @remarks
    * Canonical serialization: fidelity fields (marker characters, fence
    * style, heading spelling) win when present; documented canonical
-   * defaults apply when absent. The output re-parses to a render-equivalent
-   * document — the corpus-pinned contract — but is not a byte-level
-   * round-trip of any original source; surgical editing goes through the
-   * offset-splice edit layer instead.
+   * defaults apply when absent. One default surprises: a language-less
+   * `Code` node with no explicit `fenceChar` serializes as an
+   * **indented** code block — set `fenceChar` (or a `lang`) on the node for
+   * a fence, or normalize afterward with
+   * `MarkdownFormattingOptions.codeBlockStyle: "fenced"`. The output
+   * re-parses to a render-equivalent document — the corpus-pinned
+   * contract — but is not a byte-level round-trip of any original source;
+   * surgical editing goes through the offset-splice edit layer instead.
    *
    * Failure is rare by design, symmetric with parse: only a hardening-guard
    * trip on a tree nesting past the depth cap fails, and only synthesized
@@ -1202,9 +1226,32 @@ declare class MarkdownDocument extends MarkdownDocument_base {
    * 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.
+   * with no frontmatter block and one parsed with the capture toggle off —
+   * {@link MarkdownDocument.hasFrontmatterBlock} tells the two apart.
    */
   get frontmatter(): Frontmatter | undefined;
+  /**
+   * Whether the source opens with a well-formed frontmatter block —
+   * regardless of how the document was parsed.
+   *
+   * @remarks
+   * The structural signal that disambiguates the `frontmatter` accessor's
+   * `undefined`: 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
+   * `hasFrontmatterBlock === true` means exactly "parsed with capture off";
+   * with `false` it means the source genuinely has no block.
+   *
+   * Derived, not stored: the getter runs the **same** pre-scan the parser
+   * runs when capture is enabled (the closed fence grammar — `---` yaml,
+   * `+++` toml, `---json` json; an unclosed fence is not frontmatter), so it
+   * is `true` exactly when parsing this source with `frontmatter: true`
+   * would produce a capture node, and the two can never drift. Like the
+   * other navigation accessors it recomputes per access — bind it once when
+   * checking repeatedly.
+   */
+  get hasFrontmatterBlock(): boolean;
   /**
    * Every heading in the document, in document order, wherever it sits —
    * including headings nested inside blockquotes and list items.
@@ -1441,18 +1488,46 @@ interface FrontmatterCodec {
   /** Serialize data into a frontmatter body, without fences. */
   readonly encode: (data: unknown) => Effect.Effect<string, FrontmatterEncodeError>;
 }
-declare const FrontmatterMissingError_base: Schema.Class<FrontmatterMissingError, Schema.TaggedStruct<"FrontmatterMissingError", {}>, import("effect/Cause").YieldableError>;
+/**
+ * Why a frontmatter decoder found no capture on a document.
+ *
+ * @remarks
+ * `"absent"` — the source genuinely has no frontmatter block.
+ * `"captureDisabled"` — the source opens with a well-formed frontmatter
+ * block, but the document carries no capture node: it was parsed without
+ * `frontmatter: true` (the toggle defaults off), so spec-correct CommonMark
+ * read the fences as ordinary content.
+ *
+ * @public
+ */
+declare const FrontmatterMissingReason: Schema.Literals<readonly ["absent", "captureDisabled"]>;
+/**
+ * Why a frontmatter decoder found no capture on a document.
+ *
+ * @public
+ */
+type FrontmatterMissingReason = typeof FrontmatterMissingReason.Type;
+declare const FrontmatterMissingError_base: Schema.Class<FrontmatterMissingError, Schema.TaggedStruct<"FrontmatterMissingError", {
+  /** Why there is no capture: no block at all, or capture left off. */
+  readonly reason: Schema.Literals<readonly ["absent", "captureDisabled"]>;
+}>, import("effect/Cause").YieldableError>;
 /**
  * Indicates that a document handed to a frontmatter decoder carries no
  * frontmatter capture.
  *
  * @remarks
- * Raised when the document genuinely has no frontmatter block — including
- * when it has one in the source but was parsed with the capture toggle off
- * (`MarkdownParseOptions.frontmatter` defaults to `false`). Cause-free: there
- * is nothing to diagnose beyond the absence itself. Consumers wanting
- * optional semantics can `Effect.catchTag("FrontmatterMissingError", ...)`
- * to a default.
+ * `reason` distinguishes the two ways this happens: `"absent"` when the
+ * source genuinely has no frontmatter block, `"captureDisabled"` when the
+ * source opens with one but the document was parsed with the capture toggle
+ * off (`MarkdownParseOptions.frontmatter` defaults to `false`) — the fix
+ * there is parsing with `frontmatter: true`, not editing the document. The
+ * discriminant is computed from the same structural signal
+ * `MarkdownDocument.hasFrontmatterBlock` exposes, so the error and the
+ * accessor can never disagree.
+ *
+ * Cause-free: there is nothing to diagnose beyond the absence itself.
+ * Consumers wanting optional semantics can
+ * `Effect.catchTag("FrontmatterMissingError", ...)` to a default.
  *
  * @public
  */
@@ -1516,7 +1591,8 @@ declare class MarkdownFrontmatter {
    * The decoder reads the document's frontmatter capture (parse with
    * `frontmatter: true` — the toggle defaults off), decodes its raw value
    * through the codec, then validates the data against `schema`. Each stage
-   * fails typed: no capture is {@link FrontmatterMissingError}, a
+   * fails typed: no capture is {@link FrontmatterMissingError} (its `reason`
+   * says whether the block is genuinely absent or capture was left off), a
    * wrong-format codec is {@link FrontmatterFormatMismatchError}, unparseable
    * content is {@link FrontmatterDecodeError}, and schema-invalid data is
    * {@link FrontmatterValidationError} carrying the structured issue.
@@ -1866,6 +1942,25 @@ type MarkdownRangeLike = MarkdownRange | {
   readonly offset: number;
   readonly length: number;
 };
+/**
+ * The two ways CommonMark spells a code block: `fenced` (a backtick or tilde
+ * fence) and `indented` (four-space indentation).
+ *
+ * @remarks
+ * A formatting target for {@link MarkdownFormattingOptions}, not a node
+ * fidelity field: on a {@link Code} node the two spellings are told apart by
+ * the presence or absence of `fenceChar`/`fenceLength`, and a language-less
+ * node with neither serializes as an **indented** block by default.
+ *
+ * @public
+ */
+declare const CodeBlockStyle: Schema.Literals<readonly ["fenced", "indented"]>;
+/**
+ * The union of all code-block-style string literals.
+ *
+ * @public
+ */
+type CodeBlockStyle = typeof CodeBlockStyle.Type;
 declare const MarkdownFormattingOptions_base: Schema.Class<MarkdownFormattingOptions, Schema.Struct<{
   readonly dialect: Schema.optionalKey<Schema.Literals<readonly ["commonmark", "gfm"]>>;
   readonly frontmatter: Schema.optionalKey<Schema.Boolean>;
@@ -1874,6 +1969,7 @@ declare const MarkdownFormattingOptions_base: Schema.Class<MarkdownFormattingOpt
   readonly emphasisChar: Schema.optionalKey<Schema.Literals<readonly ["*", "_"]>>;
   readonly fenceChar: Schema.optionalKey<Schema.Literals<readonly ["`", "~"]>>;
   readonly thematicBreakChar: Schema.optionalKey<Schema.Literals<readonly ["-", "_", "*"]>>;
+  readonly codeBlockStyle: Schema.optionalKey<Schema.Literals<readonly ["fenced", "indented"]>>;
 }>, {}>;
 /**
  * Options controlling formatting: which concrete-syntax markers to normalize,
@@ -1883,7 +1979,25 @@ declare const MarkdownFormattingOptions_base: Schema.Class<MarkdownFormattingOpt
  *
  * Day-one scope is marker normalization only — heading style, bullet
  * character, emphasis/strong marker, fence character, thematic-break
- * character. Content is never rewritten, rewrapped or reflowed.
+ * character, code-block style. Content is never rewritten, rewrapped or
+ * reflowed.
+ *
+ * @remarks
+ * `codeBlockStyle` is the opt-in that converts between the two code-block
+ * spellings for **language-less** blocks (a block with a `lang` has no
+ * indented spelling and is never touched). It exists because the default
+ * surprises: absent this option, a language-less code block keeps its
+ * spelling — and a language-less {@link Code} node with no explicit
+ * `fenceChar` **serializes as an indented block** through
+ * `Markdown.stringify`. `"fenced"` rewrites indented blocks to fences (the
+ * fence character follows `fenceChar` when also set, backtick otherwise);
+ * `"indented"` rewrites language-less fences to indented form where provably
+ * safe. Like every other option, hazardous conversions are skipped, never
+ * attempted: both directions apply to root-level, flush-left blocks only,
+ * and the `"indented"` direction additionally skips blocks whose indented
+ * spelling would lazily continue a paragraph, be absorbed into a preceding
+ * list or footnote definition, merge with an adjacent code block, or fail
+ * representability (empty, or blank first/last lines).
  *
  * @public
  */
@@ -1941,12 +2055,18 @@ declare class MarkdownFormat {
   /**
    * Compute marker-normalization edits per the requested
    * {@link MarkdownFormattingOptions}: heading style, bullet character,
-   * emphasis/strong marker, fence character and thematic-break character,
-   * each only where the node's concrete syntax differs from the target and
-   * the rewrite is provably safe. Content is never touched. `range`
-   * restricts edits to the nodes intersecting it (the owning-node
-   * intersection posture, matching toml). Non-mutating — apply with
-   * `MarkdownEdit.applyAll` (or use {@link MarkdownFormat.formatToString}).
+   * emphasis/strong marker, fence character, thematic-break character and
+   * code-block style, each only where the node's concrete syntax differs
+   * from the target and the rewrite is provably safe. Content is never
+   * touched. `range` restricts edits to the nodes intersecting it (the
+   * owning-node intersection posture, matching toml). Non-mutating — apply
+   * with `MarkdownEdit.applyAll` (or use
+   * {@link MarkdownFormat.formatToString}).
+   *
+   * Note the code-block default: absent `codeBlockStyle`, a language-less
+   * code block keeps whichever spelling it has — `fenceChar` alone
+   * normalizes existing fences and deliberately leaves indented blocks
+   * indented.
    */
   static format(text: string, range?: MarkdownRangeLike, options?: MarkdownFormattingOptions): ReadonlyArray<MarkdownEdit>;
   /**
@@ -2292,5 +2412,5 @@ declare const TomlFrontmatter: FrontmatterCodec;
  */
 declare const YamlFrontmatter: FrontmatterCodec;
 //#endregion
-export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, type DocumentHeading, type DocumentLink, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, type SectionHeadingMatch, type SectionQueryOptions, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, CodeBlockStyle, Definition, Delete, type DocumentHeading, type DocumentLink, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, type FrontmatterCodec, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, type FrontmatterResolveError, type FrontmatterSchemaError, type FrontmatterSchemaResolver, FrontmatterValidationError, type FrontmatterWriteError, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, JsonFrontmatter, Link, type LinkBearingNode, LinkReference, List, ListContent, ListDelimiter, ListItem, Markdown, MarkdownDiagnostic, MarkdownDialect, MarkdownDocument, MarkdownEdit, MarkdownFormat, MarkdownFormattingOptions, MarkdownFrontmatter, MarkdownModificationError, MarkdownModificationErrorCode, MarkdownNode, type MarkdownNodeOfType, type MarkdownNodeType, MarkdownParseError, MarkdownParseErrorCode, MarkdownParseOptions, type MarkdownPath, MarkdownRange, type MarkdownRangeLike, type MarkdownSegment, MarkdownStringifyError, MarkdownVisitor, MarkdownVisitorEvent, Mdast, MdastDecodeError, type MdastNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError, type SectionHeadingMatch, type SectionQueryOptions, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar, TomlFrontmatter, YamlFrontmatter };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,15 +1,15 @@
 import { MarkdownEdit, MarkdownRange } from "./MarkdownEdit.js";
 import { 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, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar } from "./MarkdownNode.js";
-import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterValidationError, MarkdownFrontmatter } from "./Frontmatter.js";
+import { FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormatMismatchError, FrontmatterMissingError, FrontmatterMissingReason, FrontmatterValidationError, MarkdownFrontmatter } from "./Frontmatter.js";
 import { SchemaDeclaration, SchemaDeclarationByName, SchemaDeclarationByPath, SchemaDeclarationByUrl, SchemaDeclarationInline, SchemaDeclarationInvalidError, SchemaDeclarationMissingError, SchemaNameUnknownError, SchemaResolver, SchemaVersionUnresolvableError } from "./FrontmatterResolver.js";
 import { JsonFrontmatter } from "./JsonFrontmatter.js";
 import { MarkdownDiagnostic, MarkdownParseErrorCode } from "./MarkdownDiagnostic.js";
 import { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError } from "./Markdown.js";
 import { DocumentSection, MarkdownDocument } from "./MarkdownDocument.js";
-import { MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode } from "./MarkdownFormat.js";
+import { CodeBlockStyle, MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode } from "./MarkdownFormat.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, Definition, Delete, DocumentSection, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterDecodeError, FrontmatterEncodeError, FrontmatterFormat, FrontmatterFormatMismatchError, FrontmatterMissingError, 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, 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, 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, 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/references.js

@@ -20,6 +20,22 @@ const reLinkLabel = /^\[(?:[^\\[\]]|\\.){0,1000}\]/s;
 * between seconds and minutes.
 */
 const isWhitespaceCode = (code) => code === 32 || code === 9 || code === 10 || code === 11 || code === 12 || code === 13;
+/**
+* The most `(` a bare link destination may hold open at once.
+*
+* cmark's `MAX_LINK_DEST_PARENS` bound in `manual_scan_link_url`, and the
+* limit the spec explicitly sanctions ("Implementations may impose limits on
+* parentheses nesting to avoid performance issues, but at least three levels
+* of nesting should be supported"). Without it the bare-destination walk is
+* the engine's one quadratic: on `"[a](b".repeat(n)` there is no whitespace
+* and no unbalanced `)` to stop at, so every failed inline-link attempt
+* scanned to the end of the subject — O(n) per `]`, O(n^2) overall. With the
+* cap a failed attempt stops at the 33rd `(`, a constant distance, and the
+* pathological suite's "unclosed links B" runs linear. commonmark.js@0.31.2
+* has no such cap and shares the quadratic; the C reference is the authority
+* here.
+*/
+const MAX_LINK_DESTINATION_PARENS = 32;
 const C_BACKSLASH = 92;
 const C_COLON = 58;
 const C_LESSTHAN = 60;
@@ -81,6 +97,7 @@ var ReferenceScanner = class {
 			} else if (code === C_OPEN_PAREN) {
 				this.pos += 1;
 				openParens += 1;
+				if (openParens > MAX_LINK_DESTINATION_PARENS) return;
 			} else if (code === C_CLOSE_PAREN) {
 				if (openParens < 1) break;
 				this.pos += 1;

package/internal/stringify.js

@@ -291,7 +291,6 @@ const serializeInlines = (children, context, state, startsLine, junctionGuard) =
 			case "footnoteReference":
 				out += `[^${escapeLabel(child.label ?? child.identifier)}]`;
 				atLineStart = false;
-				break;
 		}
 		index += 1;
 		unguard(state);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/markdown",
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"private": false,
 	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
 	"keywords": [