@stll/folio-core 0.52.0 → 0.54.0

package/dist/markdown/renderRuns.js

@@ -4,7 +4,8 @@ import { decodeOoxmlSymbolCharacter } from "../utils/ooxmlSymbol.js";
 import { wrapComment, wrapDeletion, wrapInsertion, wrapMoveFrom, wrapMoveTo } from "./annotations.js";
 import { escapeAltText, escapeInline, escapeLinkUrl } from "./escape.js";
 import { registerImage } from "./images.js";
-import { pushWarning } from "./internals.js";
+import { numberNoteReference, pushWarning } from "./internals.js";
+import { compileMarkdownToContent } from "@stll/docx-core";
 //#region src/markdown/renderRuns.ts
 const MARK_DELIMS = {
 	bold: "**",
@@ -32,9 +33,9 @@ function marksFor(run) {
 	const f = run.formatting;
 	if (!f) return [];
 	const out = [];
+	if (f.strike) out.push("strike");
 	if (f.bold) out.push("bold");
 	if (f.italic) out.push("italic");
-	if (f.strike) out.push("strike");
 	const ascii = f.fontFamily?.ascii?.toLowerCase();
 	if (ascii && MONOSPACE_FONTS.has(ascii)) out.push("code");
 	return out;
@@ -42,7 +43,7 @@ function marksFor(run) {
 function applyMarks(text, marks) {
 	if (!text) return text;
 	if (marks.includes("code")) {
-		const literal = text.replace(/\\(?<char>[\\`*[\]_<])/gu, "$<char>");
+		const literal = text.replace(/\\(?<char>[\\`*[\]_<~])/gu, "$<char>");
 		let longestRun = 0;
 		for (const m of literal.matchAll(/`+/gu)) longestRun = Math.max(longestRun, m[0].length);
 		const fence = "`".repeat(longestRun + 1);
@@ -56,6 +57,133 @@ function applyMarks(text, marks) {
 	}
 	return out;
 }
+const UNKNOWN_NEIGHBORS = {
+	before: void 0,
+	after: void 0
+};
+const isBlank = (ch) => ch === "" || ch !== void 0 && /\s/u.test(ch);
+/**
+* Which mark wraps a stretch of runs first, outermost first. Strikethrough
+* goes inside emphasis: an emphasis delimiter beside a tilde opens and closes
+* wherever it stands, where the other way round (`~~*`) needs a blank or
+* punctuation outside.
+*/
+const GROUPING_ORDER = [
+	"italic",
+	"bold",
+	"strike"
+];
+/** The stackings tried, in turn, where the reader misreads one. */
+const GROUPING_ORDERS = [GROUPING_ORDER, [
+	"bold",
+	"italic",
+	"strike"
+]];
+/**
+* CommonMark punctuation (Unicode P and S categories) as a delimiter of
+* `mark` meets it. Beside an emphasis delimiter, an asterisk is another
+* delimiter that runs together with it, and a tilde does not let it close
+* (the GFM reader's rule): both count as letters. (Words carry them escaped,
+* as a two-character unit.)
+*/
+const punctuationFor = (mark) => (ch) => {
+	if (ch === void 0 || ch === "" || ch === "~") return false;
+	if (mark !== "strike" && ch === "*") return false;
+	return /[\p{P}\p{S}]/u.test(ch);
+};
+/** One escape pair (`\*`) or one code point of escaped inline text. */
+const INLINE_UNIT = /\\[\s\S]|[\s\S]/gu;
+/**
+* Wrap `inner` in `mark` so a CommonMark reader reads it back. A delimiter
+* opens only before a character that is not blank, and before punctuation
+* only where blank or punctuation precedes it; closing mirrors that. Where
+* the words at an edge would stop a delimiter from opening or closing (a
+* space at the edge, emphasis ending in a full stop right before a letter),
+* those characters are left outside the emphasis rather than written as
+* literal asterisks.
+*/
+function wrapFlanking(inner, mark, { before, after }) {
+	const isPunctuation = punctuationFor(mark);
+	const opensAfter = (ch) => isBlank(ch) || isPunctuation(ch);
+	const units = Array.from(inner.matchAll(INLINE_UNIT), ([unit]) => unit);
+	const isPunctuationUnit = (unit) => unit.length === 2 && unit.startsWith("\\") || isPunctuation(unit);
+	let start = 0;
+	let end = units.length;
+	let outside = before;
+	for (;;) {
+		const unit = units[start];
+		if (unit === void 0 || start >= end) break;
+		if (!isBlank(unit) && (!isPunctuationUnit(unit) || opensAfter(outside))) break;
+		outside = unit.at(-1);
+		start++;
+	}
+	outside = after;
+	for (;;) {
+		const unit = units[end - 1];
+		if (unit === void 0 || end <= start) break;
+		if (!isBlank(unit) && (!isPunctuationUnit(unit) || opensAfter(outside))) break;
+		outside = unit.at(0);
+		end--;
+	}
+	return units.slice(0, start).join("") + applyMarks(units.slice(start, end).join(""), start < end ? [mark] : []) + units.slice(end).join("");
+}
+/** Paragraph content that writes nothing to the line. */
+const SILENT_MARKERS = /* @__PURE__ */ new Set([
+	"bookmarkStart",
+	"bookmarkEnd",
+	"moveFromRangeStart",
+	"moveFromRangeEnd",
+	"moveToRangeStart",
+	"moveToRangeEnd"
+]);
+/** Comment range markers, which write nothing when comments are stripped. */
+const COMMENT_MARKERS = /* @__PURE__ */ new Set(["commentRangeStart", "commentRangeEnd"]);
+/** The first character `piece` puts on the line, inside the marks `outer` already opened. */
+const pieceStart = (piece, outer, order) => {
+	const first = piece.text.match(INLINE_UNIT)?.[0];
+	if (first === void 0 || isBlank(first)) return first;
+	const opens = order.find((mark) => piece.marks.has(mark) && !outer.has(mark));
+	if (opens === void 0) return first;
+	return opens === "strike" ? "~" : "*";
+};
+/**
+* Wrap consecutive pieces in their emphasis, one mark at a time: the pieces
+* sharing the outermost mark are wrapped once, around the rest of their
+* emphasis. Written run by run, the closing delimiter of one would meet the
+* opening one of the next (`*a**b*`), which no reader takes for two
+* emphases.
+*/
+function renderPieces(pieces, outer, edges, order = GROUPING_ORDER) {
+	let out = "";
+	let index = 0;
+	while (index < pieces.length) {
+		const piece = pieces[index];
+		if (!piece) break;
+		const mark = order.find((key) => piece.marks.has(key) && !outer.has(key));
+		if (mark === void 0) {
+			out += piece.text;
+			index++;
+			continue;
+		}
+		let last = index;
+		while (pieces[last + 1]?.marks.has(mark)) last++;
+		const next = pieces[last + 1];
+		const around = {
+			before: out.length > 0 ? out.at(-1) : edges.before,
+			after: next === void 0 ? edges.after : pieceStart(next, outer, order)
+		};
+		const inner = renderPieces(pieces.slice(index, last + 1), /* @__PURE__ */ new Set([...outer, mark]), around, order);
+		out += wrapFlanking(inner, mark, around);
+		index = last + 1;
+	}
+	return out;
+}
+/** The first character an item that is not a run puts on the line, where it is fixed. */
+function renderedStart(item) {
+	if (item?.type !== "hyperlink") return void 0;
+	const link = item;
+	return link.href || link.anchor ? "[" : void 0;
+}
 /** Render a single run's RunContent array into the inline text fragment. */
 function renderRunContent(ctx, pkg, content, paraId) {
 	let out = "";
@@ -81,17 +209,10 @@ function renderRunContent(ctx, pkg, content, paraId) {
 			out += escapeInline(item.text);
 			break;
 		case "footnoteRef":
-		case "endnoteRef": {
+		case "endnoteRef":
 			if (ctx.opts.footnotes === "strip") break;
-			const markerNumber = ctx.footnoteRefs.length + 1;
-			ctx.footnoteRefs.push({
-				refId: item.id,
-				markerNumber,
-				kind: item.type === "endnoteRef" ? "endnote" : "footnote"
-			});
-			out += `[^${markerNumber}]`;
+			out += numberNoteReference(ctx, item.type === "endnoteRef" ? "endnote" : "footnote", item.id).marker;
 			break;
-		}
 		case "drawing": {
 			const ref = resolveRelationshipIdOfType(pkg?.relationships, item.image.rId, RELATIONSHIP_TYPES.image);
 			const media = ref.status === "resolved" ? pkg?.media?.get(ref.relationship.target) : void 0;
@@ -118,21 +239,111 @@ function renderRunContent(ctx, pkg, content, paraId) {
 	}
 	return out;
 }
-/** Render a single Run with its formatting applied. */
-function renderRun(ctx, pkg, run, paraId) {
-	if (run.formatting?.hidden) return "";
+/** A run's rendered text and the emphasis it still takes; `null` when it writes nothing. */
+function pieceOf(ctx, pkg, run, paraId) {
+	if (run.formatting?.hidden) return null;
 	const inner = renderRunContent(ctx, pkg, run.content, paraId);
-	if (!inner) return "";
+	if (!inner) return null;
+	const marks = marksFor(run);
+	if (!marks.includes("code")) return {
+		text: inner,
+		marks: new Set(marks)
+	};
 	const leadLen = inner.length - inner.trimStart().length;
 	const trailLen = inner.length - inner.trimEnd().length;
 	const core = inner.slice(leadLen, inner.length - trailLen);
-	if (!core) return inner;
-	const lead = inner.slice(0, leadLen);
-	const trail = inner.slice(inner.length - trailLen);
-	return `${lead}${applyMarks(core, marksFor(run))}${trail}`;
+	return {
+		text: core ? `${inner.slice(0, leadLen)}${applyMarks(core, marks)}${inner.slice(inner.length - trailLen)}` : inner,
+		marks: /* @__PURE__ */ new Set()
+	};
+}
+/** What a markdown reader reads from one line: each character with its emphasis. */
+const readLine = (line) => compileMarkdownToContent(line).content.flatMap((block) => block.type === "paragraph" ? block.content : []).flatMap((item) => item.type === "hyperlink" ? item.children : [item]).flatMap((item) => {
+	if (item.type !== "run") return [{
+		char: "\0",
+		marks: /* @__PURE__ */ new Set()
+	}];
+	const marks = new Set(GROUPING_ORDER.filter((key) => item.formatting?.[key] === true));
+	return item.content.flatMap((content) => content.type === "text" ? Array.from(content.text, (char) => ({
+		char,
+		marks
+	})) : [{
+		char: "\0",
+		marks
+	}]);
+});
+const sameMarks = (left, right) => left.size === right.size && [...left].every((key) => right.has(key));
+/**
+* How `rendered`, between `edges`, reads back: `"exact"` with the pieces'
+* text and each letter's emphasis, `"text"` with their text alone (emphasis
+* lost somewhere, none of it read as literal asterisks), or `null`.
+*/
+const readBack = (rendered, pieces, edges) => {
+	const side = (ch) => {
+		if (ch === void 0) return "x";
+		return ch === "" ? " " : ch;
+	};
+	const line = (inner) => `x ${side(edges.before)}${inner}${side(edges.after)} x`;
+	const read = readLine(line(rendered));
+	const plain = readLine(line(pieces.map(({ text }) => text).join("")));
+	if (read.map(({ char }) => char).join("") !== plain.map(({ char }) => char).join("")) return null;
+	const expected = pieces.flatMap(({ text, marks }) => readLine(`x${text}x`).slice(1, -1).map(({ char }) => ({
+		char,
+		marks
+	})));
+	const start = Array.from(`x ${side(edges.before)}`).length;
+	const end = Array.from(`${side(edges.after)} x`).length;
+	if (read.length !== start + expected.length + end) return read.every(({ marks }) => marks.size === 0) ? "text" : null;
+	let exact = true;
+	for (const [index, { char, marks }] of expected.entries()) {
+		const at = read[start + index];
+		if (at?.char !== char) return null;
+		if ([...at.marks].some((mark) => !marks.has(mark))) return null;
+		if (/[\p{L}\p{N}]/u.test(char) && !sameMarks(at.marks, marks)) exact = false;
+	}
+	return exact ? "exact" : "text";
+};
+/**
+* Render consecutive runs with their formatting applied. The delimiters are
+* placed by the flanking rules the reader applies, and the result is checked
+* against the reader: a stacking it misreads is tried the other way round,
+* or with more punctuation left outside, and failing all of those, the runs
+* go out without emphasis rather than with stray asterisks.
+*/
+function renderRuns(ctx, pkg, runs, paraId, edges = UNKNOWN_NEIGHBORS) {
+	const pieces = runs.flatMap((run) => pieceOf(ctx, pkg, run, paraId) ?? []);
+	const plain = pieces.map(({ text }) => text).join("");
+	if (!pieces.some(({ marks }) => marks.size > 0)) return plain;
+	let fallback;
+	for (const split of [pieces, splitAtBlanks(pieces)]) for (const order of GROUPING_ORDERS) for (const neighbors of [edges, UNKNOWN_NEIGHBORS]) {
+		const rendered = renderPieces(split, /* @__PURE__ */ new Set(), neighbors, order);
+		const read = readBack(rendered, pieces, edges);
+		if (read === "exact") return rendered;
+		if (read === "text") fallback ??= rendered;
+	}
+	return fallback ?? plain;
 }
+/** The pieces with every blank a piece of its own, without emphasis. */
+const splitAtBlanks = (pieces) => pieces.flatMap((piece) => {
+	if (piece.marks.size === 0) return [piece];
+	const parts = [];
+	for (const [unit] of piece.text.matchAll(INLINE_UNIT)) {
+		const marks = isBlank(unit) ? /* @__PURE__ */ new Set() : piece.marks;
+		const last = parts.at(-1);
+		if (last && last.marks === marks) last.text += unit;
+		else parts.push({
+			text: unit,
+			marks
+		});
+	}
+	return parts;
+});
 function renderHyperlink(ctx, pkg, link, paraId) {
-	const inner = getHyperlinkRuns(link).map((run) => renderRun(ctx, pkg, run, paraId)).join("");
+	const bracketed = Boolean(link.href ?? link.anchor);
+	const inner = renderRuns(ctx, pkg, getHyperlinkRuns(link), paraId, bracketed ? {
+		before: "[",
+		after: "]"
+	} : UNKNOWN_NEIGHBORS);
 	if (!inner) return "";
 	const href = link.href ?? (link.anchor ? `#${link.anchor}` : "");
 	if (!href) {
@@ -152,17 +363,17 @@ function renderHyperlink(ctx, pkg, link, paraId) {
 function renderTrackedWrapper(ctx, pkg, wrapper, paraId) {
 	const renderChild = (child) => {
 		switch (child.type) {
-			case "run": return renderRun(ctx, pkg, child, paraId);
+			case "run": return renderRuns(ctx, pkg, [child], paraId);
 			case "hyperlink": return renderHyperlink(ctx, pkg, child, paraId);
 			case "mathEquation": return child.plainText ? escapeInline(child.plainText) : "";
 			case "inlineWrapper":
-			case "inlineSdt": return renderParagraphInline(ctx, pkg, child.content, paraId);
+			case "inlineSdt": return renderParagraphInline(ctx, pkg, child.content, paraId, UNKNOWN_NEIGHBORS);
 			case "insertion":
 			case "deletion":
 			case "moveFrom":
 			case "moveTo": return renderTrackedWrapper(ctx, pkg, child, paraId);
 			case "simpleField":
-			case "complexField": return renderParagraphInline(ctx, pkg, [child], paraId);
+			case "complexField": return renderParagraphInline(ctx, pkg, [child], paraId, UNKNOWN_NEIGHBORS);
 			case "bookmarkStart":
 			case "bookmarkEnd":
 			case "moveFromRangeStart":
@@ -173,11 +384,33 @@ function renderTrackedWrapper(ctx, pkg, wrapper, paraId) {
 			default: return child;
 		}
 	};
+	const renderChildren = () => {
+		let rendered = "";
+		let runs = [];
+		const flush = (after) => {
+			if (runs.length === 0) return;
+			rendered += renderRuns(ctx, pkg, runs, paraId, {
+				before: rendered.length > 0 ? rendered.at(-1) : void 0,
+				after
+			});
+			runs = [];
+		};
+		for (const child of wrapper.content) {
+			if (child.type === "run") {
+				runs.push(child);
+				continue;
+			}
+			flush(renderedStart(child));
+			rendered += renderChild(child);
+		}
+		flush(void 0);
+		return rendered;
+	};
 	if (ctx.opts.trackedChanges === "clean") {
-		if (wrapper.type === "insertion" || wrapper.type === "moveTo") return wrapper.content.map(renderChild).join("");
+		if (wrapper.type === "insertion" || wrapper.type === "moveTo") return renderChildren();
 		return "";
 	}
-	const inner = wrapper.content.map(renderChild).join("");
+	const inner = renderChildren();
 	switch (wrapper.type) {
 		case "insertion": return wrapInsertion(ctx, wrapper.info, inner);
 		case "deletion": return wrapDeletion(ctx, wrapper.info, inner);
@@ -189,55 +422,76 @@ function renderTrackedWrapper(ctx, pkg, wrapper, paraId) {
 * Render the full inline content of a paragraph, tracking comment-range
 * boundaries to apply the configured wrapper.
 */
-function renderParagraphInline(ctx, pkg, content, paraId) {
+function renderParagraphInline(ctx, pkg, content, paraId, edges = {
+	before: "",
+	after: ""
+}) {
 	let out = "";
 	const openComments = [];
-	for (const item of content) switch (item.type) {
-		case "run":
-			out += renderRun(ctx, pkg, item, paraId);
-			break;
-		case "hyperlink":
-			out += renderHyperlink(ctx, pkg, item, paraId);
-			break;
-		case "insertion":
-		case "deletion":
-		case "moveFrom":
-		case "moveTo":
-			out += renderTrackedWrapper(ctx, pkg, item, paraId);
-			break;
-		case "commentRangeStart":
-			out += handleCommentStart(ctx, pkg, item, openComments, out.length);
-			break;
-		case "commentRangeEnd":
-			out = handleCommentEnd(ctx, item, openComments, out);
-			break;
-		case "commentReference":
-			out += renderPointComment(ctx, pkg, item.id);
-			break;
-		case "simpleField":
-		case "complexField": {
-			const runs = item.type === "simpleField" ? item.content : item.fieldResult;
-			for (const child of runs) {
-				if (child.type === "run") {
-					out += renderRun(ctx, pkg, child, paraId);
-					continue;
+	const items = content.filter((item) => !SILENT_MARKERS.has(item.type) && !(ctx.opts.comments === "strip" && COMMENT_MARKERS.has(item.type)));
+	const around = (index) => {
+		const next = items[index + 1];
+		return {
+			before: out.length > 0 ? out.at(-1) : edges.before,
+			after: next === void 0 ? edges.after : renderedStart(next)
+		};
+	};
+	for (let index = 0; index < items.length; index++) {
+		const item = items[index];
+		if (item === void 0) break;
+		switch (item.type) {
+			case "run": {
+				const runs = [item];
+				while (items[index + 1]?.type === "run") {
+					runs.push(items[index + 1]);
+					index++;
 				}
-				if (child.type === "hyperlink") {
-					out += renderHyperlink(ctx, pkg, child, paraId);
-					continue;
+				out += renderRuns(ctx, pkg, runs, paraId, around(index));
+				break;
+			}
+			case "hyperlink":
+				out += renderHyperlink(ctx, pkg, item, paraId);
+				break;
+			case "insertion":
+			case "deletion":
+			case "moveFrom":
+			case "moveTo":
+				out += renderTrackedWrapper(ctx, pkg, item, paraId);
+				break;
+			case "commentRangeStart":
+				out += handleCommentStart(ctx, pkg, item, openComments, out.length);
+				break;
+			case "commentRangeEnd":
+				out = handleCommentEnd(ctx, item, openComments, out);
+				break;
+			case "commentReference":
+				out += renderPointComment(ctx, pkg, item.id);
+				break;
+			case "simpleField":
+			case "complexField": {
+				const runs = item.type === "simpleField" ? item.content : item.fieldResult;
+				for (const child of runs) {
+					if (child.type === "run") {
+						out += renderRuns(ctx, pkg, [child], paraId);
+						continue;
+					}
+					if (child.type === "hyperlink") {
+						out += renderHyperlink(ctx, pkg, child, paraId);
+						continue;
+					}
+					out += child.type === "inlineWrapper" ? renderParagraphInline(ctx, pkg, child.content, paraId, UNKNOWN_NEIGHBORS) : child.text;
 				}
-				out += child.type === "inlineWrapper" ? renderParagraphInline(ctx, pkg, child.content, paraId) : child.text;
+				break;
 			}
-			break;
+			case "inlineSdt":
+			case "inlineWrapper":
+				out += renderParagraphInline(ctx, pkg, item.content, paraId, around(index));
+				break;
+			case "mathEquation":
+				if (item.plainText) out += escapeInline(item.plainText);
+				break;
+			default: break;
 		}
-		case "inlineSdt":
-		case "inlineWrapper":
-			out += renderParagraphInline(ctx, pkg, item.content, paraId);
-			break;
-		case "mathEquation":
-			if (item.plainText) out += escapeInline(item.plainText);
-			break;
-		default: break;
 	}
 	while (openComments.length) {
 		const slot = openComments.pop();

package/dist/markdown/renderTable.js

@@ -1,18 +1,25 @@
+import { ALT_CHUNK_READER_DIAGNOSTIC, isAltChunkMarkup } from "../docx/altChunk.js";
 import { getHyperlinkRuns } from "../docx/hyperlinkParser.js";
+import { OPAQUE_REVISION_CARRIER_READER_DIAGNOSTIC, isOpaqueNestedRowMarkup, opaqueRevisionCarrierName } from "../docx/opaqueCarrier.js";
 import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "../docx/relsParser.js";
 import { decodeOoxmlSymbolCharacter } from "../utils/ooxmlSymbol.js";
 import { escapeTableCell } from "./escape.js";
 import { registerImage } from "./images.js";
-import { pushWarning } from "./internals.js";
+import { numberNoteReference, pushWarning } from "./internals.js";
 import { renderParagraph } from "./renderParagraph.js";
 //#region src/markdown/renderTable.ts
 /** Render a `Table` as markdown. Picks GFM vs HTML based on cell features. */
 function renderTable(ctx, pkg, table) {
 	const { rows } = table;
-	if (!rows.length) return "";
-	if (needsHtmlFallback(rows)) return renderHtmlTable(ctx, pkg, rows, true);
-	return renderGfmTable(ctx, pkg, rows, true);
+	const diagnostics = [...preservedCarrierDiagnostics(table.preserved?.children), ...rows.flatMap((row) => preservedCarrierDiagnostics(row.preserved?.children))];
+	if (!rows.length) return diagnostics.join("\n");
+	return [needsHtmlFallback(rows) ? renderHtmlTable(ctx, pkg, rows, true) : renderGfmTable(ctx, pkg, rows, true), ...diagnostics].filter(Boolean).join("\n\n");
 }
+const preservedCarrierDiagnostics = (children) => (children ?? []).flatMap(({ xml }) => {
+	if (isAltChunkMarkup(xml)) return [ALT_CHUNK_READER_DIAGNOSTIC];
+	if (opaqueRevisionCarrierName(xml) !== void 0) return [OPAQUE_REVISION_CARRIER_READER_DIAGNOSTIC];
+	return isOpaqueNestedRowMarkup(xml) ? ["[Unsupported nested w:tr content]"] : [];
+});
 function needsHtmlFallback(rows) {
 	for (const row of rows) for (const cell of row.cells) {
 		if ((cell.formatting?.gridSpan ?? 1) > 1) return true;
@@ -64,10 +71,15 @@ function renderGfmCell(ctx, pkg, cell) {
 				break;
 			}
 			case "blockSdt":
+			case "blockCustomXml":
 				renderBlocks(item.content);
 				break;
-			case "table":
+			case "table": break;
 			case "preservedBlock":
+				if (isAltChunkMarkup(item.xml)) blocks.push(item.readerText === void 0 ? ALT_CHUNK_READER_DIAGNOSTIC : `${ALT_CHUNK_READER_DIAGNOSTIC}\n${item.readerText}`);
+				else if (opaqueRevisionCarrierName(item.xml) !== void 0) blocks.push(OPAQUE_REVISION_CARRIER_READER_DIAGNOSTIC);
+				else if (isOpaqueNestedRowMarkup(item.xml)) blocks.push("[Unsupported nested w:tr content]");
+				break;
 			case "bookmarkStart":
 			case "bookmarkEnd": break;
 			default: return item;
@@ -139,9 +151,14 @@ function renderHtmlCell(ctx, pkg, cell) {
 				break;
 			}
 			case "blockSdt":
+			case "blockCustomXml":
 				renderBlocks(item.content);
 				break;
 			case "preservedBlock":
+				if (isAltChunkMarkup(item.xml)) parts.push(item.readerText === void 0 ? ALT_CHUNK_READER_DIAGNOSTIC : `${ALT_CHUNK_READER_DIAGNOSTIC} ${item.readerText}`);
+				else if (opaqueRevisionCarrierName(item.xml) !== void 0) parts.push(OPAQUE_REVISION_CARRIER_READER_DIAGNOSTIC);
+				else if (isOpaqueNestedRowMarkup(item.xml)) parts.push("[Unsupported nested w:tr content]");
+				break;
 			case "bookmarkStart":
 			case "bookmarkEnd": break;
 			default: return item;
@@ -257,13 +274,8 @@ function renderHtmlRun(ctx, pkg, run, paraId) {
 		case "footnoteRef":
 		case "endnoteRef": {
 			if (ctx.opts.footnotes === "strip") break;
-			const markerNumber = ctx.footnoteRefs.length + 1;
-			ctx.footnoteRefs.push({
-				refId: item.id,
-				markerNumber,
-				kind: item.type === "endnoteRef" ? "endnote" : "footnote"
-			});
-			text += `<sup>[${markerNumber}]</sup>`;
+			const { token } = numberNoteReference(ctx, item.type === "endnoteRef" ? "endnote" : "footnote", item.id);
+			text += `<sup>[${token}]</sup>`;
 			break;
 		}
 		default: break;

package/dist/markdown/trailers.js

@@ -18,9 +18,9 @@ import { panic } from "better-result";
 function appendTrailers(ctx, doc, body) {
 	const sections = body.trim() ? [body] : [];
 	if (ctx.footnoteRefs.length > 0) {
-		const refs = ctx.footnoteRefs.map(({ refId, markerNumber, kind }) => {
+		const refs = ctx.footnoteRefs.map(({ refId, marker, kind }) => {
 			const note = kind === "endnote" ? doc.package.endnotes?.find((n) => n.id === refId) : doc.package.footnotes?.find((f) => f.id === refId);
-			return `[^${markerNumber}]: ${note ? noteText(ctx, doc, note) : ""}`;
+			return `${marker}: ${note ? noteText(ctx, doc, note) : ""}`;
 		});
 		sections.push(refs.join("\n"));
 	}

package/dist/markdown/types.d.ts

@@ -1,4 +1,6 @@
+import { NoteReferenceKind, NoteReferenceNumbering } from "../utils/noteReferenceLabels.js";
 import { BuiltInStyleIndex } from "../docx/builtInStyles.js";
+import { ListLabelCounter } from "../prosemirror/listLabels.js";
 //#region src/markdown/types.d.ts
 /**
  * Metadata describing a single image registration. Owned by the markdown
@@ -106,12 +108,18 @@ type RenderContext = {
   imagesByPath: Map<string, ImageRef>;
   /** Diagnostics accumulator. */
   warnings: string[];
-  /** Footnote/endnote refs collected during this render, in document order. */
+  /**
+   * Footnote/endnote refs collected during this render, one per note in the
+   * order it is first referenced. `marker` is what the body line shows
+   * (`[^1]`, `[^e1]`) and what the definition trailer repeats.
+   */
   footnoteRefs: {
     refId: number;
-    markerNumber: number;
-    kind: "footnote" | "endnote";
+    marker: string;
+    kind: NoteReferenceKind;
   }[];
+  /** Reading-order note numbering, shared with the AI text view. */
+  noteNumbering: NoteReferenceNumbering;
   /** Comment refs collected during this render (sidecar mode only). */
   commentRefs: {
     commentId: number;
@@ -124,12 +132,26 @@ type RenderContext = {
   }[];
   /** 1-based counter for default virtual paths. */
   imageCounter: number;
-  /** Live list counters per numId, for resolving `%N` marker templates. */
-  listCounters: Map<number, number[]>;
-  /** `numId:level` pairs already seen, so a start override applies once. */
-  listSeenLevels: Set<string>;
+  /**
+   * Advances past one paragraph, in document order, and answers the list
+   * label it shows: the page's own counter, so the numbers follow the
+   * document as it stands rather than the markers resolved when it was read.
+   */
+  nextListLabel: ListLabelCounter;
   /** The document's styles indexed by the built-in they are; classifies headings and quotes. */
   builtInStyles: BuiltInStyleIndex;
+  /**
+   * The rendered width (marker text + one trailing space) of the most
+   * recently emitted list item at each level, indexed by `ListRendering.level`.
+   * A nested item's indent is the sum of every shallower level's width here,
+   * not a fixed two spaces: CommonMark only keeps a child nested under its
+   * parent when the child starts at or past the column where the parent's
+   * content begins, and a marker like `10. ` or `1. ` is wider than `- `.
+   * Document order visits a parent before its children, so by the time a
+   * level-N item renders, levels `0..N-1` already hold the current ancestor
+   * chain's widths.
+   */
+  listIndentWidths: number[];
 };
 //#endregion
 export { ImageMeta, ImageRef, MarkdownOptions, MarkdownResult, RenderContext, ResolvedOptions };

package/dist/paged-layout/incrementalMeasure.d.ts

@@ -17,8 +17,7 @@ type IncrementalMeasureResult = {
   measures: Measure[];
   measuredBlockIndexes: number[];
 };
-declare function mergeDirtyRanges(first: DirtyRange | null, second: DirtyRange | null): DirtyRange | null;
 declare function findDirtyBlockIndexes(blocks: FlowBlock[], dirtyRange: DirtyRange): number[];
 declare function tryBuildIncrementalMeasures({ previousBlocks, previousMeasures, previousBlockWidths, nextBlocks, nextBlockWidths, dirtyRange, measureBlock }: IncrementalMeasureInput): IncrementalMeasureResult | null;
 //#endregion
-export { DirtyRange, IncrementalMeasureInput, IncrementalMeasureResult, findDirtyBlockIndexes, mergeDirtyRanges, tryBuildIncrementalMeasures };
+export { DirtyRange, IncrementalMeasureInput, IncrementalMeasureResult, findDirtyBlockIndexes, tryBuildIncrementalMeasures };

package/dist/paged-layout/incrementalMeasure.js

@@ -1,12 +1,4 @@
 //#region src/paged-layout/incrementalMeasure.ts
-function mergeDirtyRanges(first, second) {
-	if (!first) return second;
-	if (!second) return first;
-	return {
-		from: Math.min(first.from, second.from),
-		to: Math.max(first.to, second.to)
-	};
-}
 function findDirtyBlockIndexes(blocks, dirtyRange) {
 	const indexes = [];
 	const dirtyFrom = Math.min(dirtyRange.from, dirtyRange.to);
@@ -53,4 +45,4 @@ function isIncrementalMeasureEligibleBlock(block) {
 	});
 }
 //#endregion
-export { findDirtyBlockIndexes, mergeDirtyRanges, tryBuildIncrementalMeasures };
+export { findDirtyBlockIndexes, tryBuildIncrementalMeasures };

package/dist/paged-layout/transactionDirtyRange.d.ts

@@ -2,7 +2,5 @@ import { DirtyRange } from "./incrementalMeasure.js";
 import { Transaction } from "prosemirror-state";
 //#region src/paged-layout/transactionDirtyRange.d.ts
 declare function getTransactionDirtyRange(transaction: Transaction): DirtyRange | null;
-/** Collect every transaction in an applied batch in the final document's coordinates. */
-declare function getTransactionsDirtyRange(transactions: readonly Transaction[]): DirtyRange | null;
 //#endregion
-export { getTransactionDirtyRange, getTransactionsDirtyRange };
+export { getTransactionDirtyRange };