@stll/docx-core 0.17.3 → 0.19.0

package/dist/index.js

@@ -1,7 +1,8 @@
-import { i as isOoxmlSymbolCharacter, t as DOCX_CONFORMANCE_CLASSES } from "./document-BPDUWV3O.js";
+import { a as isOoxmlSymbolCharacter, t as DOCX_CONFORMANCE_CLASSES } from "./document-Cj4uqQEw.js";
 import JSZip from "jszip";
 import { panic } from "better-result";
 import { XMLParser, XMLValidator } from "fast-xml-parser";
+import { Marked } from "marked";
 //#region src/serialize/xml.ts
 const ILLEGAL_XML_CHARS_RE = /[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/gu;
 const stripIllegalXmlChars = (value) => value.replace(ILLEGAL_XML_CHARS_RE, "");
@@ -703,7 +704,10 @@ const validateHyperlinkChild = (child, path, ctx) => {
 };
 const validateTrackedRunChange = (change, path, ctx) => {
 	if (change.info.author.trim() === "") addError(ctx, `${path}.info.author`, "Tracked change author is empty.");
-	for (const [index, child] of change.content.entries()) validateFieldChild(child, `${path}.content[${index}]`, ctx);
+	for (const [index, child] of change.content.entries()) {
+		const childPath = `${path}.content[${index}]`;
+		validateParagraphContent(child, childPath, ctx);
+	}
 };
 const validateImage = (image, path, ctx, options = {}) => {
 	if (!image.rId && !image.src?.startsWith("data:") && !options.hasPreservedRawDrawing) addError(ctx, `${path}.rId`, "Image must have a relationship id.");
@@ -828,12 +832,251 @@ const validateCounterPairs = (starts, ends, { label, startName, endName, ctx, se
 	}
 };
 //#endregion
+//#region src/markdown/href.ts
+const ALLOWED_URL_PROTOCOLS = /* @__PURE__ */ new Set([
+	"http:",
+	"https:",
+	"mailto:",
+	"tel:"
+]);
+/**
+* Keep only http(s), mailto, and tel URLs, normalised through the URL parser.
+* Anything else (javascript:, data:, relative paths, malformed input) drops to
+* `undefined` so a markdown link degrades to its text instead of carrying an
+* executable target into the document.
+*/
+const sanitizeExternalUrl = (rawUrl) => {
+	if (!rawUrl) return;
+	const trimmed = rawUrl.trim();
+	if (!trimmed) return;
+	const parsed = parseUrl(trimmed);
+	if (!parsed || !ALLOWED_URL_PROTOCOLS.has(parsed.protocol)) return;
+	if ((parsed.protocol === "mailto:" || parsed.protocol === "tel:") && parsed.pathname.trim() === "") return;
+	return parsed.href;
+};
+const parseUrl = (value) => {
+	try {
+		return new URL(value);
+	} catch {
+		return null;
+	}
+};
+const hasUnsafeAnchorCharacter = (anchor) => {
+	for (const char of anchor) {
+		const codePoint = char.codePointAt(0) ?? 0;
+		if (codePoint <= 32 || codePoint === 127 || char.trim() === "") return true;
+	}
+	return false;
+};
+/** A `#anchor` stays a document-internal target; anything else must pass {@link sanitizeExternalUrl}. */
+const sanitizeMarkdownHref = (rawHref) => {
+	const trimmed = rawHref.trim();
+	if (!trimmed) return;
+	if (trimmed.startsWith("#")) {
+		const anchor = trimmed.slice(1);
+		if (!anchor || hasUnsafeAnchorCharacter(anchor)) return;
+		return `#${anchor}`;
+	}
+	return sanitizeExternalUrl(trimmed);
+};
+//#endregion
+//#region src/markdown/lexer.ts
+/**
+* One `marked` configuration for every markdown surface in docx-core. Plain
+* markdown (`compileMarkdownToContent`) and the legal-source compiler read the
+* same GFM token stream; the legal profile adds a block-level extension that
+* turns an `@directive` line into its own token so the line never merges into
+* a neighbouring paragraph.
+*/
+const LEGAL_DIRECTIVE_TOKEN_TYPE = "legalDirective";
+const DIRECTIVE_LINE_PATTERN = /^[ \t]*@(?<name>[A-Za-z][A-Za-z0-9_-]*)(?<argument>[^\n]*)(?:\n|$)/u;
+const DIRECTIVE_LINE_START_PATTERN = /^[ \t]*@[A-Za-z]/mu;
+const legalDirectiveExtension = {
+	name: LEGAL_DIRECTIVE_TOKEN_TYPE,
+	level: "block",
+	start: (src) => {
+		const index = src.search(DIRECTIVE_LINE_START_PATTERN);
+		return index === -1 ? void 0 : index;
+	},
+	tokenizer: (src) => {
+		const match = DIRECTIVE_LINE_PATTERN.exec(src);
+		const name = match?.groups?.["name"];
+		if (!match || name === void 0) return;
+		return {
+			type: LEGAL_DIRECTIVE_TOKEN_TYPE,
+			raw: match[0],
+			directive: `@${name.toLowerCase()}`,
+			argument: (match.groups?.["argument"] ?? "").trim()
+		};
+	}
+};
+const plainMarkdown = new Marked({ gfm: true });
+const legalMarkdown = new Marked({
+	gfm: true,
+	extensions: [legalDirectiveExtension]
+});
+/** GFM block tokens of a markdown document. */
+const lexMarkdown = (source) => plainMarkdown.lexer(source);
+/**
+* A directive line always starts a block. marked's paragraph tokenizer asks
+* block extensions where the next block starts, but its list and blockquote
+* tokenizers treat any following non-blank line as lazy continuation, so
+* `- item\n@clause Next` would swallow the directive. Inserting one blank
+* line before every directive that lacks one gives every tokenizer the same
+* boundary; the returned map keeps diagnostics on the author's line numbers.
+*/
+const separateDirectiveLines = (source) => {
+	const lines = source.split("\n");
+	const output = [];
+	const insertedBefore = [];
+	let inserted = 0;
+	for (const [index, line] of lines.entries()) {
+		const previous = output.at(-1);
+		if (index > 0 && DIRECTIVE_LINE_START_PATTERN.test(line) && previous !== void 0 && previous.trim() !== "") {
+			output.push("");
+			insertedBefore.push(inserted);
+			inserted += 1;
+		}
+		output.push(line);
+		insertedBefore.push(inserted);
+	}
+	return {
+		text: output.join("\n"),
+		originalLineOf: (line) => line - (insertedBefore.at(line - 1) ?? inserted)
+	};
+};
+/** GFM block tokens of a legal draft, with `@directive` lines as {@link LegalDirectiveToken}s. */
+const lexLegalSource = (source) => {
+	const prepared = separateDirectiveLines(source);
+	return {
+		tokens: legalMarkdown.lexer(prepared.text),
+		originalLineOf: prepared.originalLineOf
+	};
+};
+/** Inline tokens (emphasis, code spans, links, breaks) of one paragraph's text. */
+const lexInlineMarkdown = (text) => plainMarkdown.Lexer.lexInline(text, plainMarkdown.defaults);
+const isLegalDirectiveToken = (token) => token.type === LEGAL_DIRECTIVE_TOKEN_TYPE;
+const isTokenType = (token, type) => token.type === type;
+//#endregion
+//#region src/markdown/inline.ts
+const MONO_FONT = {
+	ascii: "Courier New",
+	hAnsi: "Courier New"
+};
+/**
+* One run. A Word run cannot carry a raw newline (the layout engine renders
+* such lines on top of each other), so "\n" becomes an explicit break node.
+*/
+const textRun = (text, format = {}) => {
+	const formatting = {
+		...format.bold ? { bold: true } : {},
+		...format.italic ? { italic: true } : {},
+		...format.strike ? { strike: true } : {},
+		...format.mono ? { fontFamily: MONO_FONT } : {},
+		...format.highlight ? { highlight: format.highlight } : {}
+	};
+	const content = [];
+	for (const [index, segment] of text.split("\n").entries()) {
+		if (index > 0) content.push({ type: "break" });
+		if (segment.length > 0) content.push({
+			type: "text",
+			text: segment,
+			preserveSpace: true
+		});
+	}
+	if (content.length === 0) content.push({
+		type: "text",
+		text: "",
+		preserveSpace: true
+	});
+	return {
+		type: "run",
+		formatting,
+		content
+	};
+};
+const PLACEHOLDER_PATTERN = /\[\[(?<inner>[^\][]+?)\]\]/gu;
+/**
+* Literal text (no markdown reading) with `[[…]]` placeholders highlighted:
+* for fields that are data rather than prose, such as signature parties.
+*/
+const plainTextRuns = (text, format = {}) => placeholderRuns(text, format);
+const placeholderRuns = (text, format) => {
+	if (!text.includes("[[")) return [textRun(text, format)];
+	const runs = [];
+	let cursor = 0;
+	for (const match of text.matchAll(PLACEHOLDER_PATTERN)) {
+		const start = match.index;
+		if (start > cursor) runs.push(textRun(text.slice(cursor, start), format));
+		runs.push(textRun(match.groups?.["inner"] ?? "", {
+			...format,
+			highlight: "yellow"
+		}));
+		cursor = start + match[0].length;
+	}
+	if (cursor < text.length) runs.push(textRun(text.slice(cursor), format));
+	return runs.length > 0 ? runs : [textRun(text, format)];
+};
+const plainRuns = (text, format, placeholders) => placeholders ? placeholderRuns(text, format) : [textRun(text, format)];
+const tokensToRuns = (tokens, fallback, format, context) => {
+	if (!tokens || tokens.length === 0) return plainRuns(fallback, format, context.placeholders);
+	const runs = [];
+	for (const token of tokens) if (isTokenType(token, "strong")) runs.push(...tokensToRuns(token.tokens, token.text, {
+		...format,
+		bold: true
+	}, context));
+	else if (isTokenType(token, "em")) runs.push(...tokensToRuns(token.tokens, token.text, {
+		...format,
+		italic: true
+	}, context));
+	else if (isTokenType(token, "del")) runs.push(...tokensToRuns(token.tokens, token.text, {
+		...format,
+		strike: true
+	}, context));
+	else if (isTokenType(token, "codespan")) runs.push(textRun(token.text, {
+		...format,
+		mono: true
+	}));
+	else if (isTokenType(token, "link")) runs.push(...linkRuns(token.tokens, token.text, token.href, format, context));
+	else if (isTokenType(token, "paragraph")) runs.push(...tokensToRuns(token.tokens, token.text, format, context));
+	else if (token.type === "br") runs.push({
+		type: "run",
+		content: [{ type: "break" }]
+	});
+	else if (token.type === "space") {
+		if (runs.length > 0 && token.raw.includes("\n")) runs.push(textRun("\n", format));
+	} else if (isTokenType(token, "text")) {
+		const nested = token.tokens;
+		if (nested && nested.length > 0) runs.push(...tokensToRuns(nested, token.text, format, context));
+		else runs.push(...plainRuns(token.text, format, context.placeholders));
+	} else if ("text" in token && typeof token.text === "string") runs.push(...plainRuns(token.text, format, context.placeholders));
+	return runs.length > 0 ? runs : plainRuns(fallback, format, context.placeholders);
+};
+const linkRuns = (tokens, text, rawHref, format, context) => {
+	const children = tokensToRuns(tokens, text, format, context).filter((child) => child.type === "run");
+	const linkChildren = children.length > 0 ? children : [textRun(text, format)];
+	const href = sanitizeMarkdownHref(rawHref);
+	if (!href) return linkChildren;
+	const anchor = href.startsWith("#") ? href.slice(1) : void 0;
+	return [{
+		type: "hyperlink",
+		href,
+		...anchor ? { anchor } : {},
+		children: linkChildren
+	}];
+};
+/** Render already-lexed inline tokens; `fallback` is the source text when the tokens are empty. */
+const inlineTokensToRuns = (tokens, fallback, options = {}) => tokensToRuns(tokens, fallback, options.base ?? {}, { placeholders: options.placeholders ?? false });
+/** Lex and render one paragraph's inline markdown. */
+const inlineMarkdownToRuns = (text, options = {}) => inlineTokensToRuns(lexInlineMarkdown(text), text, options);
+//#endregion
 //#region src/legal-source/parser.ts
 const DEFAULT_KIND = "agreement";
 const DEFAULT_LOCALE = "en-GB";
 const DEFAULT_NUMBERING = "legal";
 const DEFAULT_PAGE_SIZE = "A4";
 const DEFAULT_ORIENTATION = "portrait";
+const MAX_CLAUSE_LEVEL = 6;
 const DIRECTIVE_ALIASES = {
 	"@annex": "@schedule",
 	"@appendix": "@schedule",
@@ -844,6 +1087,7 @@ const DIRECTIVE_ALIASES = {
 	"@signature": "@signatures",
 	"@subsection": "@subclause"
 };
+const CLOSING_DIRECTIVE_PATTERN = /^@end[a-z]*$/u;
 const DIRECTIVES = /* @__PURE__ */ new Set([
 	"@doc",
 	"@title",
@@ -857,194 +1101,337 @@ const DIRECTIVES = /* @__PURE__ */ new Set([
 	"@signatures",
 	"@pagebreak"
 ]);
+/**
+* Walks the top-level token stream. Line numbers come from the newlines in
+* the consumed tokens' `raw` text, which marked keeps contiguous with the
+* source, so diagnostics point at the directive line that produced them.
+*/
+var TokenCursor = class {
+	tokens;
+	originalLineOf;
+	index = 0;
+	lineNumber = 1;
+	constructor({ tokens, originalLineOf }) {
+		this.tokens = tokens;
+		this.originalLineOf = originalLineOf;
+	}
+	get current() {
+		return this.tokens.at(this.index);
+	}
+	/** The author's line number for the current token. */
+	get line() {
+		return this.originalLineOf(this.lineNumber);
+	}
+	/** Index of the current token; lets a caller tell whether a helper consumed anything. */
+	get position() {
+		return this.index;
+	}
+	advance() {
+		const token = this.current;
+		if (token === void 0) return;
+		this.index += 1;
+		this.lineNumber += countNewlines(token.raw);
+		return token;
+	}
+};
+const countNewlines = (text) => {
+	let count = 0;
+	for (const char of text) if (char === "\n") count += 1;
+	return count;
+};
+/** A token that starts a new structural block, so no body may run past it. */
+const startsStructure = (token) => isLegalDirectiveToken(token) || isTokenType(token, "heading");
 const parseLegalSource = (source, options = {}) => {
-	const fixes = [];
-	const diagnostics = [];
-	const blocks = [];
-	const meta = {
-		kind: DEFAULT_KIND,
-		locale: DEFAULT_LOCALE,
-		numbering: DEFAULT_NUMBERING,
-		page: {
-			size: DEFAULT_PAGE_SIZE,
-			orientation: DEFAULT_ORIENTATION
+	const state = {
+		blocks: [],
+		diagnostics: [],
+		fixes: [],
+		meta: {
+			kind: DEFAULT_KIND,
+			locale: DEFAULT_LOCALE,
+			numbering: DEFAULT_NUMBERING,
+			page: {
+				size: DEFAULT_PAGE_SIZE,
+				orientation: DEFAULT_ORIENTATION
+			},
+			title: null
 		},
-		title: null
-	};
-	let pending = null;
-	const pushPending = () => {
-		if (!pending) return;
-		const block = pendingToBlock(pending, diagnostics, fixes);
-		if (block) {
-			blocks.push(block);
-			if (block.type === "title") meta.title = block.text;
-		}
-		pending = null;
+		cursor: new TokenCursor(lexLegalSource(source))
 	};
-	const lines = source.replace(/\r\n?/gu, "\n").split("\n");
-	for (const [index, rawLine] of lines.entries()) {
-		const lineNumber = index + 1;
-		const line = rawLine.trimEnd();
-		const trimmed = line.trim();
-		if (!trimmed) {
-			pending?.lines.push("");
+	for (;;) {
+		const token = state.cursor.current;
+		if (token === void 0) break;
+		const line = state.cursor.line;
+		if (isLegalDirectiveToken(token)) {
+			state.cursor.advance();
+			parseDirective(token, line, state);
 			continue;
 		}
-		const markdownHeading = parseMarkdownHeading(trimmed);
-		if (markdownHeading) {
-			pushPending();
-			const { depth, heading } = markdownHeading;
-			if (depth === 1) {
-				pending = {
-					type: "title",
-					line: lineNumber,
-					heading,
-					lines: []
-				};
-				pushPending();
-			} else pending = {
-				type: "clause",
-				line: lineNumber,
-				level: Math.min(depth - 1, 6),
-				heading,
-				lines: []
-			};
-			fixes.push({
-				code: "markdown-heading-normalized",
-				message: "Converted a Markdown heading into a legal directive.",
-				line: lineNumber
-			});
+		if (isTokenType(token, "heading")) {
+			state.cursor.advance();
+			parseMarkdownHeading(token, line, state);
 			continue;
 		}
-		if (trimmed.startsWith("@")) {
-			const [rawDirective = "", ...rest] = trimmed.split(/\s+/u);
-			const canonicalDirective = DIRECTIVE_ALIASES[rawDirective.toLowerCase()] ?? rawDirective.toLowerCase();
-			const argument = rest.join(" ").trim();
-			if (!DIRECTIVES.has(canonicalDirective)) {
-				diagnostics.push({
-					code: "unknown-directive",
-					message: `Unknown legal directive "${rawDirective}".`,
-					severity: "error",
-					line: lineNumber
-				});
-				pending?.lines.push(line);
-				continue;
-			}
-			if (canonicalDirective !== rawDirective.toLowerCase()) fixes.push({
-				code: "directive-alias-normalized",
-				message: `Normalized ${rawDirective} to ${canonicalDirective}.`,
-				line: lineNumber
+		parseBareMarkdown(state);
+	}
+	if (!state.meta.title) {
+		const firstTitle = state.blocks.find((block) => block.type === "title");
+		state.meta.title = firstTitle?.type === "title" ? firstTitle.text : options.titleFallback ?? "Untitled document";
+	}
+	const draft = {
+		meta: state.meta,
+		blocks: state.blocks
+	};
+	return applyDocumentAutofixes({
+		diagnostics: state.diagnostics,
+		draft,
+		fixes: state.fixes
+	});
+};
+const pushBlock = (state, block) => {
+	if (!block) return;
+	state.blocks.push(block);
+	if (block.type === "title") state.meta.title = block.text;
+};
+const parseDirective = (token, line, state) => {
+	const { diagnostics, fixes, meta } = state;
+	const rawDirective = token.directive;
+	const directive = DIRECTIVE_ALIASES[rawDirective] ?? rawDirective;
+	const { argument } = token;
+	if (CLOSING_DIRECTIVE_PATTERN.test(directive)) {
+		fixes.push({
+			code: "closing-directive-ignored",
+			message: `Ignored ${rawDirective}: blocks end where the next directive starts.`,
+			line
+		});
+		return;
+	}
+	if (!DIRECTIVES.has(directive)) {
+		const spelled = token.raw.trim().split(/\s+/u).at(0) ?? rawDirective;
+		diagnostics.push({
+			code: "unknown-directive",
+			message: `Unknown legal directive "${spelled}".`,
+			severity: "error",
+			line
+		});
+		return;
+	}
+	if (directive !== rawDirective) fixes.push({
+		code: "directive-alias-normalized",
+		message: `Normalized ${rawDirective} to ${directive}.`,
+		line
+	});
+	switch (directive) {
+		case "@doc":
+			parseDocDirective(argument, meta, diagnostics, line);
+			return;
+		case "@title":
+			pushBlock(state, argument ? {
+				type: "title",
+				text: argument
+			} : null);
+			return;
+		case "@recital":
+			pushBlock(state, {
+				type: "recital",
+				paragraphs: takeParagraphs(state)
 			});
-			pushPending();
-			switch (canonicalDirective) {
-				case "@doc":
-					parseDocDirective(argument, meta, diagnostics, lineNumber);
-					break;
-				case "@title":
-					pending = {
-						type: "title",
-						line: lineNumber,
-						heading: argument,
-						lines: []
-					};
-					pushPending();
-					break;
-				case "@recital":
-					pending = {
-						type: "recital",
-						line: lineNumber,
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@clause":
-					pending = {
-						type: "clause",
-						line: lineNumber,
-						level: 1,
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@subclause":
-					pending = {
-						type: "clause",
-						line: lineNumber,
-						level: 2,
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@paragraph":
-					pending = {
-						type: "paragraph",
-						line: lineNumber,
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@list":
-					pending = {
-						type: "list",
-						line: lineNumber,
-						ordered: /\bordered\b/iu.test(argument),
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@table":
-					pending = {
-						type: "table",
-						line: lineNumber,
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@schedule":
-					pending = {
-						type: "schedule",
-						line: lineNumber,
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@signatures":
-					pending = {
-						type: "signatures",
-						line: lineNumber,
-						heading: argument,
-						lines: []
-					};
-					break;
-				case "@pagebreak":
-					blocks.push({ type: "pageBreak" });
-					break;
-				default: break;
-			}
-			continue;
+			return;
+		case "@clause":
+			pushBlock(state, clauseBlock(1, argument, line, state));
+			return;
+		case "@subclause":
+			pushBlock(state, clauseBlock(2, argument, line, state));
+			return;
+		case "@paragraph":
+			pushBlock(state, {
+				type: "paragraph",
+				paragraphs: takeParagraphs(state)
+			});
+			return;
+		case "@list": {
+			const ordered = /\bordered\b/iu.test(argument);
+			const items = takeRawLines(state).flatMap((rawLine) => {
+				const stripped = stripListMarker(rawLine, ordered);
+				return stripped ? [stripped] : [];
+			});
+			pushBlock(state, {
+				type: "list",
+				ordered,
+				items
+			});
+			return;
 		}
-		pending ??= {
+		case "@table":
+			pushBlock(state, parseTableBlock(takeRawLines(state), line, diagnostics, fixes));
+			return;
+		case "@schedule":
+			pushBlock(state, {
+				type: "schedule",
+				heading: stripManualNumbering(argument, line, fixes),
+				paragraphs: takeParagraphs(state)
+			});
+			return;
+		case "@signatures":
+			pushBlock(state, {
+				type: "signatures",
+				parties: parseSignatureParties(takeRawLines(state), argument)
+			});
+			return;
+		case "@pagebreak":
+			pushBlock(state, { type: "pageBreak" });
+			return;
+		default: return;
+	}
+};
+const clauseBlock = (level, rawHeading, line, state) => {
+	const heading = stripManualNumbering(rawHeading, line, state.fixes);
+	const paragraphs = takeParagraphs(state);
+	if (!heading) {
+		state.fixes.push({
+			code: "headingless-clause-downgraded",
+			message: "Converted a headingless @clause into a paragraph block.",
+			line
+		});
+		return {
 			type: "paragraph",
-			line: lineNumber,
-			heading: "",
-			lines: []
+			paragraphs
 		};
-		pending.lines.push(line);
 	}
-	pushPending();
-	if (!meta.title) {
-		const firstTitle = blocks.find((block) => block.type === "title");
-		meta.title = firstTitle?.type === "title" ? firstTitle.text : options.titleFallback ?? "Untitled document";
+	return {
+		type: "clause",
+		level,
+		heading,
+		paragraphs
+	};
+};
+const parseMarkdownHeading = (token, line, state) => {
+	const heading = token.text.trim();
+	state.fixes.push({
+		code: "markdown-heading-normalized",
+		message: "Converted a Markdown heading into a legal directive.",
+		line
+	});
+	if (token.depth === 1) {
+		pushBlock(state, heading ? {
+			type: "title",
+			text: heading
+		} : null);
+		return;
 	}
-	return applyDocumentAutofixes({
-		diagnostics,
-		draft: {
-			meta,
-			blocks
-		},
-		fixes
+	pushBlock(state, clauseBlock(Math.min(token.depth - 1, MAX_CLAUSE_LEVEL), heading, line, state));
+};
+/**
+* Markdown outside any directive. Consecutive prose stays one paragraph
+* block (several paragraphs), while a list or table is its own block so
+* markdown lists get real numbering instead of literal `-` markers.
+*/
+const parseBareMarkdown = (state) => {
+	const token = state.cursor.current;
+	if (token === void 0) return;
+	if (isTokenType(token, "list")) {
+		state.cursor.advance();
+		pushBlock(state, {
+			type: "list",
+			ordered: token.ordered,
+			items: flattenListItems(token)
+		});
+		return;
+	}
+	if (isTokenType(token, "table")) {
+		state.cursor.advance();
+		pushBlock(state, {
+			type: "table",
+			table: {
+				headers: token.header.map((cell) => cellText(cell)),
+				rows: token.rows.map((row) => row.map((cell) => cellText(cell)))
+			}
+		});
+		return;
+	}
+	const before = state.cursor.position;
+	const paragraphs = takeParagraphs(state);
+	if (paragraphs.length > 0) {
+		pushBlock(state, {
+			type: "paragraph",
+			paragraphs
+		});
+		return;
+	}
+	if (state.cursor.position === before) state.cursor.advance();
+};
+/**
+* Consecutive prose tokens as paragraph strings: paragraphs (soft line
+* breaks collapsed to spaces), blockquotes, code blocks, and raw HTML. Stops
+* at the next directive, heading, list, or table so those keep their order.
+*/
+const takeParagraphs = (state) => {
+	const paragraphs = [];
+	for (;;) {
+		const token = state.cursor.current;
+		if (token === void 0 || startsStructure(token)) return paragraphs;
+		if (isTokenType(token, "list") || isTokenType(token, "table")) return paragraphs;
+		const prose = proseParagraphs(token);
+		if (prose === null) return paragraphs;
+		state.cursor.advance();
+		paragraphs.push(...prose);
+	}
+};
+/** The paragraph strings of one prose token, or `null` when the token is not prose. */
+const proseParagraphs = (token) => {
+	if (token.type === "space" || token.type === "hr") return [];
+	if (isTokenType(token, "paragraph") || isTokenType(token, "text")) {
+		const text = collapseSoftBreaks(token.text);
+		return text ? [text] : [];
+	}
+	if (isTokenType(token, "blockquote")) return token.tokens.flatMap((inner) => proseParagraphs(inner) ?? []);
+	if (isTokenType(token, "code")) return token.text.split("\n").flatMap((codeLine) => {
+		const trimmed = codeLine.trim();
+		return trimmed ? [escapeInlineMarkdown(trimmed)] : [];
 	});
+	if (isTokenType(token, "html")) {
+		const text = collapseSoftBreaks(token.text);
+		return text ? [text] : [];
+	}
+	return null;
 };
+/**
+* Raw source lines of everything up to the next directive or heading, for
+* the line-oriented directive bodies (`@list`, `@table`, `@signatures`).
+*/
+const takeRawLines = (state) => {
+	let raw = "";
+	for (;;) {
+		const token = state.cursor.current;
+		if (token === void 0 || startsStructure(token)) break;
+		state.cursor.advance();
+		raw += token.raw;
+	}
+	return raw.split("\n").map((rawLine) => rawLine.trimEnd());
+};
+const flattenListItems = (list) => {
+	const items = [];
+	for (const item of list.items) {
+		const parts = [];
+		const nested = [];
+		for (const child of item.tokens) {
+			if (isTokenType(child, "list")) {
+				nested.push(child);
+				continue;
+			}
+			parts.push(...proseParagraphs(child) ?? []);
+		}
+		const text = parts.join(" ").trim();
+		if (text) items.push(text);
+		for (const nestedList of nested) items.push(...flattenListItems(nestedList));
+	}
+	return items;
+};
+const cellText = (cell) => collapseSoftBreaks(cell.text);
+const INLINE_MARKDOWN_SPECIALS = /[\\`*_[\]<>~!]/gu;
+/** Backslash-escape the inline markdown syntax so the text renders verbatim. */
+const escapeInlineMarkdown = (text) => text.replaceAll(INLINE_MARKDOWN_SPECIALS, (char) => `\\${char}`);
+const collapseSoftBreaks = (text) => text.split("\n").map((textLine) => textLine.trim()).filter((textLine) => textLine.length > 0).join(" ");
 const parseDocDirective = (argument, meta, diagnostics, line) => {
 	const attrs = parseAttributes(argument);
 	const kind = attrs.get("kind");
@@ -1164,84 +1551,12 @@ const isAsciiAlphaNumeric = (char) => {
 	if (code === void 0) return false;
 	return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122;
 };
-const parseMarkdownHeading = (line) => {
-	let depth = 0;
-	for (const char of line) {
-		if (char !== "#") break;
-		depth++;
-	}
-	if (depth < 1 || depth > 6 || line.at(depth) !== " ") return null;
-	const heading = line.slice(depth + 1).trim();
-	return heading ? {
-		depth,
-		heading
-	} : null;
-};
-const pendingToBlock = (pending, diagnostics, fixes) => {
-	switch (pending.type) {
-		case "title": {
-			const text = pending.heading || paragraphText(pending.lines);
-			if (!text) return null;
-			return {
-				type: "title",
-				text
-			};
-		}
-		case "recital": return {
-			type: "recital",
-			paragraphs: compactParagraphs(pending.lines)
-		};
-		case "clause": {
-			const heading = stripManualNumbering(pending.heading, pending.line, fixes);
-			if (!heading) {
-				fixes.push({
-					code: "headingless-clause-downgraded",
-					message: "Converted a headingless @clause into a paragraph block.",
-					line: pending.line
-				});
-				return {
-					type: "paragraph",
-					paragraphs: compactParagraphs(pending.lines)
-				};
-			}
-			return {
-				type: "clause",
-				level: pending.level,
-				heading,
-				paragraphs: compactParagraphs(pending.lines)
-			};
-		}
-		case "paragraph": return {
-			type: "paragraph",
-			paragraphs: compactParagraphs(pending.lines)
-		};
-		case "list": return {
-			type: "list",
-			ordered: pending.ordered,
-			items: pending.lines.flatMap((line) => {
-				const stripped = stripListMarker(line, pending.ordered);
-				return stripped ? [stripped] : [];
-			})
-		};
-		case "table": return parseTableBlock(pending, diagnostics, fixes);
-		case "schedule": return {
-			type: "schedule",
-			heading: stripManualNumbering(pending.heading, pending.line, fixes),
-			paragraphs: compactParagraphs(pending.lines)
-		};
-		case "signatures": return {
-			type: "signatures",
-			parties: parseSignatureParties(pending.lines, pending.heading)
-		};
-		default: return null;
-	}
-};
-const parseTableBlock = (pending, diagnostics, fixes) => {
-	const rows = pending.lines.flatMap((rawLine) => {
-		const line = rawLine.trim();
-		return line.startsWith("|") ? [line] : [];
-	}).flatMap((line) => {
-		const row = parsePipeRow(line);
+const parseTableBlock = (lines, line, diagnostics, fixes) => {
+	const rows = lines.flatMap((rawLine) => {
+		const trimmed = rawLine.trim();
+		return trimmed.startsWith("|") ? [trimmed] : [];
+	}).flatMap((tableLine) => {
+		const row = parsePipeRow(tableLine);
 		return row.length > 0 ? [row] : [];
 	});
 	const header = rows.at(0) ?? [];
@@ -1250,7 +1565,7 @@ const parseTableBlock = (pending, diagnostics, fixes) => {
 		fixes.push({
 			code: "table-row-width-normalized",
 			message: "Normalized a table row to match the header width.",
-			line: pending.line
+			line
 		});
 		return header.map((_, index) => row.at(index) ?? "");
 	});
@@ -1258,7 +1573,7 @@ const parseTableBlock = (pending, diagnostics, fixes) => {
 		code: "missing-table-header",
 		message: "Table directives must include a pipe-table header row.",
 		severity: "error",
-		line: pending.line
+		line
 	});
 	return {
 		type: "table",
@@ -1380,8 +1695,8 @@ const parseSignatureParties = (lines, heading) => {
 		current = { name };
 	};
 	if (heading.trim()) startParty(heading.trim().replace(/^party:\s*/iu, ""));
-	for (const line of lines) {
-		const trimmed = line.trim();
+	for (const rawLine of lines) {
+		const trimmed = rawLine.trim();
 		if (!trimmed) continue;
 		const separatorIndex = trimmed.indexOf(":");
 		if (separatorIndex === -1) {
@@ -1414,31 +1729,13 @@ const parseSignatureParties = (lines, heading) => {
 };
 const ORDERED_LIST_MARKER_RE = /^(?:\d+(?:\.\d+)+|\d+[.)])\s+/u;
 const MANUAL_NUMBERING_PREFIX_RE = /^(?:\d+(?:\.\d+)+|\d+[.)]|[A-Za-z][.)]|\([a-zivx]+\))\s+/u;
-const stripListMarker = (line, ordered) => {
-	const trimmed = line.trim();
+const stripListMarker = (rawLine, ordered) => {
+	const trimmed = rawLine.trim();
 	if (ordered) return trimmed.replace(ORDERED_LIST_MARKER_RE, "");
 	return trimmed.replace(/^[-*•]\s+/u, "");
 };
-const parsePipeRow = (line) => line.replace(/^\|/u, "").replace(/\|$/u, "").split("|").map((cell) => cell.trim());
+const parsePipeRow = (tableLine) => tableLine.replace(/^\|/u, "").replace(/\|$/u, "").split("|").map((cell) => cell.trim());
 const isMarkdownDividerRow = (row) => row.every((cell) => /^:?-{3,}:?$/u.test(cell));
-const compactParagraphs = (lines) => {
-	const paragraphs = [];
-	let current = [];
-	for (const line of lines) {
-		const trimmed = line.trim();
-		if (!trimmed) {
-			if (current.length > 0) {
-				paragraphs.push(current.join(" "));
-				current = [];
-			}
-			continue;
-		}
-		current.push(trimmed);
-	}
-	if (current.length > 0) paragraphs.push(current.join(" "));
-	return paragraphs;
-};
-const paragraphText = (lines) => compactParagraphs(lines).join(" ");
 const stripManualNumbering = (value, line, fixes) => {
 	const stripped = value.trim().replace(MANUAL_NUMBERING_PREFIX_RE, "");
 	if (stripped !== value.trim()) fixes.push({
@@ -1455,8 +1752,32 @@ const isPageSize = (value) => value === "A4" || value === "Letter";
 const isPageOrientation = (value) => value === "portrait" || value === "landscape";
 //#endregion
 //#region src/legal-source/validate.ts
+const WHOLE_TEXT_EMPHASIS = /^(?:\*\*[^*]+\*\*|__[^_]+__)$/u;
+/** Body strings of a block that a reader would expect to be prose, not a heading. */
+const bodyStrings = (block) => {
+	switch (block.type) {
+		case "paragraph":
+		case "recital":
+		case "clause":
+		case "schedule": return block.paragraphs;
+		case "list": return block.items;
+		case "table": return block.table.rows.flat();
+		case "title":
+		case "signatures":
+		case "pageBreak": return [];
+		default: return [];
+	}
+};
 const validateLegalDraft = (draft) => {
 	const diagnostics = [];
+	for (const block of draft.blocks) if (bodyStrings(block).some((text) => WHOLE_TEXT_EMPHASIS.test(text.trim()))) {
+		diagnostics.push({
+			code: "whole-paragraph-emphasis",
+			message: "A body paragraph, list item, or table cell is bold from end to end; use a clause heading for headings and keep bold for short labels.",
+			severity: "warning"
+		});
+		break;
+	}
 	if (!draft.meta.title?.trim()) diagnostics.push({
 		code: "missing-title",
 		message: "The draft must have a title.",
@@ -1616,35 +1937,15 @@ const paragraph = (text, styleId, runOptions = {}, numPr, pageBreakBefore = fals
 		...numPr ? { numPr } : {},
 		...pageBreakBefore ? { pageBreakBefore: true } : {}
 	},
-	content: textRunsWithPlaceholders(text, runOptions)
+	content: inlineMarkdownToRuns(text, {
+		base: runOptions,
+		placeholders: true
+	})
 });
-const PLACEHOLDER_PATTERN = /\[\[(?<inner>[^\][]+?)\]\]/gu;
-const textRunsWithPlaceholders = (text, options = {}) => {
-	if (!text.includes("[[")) return [textRun(text, options)];
-	const runs = [];
-	let cursor = 0;
-	for (const match of text.matchAll(PLACEHOLDER_PATTERN)) {
-		const start = match.index;
-		if (start > cursor) runs.push(textRun(text.slice(cursor, start), options));
-		const inner = match.groups?.["inner"] ?? "";
-		runs.push(textRun(inner, options, { highlight: "yellow" }));
-		cursor = start + match[0].length;
-	}
-	if (cursor < text.length) runs.push(textRun(text.slice(cursor), options));
-	return runs.length > 0 ? runs : [textRun(text, options)];
-};
-const textRun = (text, options = {}, extra = {}) => ({
-	type: "run",
-	formatting: {
-		...options.bold ? { bold: true } : {},
-		...options.italic ? { italic: true } : {},
-		...extra.highlight ? { highlight: extra.highlight } : {}
-	},
-	content: [{
-		type: "text",
-		text,
-		preserveSpace: true
-	}]
+const plainParagraph = (text, styleId, runOptions = {}) => ({
+	type: "paragraph",
+	formatting: { styleId },
+	content: plainTextRuns(text, runOptions)
 });
 const table = (headers, rows) => ({
 	type: "table",
@@ -1664,16 +1965,16 @@ const signatureTable = (parties) => {
 		signatory: "",
 		title: ""
 	}];
-	const empty = () => paragraph("", "SignatureSpacer");
+	const empty = () => plainParagraph("", "SignatureSpacer");
 	const buildCell = (party) => {
 		const cellContent = [
-			paragraph(party.name, "SignatureParty", { bold: true }),
+			plainParagraph(party.name, "SignatureParty", { bold: true }),
 			empty(),
 			empty(),
-			paragraph(SIGNATURE_LINE, "SignatureRule")
+			plainParagraph(SIGNATURE_LINE, "SignatureRule")
 		];
-		if (party.signatory) cellContent.push(paragraph(party.signatory, "SignatureField"));
-		if (party.title) cellContent.push(paragraph(party.title, "SignatureField", { italic: true }));
+		if (party.signatory) cellContent.push(plainParagraph(party.signatory, "SignatureField"));
+		if (party.title) cellContent.push(plainParagraph(party.title, "SignatureField", { italic: true }));
 		return {
 			type: "tableCell",
 			content: cellContent
@@ -2059,4 +2360,157 @@ const compileLegalSourceToDocx = async (source, options = {}) => {
 	};
 };
 //#endregion
-export { DOCX_CONFORMANCE_CLASSES, DOCX_PACKAGE_ISSUE_CODES, assertValidDocumentModel, compileLegalSourceToDocument, compileLegalSourceToDocx, parseLegalSource, serializeDocumentToDocx, validateDocumentModel, validateDocxPackage, validateLegalDraft };
+//#region src/markdown/content.ts
+const para = (runs, styleId) => ({
+	type: "paragraph",
+	formatting: styleId ? { styleId } : {},
+	content: runs.length > 0 ? runs : [textRun("")]
+});
+const listPara = (runs, rendering) => ({
+	type: "paragraph",
+	formatting: { numPr: {
+		numId: rendering.numId,
+		ilvl: rendering.level
+	} },
+	listRendering: rendering,
+	content: runs.length > 0 ? runs : [textRun("")]
+});
+const cellOf = (cell) => ({
+	type: "tableCell",
+	content: [para(inlineTokensToRuns(cell.tokens, cell.text))]
+});
+const tableFromToken = (token) => ({
+	type: "table",
+	rows: [{
+		type: "tableRow",
+		cells: token.header.map((cell) => cellOf(cell))
+	}, ...token.rows.map((row) => ({
+		type: "tableRow",
+		cells: row.map((cell) => cellOf(cell))
+	}))]
+});
+const LIST_INDENT_STEP_TWIPS = 720;
+const buildListLevel = (ilvl, isBullet, start) => ({
+	ilvl,
+	...!isBullet && { start },
+	numFmt: isBullet ? "bullet" : "decimal",
+	lvlText: isBullet ? "•" : `%${ilvl + 1}.`,
+	suffix: "tab",
+	pPr: {
+		indentLeft: LIST_INDENT_STEP_TWIPS * (ilvl + 1),
+		indentFirstLine: -360,
+		hangingIndent: true
+	}
+});
+/**
+* The numId a list renders under. The first list to reach a (numId, ilvl)
+* pair defines that level; a later list at the same depth under the same
+* parent shares it when it is the same kind (so sibling nested bullets share
+* one counter), and gets a numId of its own when it is not (a nested ordered
+* list must not inherit a sibling's bullet definition).
+*/
+const resolveListNumId = (numIds, parentNumId, level) => {
+	const levels = numIds.levels.get(parentNumId);
+	const existing = levels?.get(level.ilvl);
+	if (levels !== void 0 && existing === void 0) {
+		levels.set(level.ilvl, level);
+		return parentNumId;
+	}
+	if (levels !== void 0 && existing !== void 0 && existing.numFmt === level.numFmt && existing.start === level.start) return parentNumId;
+	const numId = numIds.next++;
+	numIds.levels.set(numId, /* @__PURE__ */ new Map([[level.ilvl, level]]));
+	return numId;
+};
+const listBlocks = (list, level, parentNumId, numIds) => {
+	const out = [];
+	const start = Number(list.start) || 1;
+	const decimalLevels = Array.from({ length: level + 1 }, () => "decimal");
+	const numId = resolveListNumId(numIds, parentNumId, buildListLevel(level, !list.ordered, start));
+	for (const item of list.items) {
+		const rendering = list.ordered ? {
+			marker: `%${level + 1}.`,
+			level,
+			numId,
+			isBullet: false,
+			numFmt: "decimal",
+			levelNumFmts: decimalLevels,
+			...start !== 1 && { startOverride: start }
+		} : {
+			marker: "•",
+			level,
+			numId,
+			isBullet: true
+		};
+		const inlineTokens = [];
+		const nestedLists = [];
+		for (const child of item.tokens) if (isTokenType(child, "list")) nestedLists.push(child);
+		else inlineTokens.push(child);
+		out.push(listPara(inlineTokensToRuns(inlineTokens, item.text), rendering));
+		for (const nested of nestedLists) out.push(...listBlocks(nested, level + 1, numId, numIds));
+	}
+	return out;
+};
+const MAX_HEADING_LEVEL = 4;
+const blocksFromTokens = (tokens, numIds) => {
+	const blocks = [];
+	for (const token of tokens ?? []) if (isTokenType(token, "heading")) {
+		const level = Math.min(Math.max(token.depth, 1), MAX_HEADING_LEVEL);
+		blocks.push(para(inlineTokensToRuns(token.tokens, token.text), `Heading${level}`));
+	} else if (isTokenType(token, "paragraph")) blocks.push(para(inlineTokensToRuns(token.tokens, token.text)));
+	else if (isTokenType(token, "list")) {
+		const numId = numIds.next++;
+		numIds.levels.set(numId, /* @__PURE__ */ new Map());
+		blocks.push(...listBlocks(token, 0, numId, numIds));
+	} else if (isTokenType(token, "table")) blocks.push(tableFromToken(token));
+	else if (isTokenType(token, "code")) for (const line of token.text.split("\n")) blocks.push(para([textRun(line.length > 0 ? line : " ", { mono: true })]));
+	else if (isTokenType(token, "blockquote")) for (const inner of blocksFromTokens(token.tokens, numIds)) {
+		const styled = inner.type === "paragraph" ? {
+			...inner,
+			formatting: {
+				...inner.formatting,
+				styleId: "Quote"
+			}
+		} : inner;
+		blocks.push(styled);
+	}
+	else if (token.type === "hr") blocks.push(para([textRun("———")]));
+	else if (token.type !== "space" && "text" in token && typeof token.text === "string" && token.text.trim().length > 0) blocks.push(para([textRun(token.text)]));
+	return blocks;
+};
+const buildNumbering = (numIdLevels) => {
+	const abstractNums = [];
+	const nums = [];
+	for (const [numId, levels] of numIdLevels) {
+		const sortedLevels = [...levels.entries()].sort(([a], [b]) => a - b).map(([, lvl]) => lvl);
+		abstractNums.push({
+			abstractNumId: numId,
+			multiLevelType: sortedLevels.length > 1 ? "multilevel" : "singleLevel",
+			levels: sortedLevels
+		});
+		nums.push({
+			numId,
+			abstractNumId: numId
+		});
+	}
+	return {
+		abstractNums,
+		nums
+	};
+};
+/**
+* Parse GFM markdown into document blocks plus the numbering its lists need.
+* Synchronous. The caller places the blocks into a `Document` of its own
+* (page geometry, styles, and presets are the host's decision).
+*/
+const compileMarkdownToContent = (markdown) => {
+	const numIds = {
+		next: 1,
+		levels: /* @__PURE__ */ new Map()
+	};
+	return {
+		content: blocksFromTokens(lexMarkdown(markdown), numIds),
+		...numIds.levels.size > 0 && { numbering: buildNumbering(numIds.levels) }
+	};
+};
+//#endregion
+export { DOCX_CONFORMANCE_CLASSES, DOCX_PACKAGE_ISSUE_CODES, assertValidDocumentModel, compileLegalSourceToDocument, compileLegalSourceToDocx, compileMarkdownToContent, parseLegalSource, sanitizeExternalUrl, serializeDocumentToDocx, validateDocumentModel, validateDocxPackage, validateLegalDraft };