@stll/docx-core 0.17.2 → 0.18.0

package/README.md

@@ -4,8 +4,9 @@ A typed OOXML/DOCX document model with parsing, validation, and serialization.
 
 The package exposes a structured document model (paragraphs, runs, tables,
 styles, section properties) together with the tools to produce and check DOCX
-packages, plus a legal-source compiler that turns a plain legal draft into that
-model or a finished DOCX file.
+packages, plus a legal-source compiler that turns a legal draft (GFM markdown
+plus `@` directives) into that model or a finished DOCX file, and a plain
+markdown reader (`compileMarkdownToContent`) that shares its parser.
 
 ```ts
 import { compileLegalSourceToDocx, validateDocxPackage } from "@stll/docx-core";
@@ -30,7 +31,8 @@ bun add @stll/docx-core
 
 - `.` — the document model types, the legal-source compiler
   (`parseLegalSource`, `compileLegalSourceToDocument`,
-  `compileLegalSourceToDocx`, `validateLegalDraft`), DOCX serialization
+  `compileLegalSourceToDocx`, `validateLegalDraft`), the markdown reader
+  (`compileMarkdownToContent`, `sanitizeExternalUrl`), DOCX serialization
   (`serializeDocumentToDocx`), and validation (`validateDocxPackage`,
   `validateDocumentModel`, `assertValidDocumentModel`).
 - `./model` — the document model types only.

package/dist/{document-P4LhYoK3.d.ts → document-C4ms2O35.d.ts}

@@ -1153,6 +1153,8 @@ type TextBox = {
   autoFit?: ShapeTextBody["autoFit"];
   /** Horizontal text wrapping inside the box */
   textWrap?: ShapeTextBody["textWrap"];
+  /** Vertical text alignment inside the box */
+  verticalAlign?: ShapeTextBody["anchor"];
   /** Internal margins */
   margins?: {
     top?: number;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Dt as RunContent, Et as Run, Kt as Table, Mt as SectionProperties, N as DocumentBody, Xt as TableRow, a as DocxPackage, b as BlockContent, bt as ParagraphContent, en as TextContent, i as DocxConformanceClass, n as Document, p as Style, qt as TableCell, t as DOCX_CONFORMANCE_CLASSES, w as BreakContent, wt as PositionalTab, yt as Paragraph } from "./document-P4LhYoK3.js";
+import { Dt as RunContent, Et as Run, Kt as Table, Mt as SectionProperties, N as DocumentBody, Xt as TableRow, a as DocxPackage, b as BlockContent, bt as ParagraphContent, en as TextContent, i as DocxConformanceClass, mn as NumberingDefinitions, n as Document, p as Style, qt as TableCell, t as DOCX_CONFORMANCE_CLASSES, w as BreakContent, wt as PositionalTab, yt as Paragraph } from "./document-C4ms2O35.js";
 import { Buffer } from "node:buffer";
 //#region src/legal-source/types.d.ts
 type LegalDocumentKind = "agreement" | "letter" | "memo" | "checklist" | "pleading" | "other";
@@ -24,6 +24,12 @@ type LegalSignatureParty = {
   signatory?: string;
   title?: string;
 };
+/**
+ * A parsed draft block. Every `text`, `heading`, paragraph, list item, and
+ * table cell string keeps its inline GFM markdown (`**bold**`, `*italic*`,
+ * `[link](https://…)`, `` `code` ``) and `[[placeholder]]` markers; the
+ * compiler renders them into runs.
+ */
 type LegalDraftBlock = {
   type: "title";
   text: string;
@@ -114,6 +120,29 @@ declare const validateLegalDraft: (draft: LegalDraft) => LegalDraftDiagnostic[];
 //#region src/legal-source/index.d.ts
 declare const compileLegalSourceToDocx: (source: string, options?: LegalSourceCompileOptions) => Promise<LegalSourceDocxCompileResult>;
 //#endregion
+//#region src/markdown/content.d.ts
+/** Block content and the numbering definitions its list paragraphs reference. */
+type MarkdownContent = {
+  content: BlockContent[];
+  /** Present only when the markdown contained at least one list. */
+  numbering?: NumberingDefinitions;
+};
+/**
+ * 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).
+ */
+declare const compileMarkdownToContent: (markdown: string) => MarkdownContent;
+//#endregion
+//#region src/markdown/href.d.ts
+/**
+ * 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.
+ */
+declare const sanitizeExternalUrl: (rawUrl: string | undefined) => string | undefined;
+//#endregion
 //#region src/serialize/docx.d.ts
 type SerializeDocumentOptions = {
   /** BCP-47 language tag (e.g. "en", "cs", "cs-CZ"); used for footer labels. */
@@ -150,4 +179,4 @@ declare const validateDocxPackage: (buffer: ArrayBuffer | Uint8Array) => Promise
 declare const validateDocumentModel: (document: Document) => ValidateDocumentModelResult;
 declare const assertValidDocumentModel: (document: Document) => void;
 //#endregion
-export { type Autofix, type BlockContent, type BreakContent, type CompiledLegalDocument, DOCX_CONFORMANCE_CLASSES, DOCX_PACKAGE_ISSUE_CODES, type Document, type DocumentBody, type DocxConformanceClass, type DocxPackage, type DocxPackageIssueCode, type LegalDraft, type LegalDraftBlock, type LegalDraftDiagnostic, type LegalSourceCompileOptions, type LegalSourceCompileResult, type LegalSourceDocxCompileResult, type LegalSourceParseResult, type Paragraph, type ParagraphContent, type PositionalTab, type Run, type RunContent, type SectionProperties, type Style, type Table, type TableCell, type TableRow, type TextContent, type ValidateDocumentModelIssue, type ValidateDocumentModelResult, type ValidateDocxPackageResult, assertValidDocumentModel, compileLegalSourceToDocument, compileLegalSourceToDocx, parseLegalSource, serializeDocumentToDocx, validateDocumentModel, validateDocxPackage, validateLegalDraft };
+export { type Autofix, type BlockContent, type BreakContent, type CompiledLegalDocument, DOCX_CONFORMANCE_CLASSES, DOCX_PACKAGE_ISSUE_CODES, type Document, type DocumentBody, type DocxConformanceClass, type DocxPackage, type DocxPackageIssueCode, type LegalDraft, type LegalDraftBlock, type LegalDraftDiagnostic, type LegalSourceCompileOptions, type LegalSourceCompileResult, type LegalSourceDocxCompileResult, type LegalSourceParseResult, type MarkdownContent, type Paragraph, type ParagraphContent, type PositionalTab, type Run, type RunContent, type SectionProperties, type Style, type Table, type TableCell, type TableRow, type TextContent, type ValidateDocumentModelIssue, type ValidateDocumentModelResult, type ValidateDocxPackageResult, assertValidDocumentModel, compileLegalSourceToDocument, compileLegalSourceToDocx, compileMarkdownToContent, parseLegalSource, sanitizeExternalUrl, serializeDocumentToDocx, validateDocumentModel, validateDocxPackage, validateLegalDraft };

package/dist/index.js

@@ -2,6 +2,7 @@ import { i as isOoxmlSymbolCharacter, t as DOCX_CONFORMANCE_CLASSES } from "./do
 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, "");
@@ -828,12 +829,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 +1084,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 +1098,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;
+	}
+	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;
 	}
-	return applyDocumentAutofixes({
-		diagnostics,
-		draft: {
-			meta,
-			blocks
-		},
-		fixes
+	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 +1548,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 +1562,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 +1570,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 +1692,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 +1726,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 +1749,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 +1934,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 +1962,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 +2357,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 };

package/dist/model/document.d.ts

@@ -1,2 +1,2 @@
-import { $ as ImagePosition, $t as TextBox, A as ComplexField, An as TableFormatting, At as SdtType, B as FieldCharContent, Bn as KnownBorderStyle, Bt as ShapeTextBody, C as BookmarkStart, Cn as SpacingExplicit, Ct as PictureWatermark, D as CommentRangeEnd, Dn as TableBorders, Dt as RunContent, E as Comment, En as TabStopAlignment, Et as Run, F as DrawingRawXmlMode, Fn as TextEffect, Ft as Shape, G as FootnoteProperties, Gt as TabContent, H as FooterReference, Hn as ThemeColorSlot, Ht as SimpleField, I as Endnote, In as TextFormatting, It as ShapeContent, J as HeaderReference, Jt as TableCellPropertyChange, K as HeaderFooter, Kt as Table, L as EndnotePosition, Ln as UnderlineStyle, Lt as ShapeFill, M as Deletion, Mn as TableMeasurement, Mt as SectionProperties, N as DocumentBody, Nn as TableRowFormatting, Nt as SectionPropertyChange, O as CommentRangeStart, On as TableCellBorders, Ot as RunPropertyChange, P as DrawingContent, Pn as TableWidthType, Pt as SectionStart, Q as ImagePadding, Qt as TableStructuralChangeInfo, R as EndnoteProperties, Rn as BorderSpec, Rt as ShapeGeometryAdjustment, S as BookmarkEnd, Sn as ParagraphFormatting, St as ParagraphPropertyChange, T as Column, Tn as TabStop, Tt as PropertyChangeInfo, U as Footnote, Ut as SoftHyphenContent, V as FieldType, Vn as ShadingProperties, Vt as ShapeType, W as FootnotePosition, Wt as SymbolContent, X as Image, Xt as TableRow, Y as Hyperlink, Yt as TablePropertyChange, Z as ImageCrop, Zt as TableRowPropertyChange, _ as ThemeColorScheme, _n as ConditionalFormatStyle, _t as NoteReferenceContent, a as DocxPackage, an as Watermark, at as InstrTextContent, b as BlockContent, bn as LineSpacingRule, bt as ParagraphContent, c as FontTable, cn as AbstractNumbering, ct as MathEquation, d as RelationshipMap, dn as ListMarkerFormatting, dt as MoveFromRangeStart, en as TextContent, et as ImageSize, f as RelationshipType, fn as ListRendering, ft as MoveTo, g as Theme, gn as CellMargins, gt as NoteNumberRestart, h as StyleType, hn as NumberingInstance, ht as NoBreakHyphenContent, i as DocxConformanceClass, in as VerticalAlign, it as Insertion, j as DRAWING_RAW_XML_MODES, jn as TableLook, jt as Section, k as CommentReference, kn as TableCellFormatting, kt as SdtProperties, l as MediaFile, ln as LevelSuffix, lt as MoveFrom, m as StyleDefinitions, mn as NumberingDefinitions, mt as MoveToRangeStart, n as Document, nn as TrackedChangeInfo, nt as ImageWrap, o as DocDefaults, on as isOoxmlSymbolCharacter, ot as LineNumberRestart, p as Style, pn as NumberFormat, pt as MoveToRangeEnd, q as HeaderFooterType, qt as TableCell, r as DocumentSettings, rn as TrackedRunChange, rt as InlineSdt, s as FontInfo, sn as normalizeRevisionId, st as MAX_REVISION_ID, t as DOCX_CONFORMANCE_CLASSES, tn as TextWatermark, tt as ImageTransform, u as Relationship, un as ListLevel, ut as MoveFromRangeEnd, v as ThemeFont, vn as EmphasisMark, vt as PageOrientation, w as BreakContent, wn as TabLeader, wt as PositionalTab, x as BlockSdt, xn as ParagraphAlignment, xt as ParagraphMarkChange, y as ThemeFontScheme, yn as FloatingTableProperties, yt as Paragraph, z as Field, zn as ColorValue, zt as ShapeOutline } from "../document-P4LhYoK3.js";
+import { $ as ImagePosition, $t as TextBox, A as ComplexField, An as TableFormatting, At as SdtType, B as FieldCharContent, Bn as KnownBorderStyle, Bt as ShapeTextBody, C as BookmarkStart, Cn as SpacingExplicit, Ct as PictureWatermark, D as CommentRangeEnd, Dn as TableBorders, Dt as RunContent, E as Comment, En as TabStopAlignment, Et as Run, F as DrawingRawXmlMode, Fn as TextEffect, Ft as Shape, G as FootnoteProperties, Gt as TabContent, H as FooterReference, Hn as ThemeColorSlot, Ht as SimpleField, I as Endnote, In as TextFormatting, It as ShapeContent, J as HeaderReference, Jt as TableCellPropertyChange, K as HeaderFooter, Kt as Table, L as EndnotePosition, Ln as UnderlineStyle, Lt as ShapeFill, M as Deletion, Mn as TableMeasurement, Mt as SectionProperties, N as DocumentBody, Nn as TableRowFormatting, Nt as SectionPropertyChange, O as CommentRangeStart, On as TableCellBorders, Ot as RunPropertyChange, P as DrawingContent, Pn as TableWidthType, Pt as SectionStart, Q as ImagePadding, Qt as TableStructuralChangeInfo, R as EndnoteProperties, Rn as BorderSpec, Rt as ShapeGeometryAdjustment, S as BookmarkEnd, Sn as ParagraphFormatting, St as ParagraphPropertyChange, T as Column, Tn as TabStop, Tt as PropertyChangeInfo, U as Footnote, Ut as SoftHyphenContent, V as FieldType, Vn as ShadingProperties, Vt as ShapeType, W as FootnotePosition, Wt as SymbolContent, X as Image, Xt as TableRow, Y as Hyperlink, Yt as TablePropertyChange, Z as ImageCrop, Zt as TableRowPropertyChange, _ as ThemeColorScheme, _n as ConditionalFormatStyle, _t as NoteReferenceContent, a as DocxPackage, an as Watermark, at as InstrTextContent, b as BlockContent, bn as LineSpacingRule, bt as ParagraphContent, c as FontTable, cn as AbstractNumbering, ct as MathEquation, d as RelationshipMap, dn as ListMarkerFormatting, dt as MoveFromRangeStart, en as TextContent, et as ImageSize, f as RelationshipType, fn as ListRendering, ft as MoveTo, g as Theme, gn as CellMargins, gt as NoteNumberRestart, h as StyleType, hn as NumberingInstance, ht as NoBreakHyphenContent, i as DocxConformanceClass, in as VerticalAlign, it as Insertion, j as DRAWING_RAW_XML_MODES, jn as TableLook, jt as Section, k as CommentReference, kn as TableCellFormatting, kt as SdtProperties, l as MediaFile, ln as LevelSuffix, lt as MoveFrom, m as StyleDefinitions, mn as NumberingDefinitions, mt as MoveToRangeStart, n as Document, nn as TrackedChangeInfo, nt as ImageWrap, o as DocDefaults, on as isOoxmlSymbolCharacter, ot as LineNumberRestart, p as Style, pn as NumberFormat, pt as MoveToRangeEnd, q as HeaderFooterType, qt as TableCell, r as DocumentSettings, rn as TrackedRunChange, rt as InlineSdt, s as FontInfo, sn as normalizeRevisionId, st as MAX_REVISION_ID, t as DOCX_CONFORMANCE_CLASSES, tn as TextWatermark, tt as ImageTransform, u as Relationship, un as ListLevel, ut as MoveFromRangeEnd, v as ThemeFont, vn as EmphasisMark, vt as PageOrientation, w as BreakContent, wn as TabLeader, wt as PositionalTab, x as BlockSdt, xn as ParagraphAlignment, xt as ParagraphMarkChange, y as ThemeFontScheme, yn as FloatingTableProperties, yt as Paragraph, z as Field, zn as ColorValue, zt as ShapeOutline } from "../document-C4ms2O35.js";
 export { type AbstractNumbering, type BlockContent, type BlockSdt, type BookmarkEnd, type BookmarkStart, type BorderSpec, type BreakContent, type CellMargins, type ColorValue, type Column, type Comment, type CommentRangeEnd, type CommentRangeStart, type CommentReference, type ComplexField, type ConditionalFormatStyle, DOCX_CONFORMANCE_CLASSES, DRAWING_RAW_XML_MODES, type Deletion, type DocDefaults, Document, type DocumentBody, DocumentSettings, DocxConformanceClass, DocxPackage, type DrawingContent, type DrawingRawXmlMode, type EmphasisMark, type Endnote, type EndnotePosition, type EndnoteProperties, type Field, type FieldCharContent, type FieldType, type FloatingTableProperties, type FontInfo, type FontTable, type FooterReference, type Footnote, type FootnotePosition, type FootnoteProperties, type HeaderFooter, type HeaderFooterType, type HeaderReference, type Hyperlink, type Image, type ImageCrop, type ImagePadding, type ImagePosition, type ImageSize, type ImageTransform, type ImageWrap, type InlineSdt, type Insertion, type InstrTextContent, type KnownBorderStyle, type LevelSuffix, type LineNumberRestart, type LineSpacingRule, type ListLevel, type ListMarkerFormatting, type ListRendering, MAX_REVISION_ID, type MathEquation, type MediaFile, type MoveFrom, type MoveFromRangeEnd, type MoveFromRangeStart, type MoveTo, type MoveToRangeEnd, type MoveToRangeStart, type NoBreakHyphenContent, type NoteNumberRestart, type NoteReferenceContent, type NumberFormat, type NumberingDefinitions, type NumberingInstance, type PageOrientation, type Paragraph, type ParagraphAlignment, type ParagraphContent, type ParagraphFormatting, type ParagraphMarkChange, type ParagraphPropertyChange, type PictureWatermark, type PositionalTab, type PropertyChangeInfo, type Relationship, type RelationshipMap, type RelationshipType, type Run, type RunContent, type RunPropertyChange, type SdtProperties, type SdtType, type Section, type SectionProperties, type SectionPropertyChange, type SectionStart, type ShadingProperties, type Shape, type ShapeContent, type ShapeFill, type ShapeGeometryAdjustment, type ShapeOutline, type ShapeTextBody, type ShapeType, type SimpleField, type SoftHyphenContent, type SpacingExplicit, type Style, type StyleDefinitions, type StyleType, type SymbolContent, type TabContent, type TabLeader, type TabStop, type TabStopAlignment, type Table, type TableBorders, type TableCell, type TableCellBorders, type TableCellFormatting, type TableCellPropertyChange, type TableFormatting, type TableLook, type TableMeasurement, type TablePropertyChange, type TableRow, type TableRowFormatting, type TableRowPropertyChange, type TableStructuralChangeInfo, type TableWidthType, type TextBox, type TextContent, type TextEffect, type TextFormatting, type TextWatermark, type Theme, type ThemeColorScheme, type ThemeColorSlot, type ThemeFont, type ThemeFontScheme, type TrackedChangeInfo, type TrackedRunChange, type UnderlineStyle, type VerticalAlign, type Watermark, isOoxmlSymbolCharacter, normalizeRevisionId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/docx-core",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Typed OOXML/DOCX model, validation, serialization, legal-source compilation, and browser-native package projection.",
   "keywords": [
     "document-model",
@@ -62,7 +62,8 @@
   "dependencies": {
     "better-result": "3.0.1",
     "fast-xml-parser": "^5.10.1",
-    "jszip": "3.10.1"
+    "jszip": "3.10.1",
+    "marked": "^18.0.5"
   },
   "devDependencies": {
     "bun-types": "1.4.0",