reamkit 1.23.0 → 1.25.0

package/dist/esm/markdown/markdown-writer.js

@@ -0,0 +1,733 @@
+import { FEATURES } from "../core/ir/features.js";
+import { headingLevelOf } from "../core/outline.js";
+import { detectImageFormat } from "../core/images.js";
+import { effectiveAbstract } from "../core/numbering/state.js";
+import { EMPTY_STYLE_SHEET, resolveParagraphProperties, resolveRunProperties } from "../core/style-cascade/resolver.js";
+import "../core/style-cascade/index.js";
+import { sanitizeHref } from "../core/links.js";
+import { toBase64 } from "../core/bytes.js";
+//#region src/markdown/markdown-writer.ts
+/**
+* Render a {@link FlowDoc} to GitHub-Flavored Markdown (ir-design §7).
+*
+* A flow medium: no pagination, no layout engine and no fonts, so this is a
+* pure, zero-I/O transform. Markdown says far less than the document model
+* does — alignment, indents, colour, font metrics, tab stops and page
+* geometry have no expression at all — so those are dropped and reported as
+* {@link Loss} entries, deduplicated so one recurring omission reports once.
+*
+* @param flow    The format-neutral interlayer document tree.
+* @param options Picture handling; see {@link MarkdownWriteOptions}.
+* @returns The encoded Markdown bytes plus the recorded {@link Loss} list.
+*/
+function writeMarkdown(flow, options = {}) {
+	const ctx = {
+		losses: [],
+		seen: /* @__PURE__ */ new Set(),
+		images: options.images ?? "dataUri",
+		pageBreaks: options.pageBreaks ?? "drop",
+		list: [],
+		inCell: false,
+		resources: flow.resources,
+		anchors: referencedAnchors(flow.body),
+		notes: noteNumbers(flow),
+		mediaNames: /* @__PURE__ */ new Map(),
+		...flow.numbering ? { numbering: flow.numbering } : {}
+	};
+	if (flow.headersFooters && flow.headersFooters.size > 0) lose(ctx, "dropped", FEATURES.headersFooters, "markdown has no pages to band headers onto");
+	const blocks = [];
+	for (const el of flow.body) emitBlock(blocks, el, ctx);
+	emitNoteDefinitions(blocks, flow, ctx);
+	return {
+		bytes: new TextEncoder().encode(joinBlocks(blocks)),
+		losses: ctx.losses
+	};
+}
+/**
+* The flow-medium {@link DocumentWriter} adapter (id `'md'`), wrapping
+* {@link writeMarkdown}, with the set of {@link FEATURES} it renders.
+*/
+var markdownWriter = {
+	id: "md",
+	consumes: "flow",
+	supports: new Set([
+		FEATURES.text,
+		FEATURES.lists,
+		FEATURES.tables,
+		FEATURES.images,
+		FEATURES.hyperlinks
+	]),
+	write: (doc, opts) => writeMarkdown(doc, opts ?? {})
+};
+/** Record a loss unless an identical one was recorded already. */
+function lose(ctx, severity, feature, detail) {
+	const key = `${severity}|${feature}|${detail}`;
+	if (ctx.seen.has(key)) return;
+	ctx.seen.add(key);
+	ctx.losses.push({
+		severity,
+		feature,
+		detail
+	});
+}
+/**
+* Join the emitted blocks: one blank line between them (markdown's block
+* separator), no leading blank, exactly one trailing newline.
+*
+* Trailing spaces are stripped from every line: they are invisible, editors
+* and formatters eat them, and two of them are markdown's own hard break —
+* a meaning no document ever asked for. Ream writes a hard break as the
+* backslash GFM also accepts, which survives all three.
+*/
+function joinBlocks(blocks) {
+	const body = blocks.map(trimHardBreaks).filter((b) => b.length > 0).join("\n\n");
+	return body.length > 0 ? `${body.replace(/[ \t]+$/gm, "")}\n` : "";
+}
+/**
+* Drop a hard break sitting at either end of a block: at the end there is no
+* next line to break to, at the start no previous one, and either way the
+* backslash is left standing in the text as itself. Only a break is taken —
+* an escaped literal backslash is `\\` with no newline behind it.
+*/
+function trimHardBreaks(block) {
+	return block.replace(/^(?:\\\n)+/, "").replace(/\\\n$/, "");
+}
+function emitBlock(out, el, ctx) {
+	if (el.kind === "paragraph") {
+		emitParagraph(out, el.paragraph, ctx);
+		return;
+	}
+	ctx.list.length = 0;
+	if (el.kind === "table") emitTable(out, el.table, ctx);
+	else if (el.kind === "image") {
+		const img = pictureMarkdown(el.image.resource, el.image.altText, ctx);
+		if (img.length > 0) out.push(img);
+	} else if (el.kind === "chart") lose(ctx, "dropped", FEATURES.charts, "markdown cannot draw a chart");
+	else emitShape(out, el.shape, ctx);
+}
+/**
+* A shape contributes its WORDS. Markdown draws no geometry, no fill and no
+* line, but the text inside a callout or a text box is document content and is
+* emitted as ordinary blocks — including a group's members, however deep.
+*/
+function emitShape(out, shape, ctx) {
+	lose(ctx, "dropped", FEATURES.shapes, "shape geometry dropped; the text inside it is kept");
+	for (const el of shape.text?.content ?? []) emitBlock(out, el, ctx);
+	for (const child of shape.children ?? []) emitShape(out, child.shape, ctx);
+}
+function emitParagraph(out, p, ctx) {
+	const resolved = resolveParagraphProperties(p.properties, EMPTY_STYLE_SHEET);
+	const anchors = bookmarkAnchors(p, ctx);
+	const text = inlineRuns(p.runs, p, ctx).replace(/^[ \t]+/, "");
+	const inline = anchors + text;
+	const marker = markerText(p, ctx);
+	reportParagraphLosses(resolved, ctx);
+	if (breaksPage(p, resolved)) emitRule(out, ctx);
+	const empty = isBlank(text) && anchors.length === 0;
+	const level = headingLevelOf(resolved);
+	if (level !== void 0) {
+		if (empty) return;
+		ctx.list.length = 0;
+		const oneLine = (marker !== void 0 ? `${marker} ${inline}` : inline).replaceAll("\\\n", " ").replaceAll("\n", " ");
+		if (ctx.inCell) {
+			lose(ctx, "degraded", FEATURES.tables, "heading inside a cell flattened to plain text");
+			out.push(oneLine);
+			return;
+		}
+		out.push(`${"#".repeat(level)} ${oneLine}`);
+		return;
+	}
+	if (marker !== void 0) {
+		if (!empty) emitListItem(out, resolved, marker, inline, ctx);
+		return;
+	}
+	if (empty) return;
+	ctx.list.length = 0;
+	out.push(ctx.inCell ? inline : guardBlockStart(inline));
+}
+/**
+* True when a paragraph's rendered text says nothing at all. Whitespace counts
+* as nothing, and so do the ZERO-WIDTH characters — the `.pptx` reader marks a
+* slide boundary with a U+200B paragraph carrying the page break, and a run of
+* them down the left of a deck is a column of empty lines, not content.
+*/
+function isBlank(text) {
+	return /^[\s\u200B-\u200D\uFEFF]*$/u.test(text);
+}
+/** Whether a page starts at this paragraph — its own break, or one in a run. */
+function breaksPage(p, resolved) {
+	return resolved.pageBreakBefore || p.runs.some((r) => r.pageBreak === true);
+}
+/**
+* A `---` thematic break where a page ends, when the caller asked for one.
+*
+* Never leading and never doubled: a rule before the first block would open
+* the document with a line, and two in a row say nothing the one does not.
+* Never inside a cell or a note either — those hold inline content, where the
+* three hyphens are just three hyphens.
+*/
+function emitRule(out, ctx) {
+	if (ctx.pageBreaks !== "rule" || ctx.inCell) return;
+	if (out.length === 0 || out[out.length - 1] === RULE) return;
+	out.push(RULE);
+}
+var RULE = "---";
+/**
+* The marker `applyNumbering` materialized as the paragraph's leading runs
+* (`"1."`, `"•"`, or a picture bullet), stripped of the tab that follows it —
+* or `undefined` when the paragraph is not a list item. The text is taken raw:
+* it is re-rendered as markup, never emitted as content.
+*/
+function markerText(p, ctx) {
+	const runs = [];
+	for (const run of p.runs) {
+		if (run.listMarker !== true) break;
+		runs.push(run);
+	}
+	if (runs.length === 0) return void 0;
+	if (runs.some((r) => r.inlineImage !== void 0)) lose(ctx, "degraded", FEATURES.lists, "picture bullet rendered as a plain bullet");
+	return runs.map((r) => r.text).join("").replaceAll("	", " ").trim();
+}
+function emitListItem(out, resolved, marker, inline, ctx) {
+	const ref = resolved.numbering;
+	const numId = ref?.numId ?? "";
+	const ilvl = ref?.ilvl ?? 0;
+	const stack = ctx.list;
+	const wasOpen = stack.length > 0;
+	while (stack.length > 0 && stack[stack.length - 1].ilvl > ilvl) stack.pop();
+	let top = stack[stack.length - 1];
+	if (!top || top.ilvl < ilvl) {
+		const parent = top;
+		top = {
+			ilvl,
+			indent: parent ? parent.indent + parent.markerWidth : 0,
+			markerWidth: 2,
+			counter: 0
+		};
+		stack.push(top);
+	}
+	top.counter += 1;
+	const bullet = listBullet(marker, numId, ilvl, top.counter, ctx);
+	top.markerWidth = bullet.length + 1;
+	const pad = " ".repeat(top.indent);
+	const cont = " ".repeat(top.indent + top.markerWidth);
+	const line = `${pad}${bullet} ${inline.replaceAll("\\\n", `\\\n${cont}`)}`.replace(/\s+$/, "");
+	if (wasOpen && out.length > 0) out[out.length - 1] += `\n${line}`;
+	else out.push(line);
+}
+/**
+* The markdown marker for an item: `-` for a bullet, `N.` for an ordered list.
+* Ordered lists keep their real number — the one the source's own marker states,
+* so a list starting at 5 (§17.9.28 `w:startOverride`) still starts at 5 —
+* falling back to this level's running count when the marker states no digits.
+*/
+function listBullet(marker, numId, ilvl, counter, ctx) {
+	const level = numberingLevel(numId, ilvl, ctx.numbering);
+	if (!(level ? level.format !== "bullet" && level.format !== "none" : /\d/.test(marker))) return "-";
+	if (level && level.format !== "decimal" && level.format !== "decimalZero") lose(ctx, "degraded", FEATURES.lists, `${level.format} list markers render as decimal`);
+	const digits = /(\d+)\D*$/.exec(marker);
+	if (marker.replace(/\D+/g, "").length > (digits?.[1]?.length ?? 0)) lose(ctx, "degraded", FEATURES.lists, "multi-level list marker flattened to one number");
+	return `${digits ? Number(digits[1]) : counter}.`;
+}
+function numberingLevel(numId, ilvl, numbering) {
+	if (!numbering) return void 0;
+	const instance = numbering.numInstances.get(numId);
+	if (!instance) return void 0;
+	return effectiveAbstract(numbering, instance)?.levels.get(ilvl);
+}
+/** Everything a paragraph says that markdown has no way to say back. */
+function reportParagraphLosses(r, ctx) {
+	if (r.alignment !== "left") lose(ctx, "dropped", FEATURES.text, "paragraph alignment has no markdown expression");
+	if (r.indentLeft !== 0 || r.indentRight !== 0 || r.indentFirstLine !== 0) lose(ctx, "dropped", FEATURES.text, "paragraph indents have no markdown expression");
+	if (r.pageBreakBefore && ctx.pageBreaks === "drop") lose(ctx, "dropped", FEATURES.sections, "page breaks have no markdown expression");
+}
+/**
+* Backslash-escape a leading character that would otherwise open a block the
+* source never asked for — a heading, a quote, a list item, a setext rule.
+*/
+function guardBlockStart(text) {
+	return text.replace(/^(\s*)([#>+-]|\d+[.)]|={2,}$)/, "$1\\$2");
+}
+/**
+* Number the notes by the order their references appear in reading order
+* (§17.11: footnotes and endnotes each keep their own counter), and the review
+* comments alongside them.
+*
+* Only ids the package actually holds content for are numbered: an unmatched
+* `[^fn1]` is not a footnote reference at all in GFM — it renders as those
+* six literal characters — so a dangling reference must leave no mark.
+*/
+function noteNumbers(flow) {
+	const footnotes = /* @__PURE__ */ new Map();
+	const endnotes = /* @__PURE__ */ new Map();
+	const comments = /* @__PURE__ */ new Map();
+	const visitShape = (shape) => {
+		if (shape.text) visit(shape.text.content);
+		for (const child of shape.children ?? []) visitShape(child.shape);
+	};
+	const visit = (els) => {
+		for (const el of els) if (el.kind === "paragraph") for (const r of el.paragraph.runs) {
+			const add = (id, into, content) => {
+				if (id === void 0 || into.has(id) || !content?.has(id)) return;
+				into.set(id, into.size + 1);
+			};
+			add(r.footnoteRef, footnotes, flow.footnotes);
+			add(r.endnoteRef, endnotes, flow.endnotes);
+			add(r.commentRef, comments, flow.comments);
+		}
+		else if (el.kind === "table") for (const row of el.table.rows) for (const cell of row.cells) visit(cell.content);
+		else if (el.kind === "shape") visitShape(el.shape);
+	};
+	visit(flow.body);
+	return {
+		footnotes,
+		endnotes,
+		comments
+	};
+}
+/**
+* The GFM footnote definitions every reference above points at, in reference
+* order: the notes first, then the review comments — which markdown has no
+* concept of, and which are carried as footnotes attributed to their author.
+*/
+function emitNoteDefinitions(out, flow, ctx) {
+	define(out, ctx.notes.footnotes, flow.footnotes, "fn", ctx);
+	define(out, ctx.notes.endnotes, flow.endnotes, "en", ctx);
+	for (const [id, n] of sorted(ctx.notes.comments)) {
+		const comment = flow.comments?.get(id);
+		if (!comment) continue;
+		const who = comment.author !== void 0 ? `**${escapeInline(comment.author)}:** ` : "";
+		out.push(`[^cm${String(n)}]: ${who}${flatten(comment.content, ctx)}`);
+	}
+}
+function define(out, numbers, content, prefix, ctx) {
+	for (const [id, n] of sorted(numbers)) {
+		const blocks = content?.get(id);
+		if (!blocks) continue;
+		out.push(`[^${prefix}${String(n)}]: ${flatten(blocks, ctx)}`);
+	}
+}
+var sorted = (m) => [...m.entries()].sort((a, b) => a[1] - b[1]);
+/**
+* Blocks flattened to the single line a footnote definition occupies. Note
+* content is short by nature; a note that holds several paragraphs keeps them
+* all, joined by the line break the syntax allows.
+*/
+function flatten(blocks, ctx) {
+	const wasInCell = ctx.inCell;
+	const outer = ctx.list.splice(0);
+	ctx.inCell = true;
+	const rendered = [];
+	for (const el of blocks) emitBlock(rendered, el, ctx);
+	ctx.inCell = wasInCell;
+	ctx.list.length = 0;
+	ctx.list.push(...outer);
+	return rendered.map(trimHardBreaks).filter((b) => b.length > 0).join("<br>").replaceAll("\\\n", "<br>").replaceAll("\n", "<br>");
+}
+/**
+* Wrap already-rendered inline content in the link it carries. An external
+* target passes the scheme allowlist first (`core/links`) — untrusted input
+* never becomes a clickable link on a scheme markdown viewers will follow.
+*/
+function linkify(inner, target, ctx) {
+	if (inner.length === 0) return inner;
+	if (target.href !== void 0) {
+		const safe = sanitizeHref(target.href);
+		if (safe === void 0) {
+			lose(ctx, "degraded", FEATURES.hyperlinks, "hyperlink target with a disallowed scheme rendered as plain text");
+			return inner;
+		}
+		return `[${inner}](${destination(safe)})`;
+	}
+	if (target.anchor !== void 0) return `[${inner}](#${bookmarkSlug(target.anchor)})`;
+	return inner;
+}
+/**
+* A link destination: bare when it is plain enough, and in the pointy-bracket
+* form CommonMark §6.3 provides when it holds whitespace or unbalanced
+* parentheses that would otherwise end it early.
+*/
+function destination(url) {
+	if (!/[\s()<>]/.test(url)) return url;
+	return `<${url.replaceAll("<", "%3C").replaceAll(">", "%3E")}>`;
+}
+/**
+* The fragment an internal link points at. Markdown has no bookmark of its
+* own, so the name is slugified and planted as an inline `<a id>` on the
+* paragraph it belongs to — the same shape GFM's own heading anchors take.
+*/
+function bookmarkSlug(name) {
+	const slug = name.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "");
+	return slug.length > 0 ? slug : "bookmark";
+}
+/** The bookmark names some run actually links to — the only ones worth an anchor. */
+function referencedAnchors(body) {
+	const out = /* @__PURE__ */ new Set();
+	const visitShape = (shape) => {
+		if (shape.text) visit(shape.text.content);
+		for (const child of shape.children ?? []) visitShape(child.shape);
+	};
+	const visit = (els) => {
+		for (const el of els) if (el.kind === "paragraph") {
+			for (const r of el.paragraph.runs) if (r.anchor !== void 0) out.add(r.anchor);
+		} else if (el.kind === "table") for (const row of el.table.rows) for (const cell of row.cells) visit(cell.content);
+		else if (el.kind === "shape") visitShape(el.shape);
+	};
+	visit(body);
+	return out;
+}
+/** The `<a id>` markers a paragraph opens, for the bookmarks something links to. */
+function bookmarkAnchors(p, ctx) {
+	return (p.bookmarks ?? []).filter((b) => ctx.anchors.has(b)).map((b) => `<a id="${bookmarkSlug(b)}"></a>`).join("");
+}
+var MIME_BY_FORMAT = {
+	jpeg: "image/jpeg",
+	png: "image/png",
+	jpeg2000: "image/jp2",
+	gif: "image/gif",
+	tiff: "image/tiff",
+	bmp: "image/bmp"
+};
+var EXTENSION_BY_FORMAT = {
+	jpeg: "jpg",
+	png: "png",
+	jpeg2000: "jp2",
+	gif: "gif",
+	tiff: "tif",
+	bmp: "bmp"
+};
+/**
+* A picture as `![alt](…)`, or `''` when there is nothing to point at. The
+* destination follows {@link MarkdownWriteOptions.images}: inlined as a
+* `data:` URI by default, named under `./media/` when the caller means to
+* write the bytes out itself, or dropped.
+*/
+function pictureMarkdown(resource, altText, ctx) {
+	if (ctx.images === "drop") {
+		lose(ctx, "dropped", FEATURES.images, "pictures omitted at the caller’s request");
+		return "";
+	}
+	if (resource === void 0) return "";
+	const bytes = ctx.resources.get(resource);
+	if (!bytes) return "";
+	const format = detectImageFormat(bytes);
+	if (!format) {
+		lose(ctx, "dropped", FEATURES.images, "picture in a format markdown viewers cannot show");
+		return "";
+	}
+	const alt = escapeInline(altText ?? "").replaceAll("\n", " ");
+	if (ctx.images === "link") {
+		let name = ctx.mediaNames.get(resource);
+		if (name === void 0) {
+			name = `./media/image${String(ctx.mediaNames.size + 1)}.${EXTENSION_BY_FORMAT[format]}`;
+			ctx.mediaNames.set(resource, name);
+		}
+		lose(ctx, "degraded", FEATURES.images, "pictures referenced under ./media — a single-file writer does not write their bytes");
+		return `![${alt}](${name})`;
+	}
+	return `![${alt}](data:${MIME_BY_FORMAT[format]};base64,${toBase64(bytes)})`;
+}
+/**
+* A GFM pipe table (§4.10). Markdown's table is a plain grid: it has no
+* merged cells and no headerless form, so a `w:gridSpan` fills its first
+* column and pads the rest empty, a `w:vMerge` continuation stays empty, and
+* the first row is promoted to the header the syntax requires. Each of those
+* is reported once.
+*/
+function emitTable(out, table, ctx) {
+	const width = columnCount(table);
+	if (width === 0 || table.rows.length === 0) return;
+	const grid = table.rows.map((row) => rowCells(row, width, ctx));
+	const keep = usedRange(grid);
+	if (!keep) return;
+	const rows = grid.slice(keep.top, keep.bottom + 1).map((row) => row.slice(keep.left, keep.right + 1));
+	const header = rows[0];
+	if (table.rows[keep.top].properties.isHeader !== true) lose(ctx, "degraded", FEATURES.tables, "first row promoted to the header GFM tables require");
+	const line = (cells) => `| ${cells.join(" | ")} |`;
+	const bars = delimiters(table, width).slice(keep.left, keep.right + 1);
+	const lines = [line(header), line(bars)];
+	for (const row of rows.slice(1)) lines.push(line(row));
+	out.push(lines.join("\n"));
+}
+/**
+* The rows and columns worth drawing: the blank ones at the EDGES go.
+*
+* A print region carries its whole used range, blank leading rows and trailing
+* columns and all, because a page draws their borders and their fill. Markdown
+* draws neither, so an edge of empty cells is a column of nothing — and a blank
+* first row is worse than nothing, since §4.10 makes it the header. The blank
+* rows INSIDE stay: those separate one group of data from the next, which is
+* the one thing an empty row can still say here.
+*/
+function usedRange(grid) {
+	const filled = (r, c) => (grid[r]?.[c] ?? "").trim().length > 0;
+	const width = grid[0]?.length ?? 0;
+	let top = 0;
+	let bottom = grid.length - 1;
+	let left = 0;
+	let right = width - 1;
+	const rowFilled = (r) => grid[r].some((_, c) => filled(r, c));
+	const colFilled = (c) => grid.some((_, r) => filled(r, c));
+	while (top <= bottom && !rowFilled(top)) top++;
+	if (top > bottom) return void 0;
+	while (bottom > top && !rowFilled(bottom)) bottom--;
+	while (left <= right && !colFilled(left)) left++;
+	while (right > left && !colFilled(right)) right--;
+	return {
+		top,
+		bottom,
+		left,
+		right
+	};
+}
+/** The widest row wins: a `w:gridSpan` may reach past the declared `w:tblGrid`. */
+function columnCount(table) {
+	let widest = table.grid.length;
+	for (const row of table.rows) {
+		let n = 0;
+		for (const cell of row.cells) n += cell.properties.colSpan ?? 1;
+		widest = Math.max(widest, n);
+	}
+	return widest;
+}
+/** One row's cells, spans expanded to empty columns and padded to `cols`. */
+function rowCells(row, cols, ctx) {
+	const cells = [];
+	for (const cell of row.cells) {
+		const span = cell.properties.colSpan ?? 1;
+		if (span > 1 || cell.properties.merge !== void 0 && cell.properties.merge !== "start") lose(ctx, "degraded", FEATURES.tables, "merged cells flattened — markdown has no spans");
+		cells.push(cell.properties.merge === "middle" || cell.properties.merge === "end" ? "" : cellInline(cell, ctx));
+		for (let k = 1; k < span; k++) cells.push("");
+	}
+	while (cells.length < cols) cells.push("");
+	return cells.slice(0, cols);
+}
+/**
+* The delimiter row, carrying each column's alignment when the header cell's
+* first paragraph states one — the only paragraph property a markdown table
+* can keep.
+*/
+function delimiters(table, cols) {
+	const out = [];
+	const first = table.rows[0];
+	let col = 0;
+	for (const cell of first.cells) {
+		const span = cell.properties.colSpan ?? 1;
+		const p = cell.content.find((el) => el.kind === "paragraph");
+		const align = p ? resolveParagraphProperties(p.paragraph.properties, EMPTY_STYLE_SHEET).alignment : "left";
+		const bar = align === "center" ? ":---:" : align === "right" ? "---:" : "---";
+		for (let k = 0; k < span && col < cols; k++, col++) out.push(bar);
+	}
+	while (out.length < cols) out.push("---");
+	return out.slice(0, cols);
+}
+/**
+* A cell's blocks flattened to one line: a table row is a single line, so
+* every break between and inside its blocks becomes a `<br>`. The cell's own
+* lists number independently of whatever list surrounds the table.
+*
+* Each block is trimmed at its ends. Word carries a cell's padding as spaces in
+* the text itself, and a pipe table already sets its own — kept, they only
+* widen the source line, since §4.10 strips a cell's outer whitespace before
+* rendering it anyway.
+*/
+function cellInline(cell, ctx) {
+	const outer = ctx.list.splice(0);
+	const wasInCell = ctx.inCell;
+	ctx.inCell = true;
+	const blocks = [];
+	for (const el of cell.content) {
+		if (el.kind === "table") {
+			lose(ctx, "degraded", FEATURES.tablesNested, "nested table flattened into its cell");
+			for (const row of el.table.rows) for (const inner of row.cells) blocks.push(cellInline(inner, ctx));
+			continue;
+		}
+		emitBlock(blocks, el, ctx);
+	}
+	ctx.inCell = wasInCell;
+	ctx.list.length = 0;
+	ctx.list.push(...outer);
+	return blocks.map((b) => trimHardBreaks(b).trim()).filter((b) => b.length > 0).join("<br>").replaceAll("\\\n", "<br>").replaceAll("\n", "<br>");
+}
+/**
+* The paragraph's runs as one inline string.
+*
+* Two passes, because whether a delimiter may open or close depends on the
+* characters on either side of it (§6.2), and those belong to the NEIGHBOURING
+* spans: the first pass coalesces runs into spans, the second dresses each
+* span knowing what stands beside it.
+*/
+function inlineRuns(runs, p, ctx) {
+	const pieces = [];
+	let pending;
+	const flush = () => {
+		if (pending && pending.text.length > 0) pieces.push(pending);
+		pending = void 0;
+	};
+	for (const run of runs) {
+		const literal = literalRun(run, ctx);
+		if (literal !== void 0) {
+			flush();
+			if (literal.length > 0) pieces.push({ literal });
+			continue;
+		}
+		if (run.text.length === 0) continue;
+		const resolved = resolveRunProperties(run.properties, p.properties, EMPTY_STYLE_SHEET);
+		reportRunLosses(resolved, ctx);
+		const marks = marksOf(resolved, run);
+		if (pending && sameMarks(pending.marks, marks)) pending.text += run.text;
+		else {
+			flush();
+			pending = {
+				marks,
+				text: run.text
+			};
+		}
+	}
+	flush();
+	let out = "";
+	for (let i = 0; i < pieces.length; i++) {
+		const piece = pieces[i];
+		if ("literal" in piece) {
+			out += piece.literal;
+			continue;
+		}
+		out += applyMarks(piece.text, piece.marks, ctx, out.slice(-1), leadOf(pieces, i + 1));
+	}
+	return out;
+}
+/**
+* The first character the next span will contribute. A dressed span always
+* begins with its delimiter or its html tag — both punctuation — so a marked
+* neighbour answers without being rendered first.
+*/
+function leadOf(pieces, from) {
+	const next = pieces[from];
+	if (!next) return "";
+	if ("literal" in next) return next.literal.slice(0, 1);
+	if (wrapped(next.marks)) return "*";
+	return escapeInline(next.text).slice(0, 1);
+}
+/** Whether a span carries anything that puts a delimiter or a tag in front of it. */
+function wrapped(m) {
+	return m.bold || m.italic || m.strike || m.underline || m.vertical !== "baseline" || m.href !== void 0 || m.anchor !== void 0;
+}
+/**
+* The runs that are not a span of styled text: reference markers, inline
+* objects, and the list marker the reader materialized. Returns the literal
+* they contribute (possibly `''`), or `undefined` when the run IS styled text.
+*/
+function literalRun(run, ctx) {
+	if (run.footnoteRef !== void 0 || run.endnoteRef !== void 0) {
+		const foot = run.footnoteRef !== void 0;
+		const id = foot ? run.footnoteRef : run.endnoteRef;
+		const n = (foot ? ctx.notes.footnotes : ctx.notes.endnotes).get(id);
+		return n === void 0 ? "" : `[^${foot ? "fn" : "en"}${String(n)}]`;
+	}
+	if (run.commentRef !== void 0) {
+		const n = ctx.notes.comments.get(run.commentRef);
+		if (n === void 0) return "";
+		lose(ctx, "degraded", FEATURES.trackedChanges, "review comments rendered as footnotes");
+		return `[^cm${String(n)}]`;
+	}
+	if (run.noteNumber) return "";
+	if (run.listMarker) return "";
+	if (run.math !== void 0) {
+		lose(ctx, "dropped", FEATURES.math, "markdown has no math notation (GFM)");
+		return "";
+	}
+	if (run.inlineImage !== void 0) return linkify(pictureMarkdown(run.inlineImage.resource, void 0, ctx), run, ctx);
+	if (run.columnBreak === true || run.pageBreak === true && ctx.pageBreaks === "drop") lose(ctx, "dropped", FEATURES.sections, "page breaks have no markdown expression");
+}
+/** Everything a run says that markdown has no way to say back. */
+function reportRunLosses(r, ctx) {
+	if (r.colorHex !== "000000") lose(ctx, "dropped", FEATURES.text, "run colour has no markdown expression");
+	if (r.caps || r.smallCaps) lose(ctx, "dropped", FEATURES.text, "w:caps / w:smallCaps has no markdown expression");
+}
+function marksOf(r, run) {
+	return {
+		bold: r.bold,
+		italic: r.italic,
+		strike: r.strike,
+		underline: r.underline !== "none",
+		vertical: r.verticalAlign === "superscript" || r.verticalAlign === "subscript" ? r.verticalAlign : "baseline",
+		...run.href !== void 0 ? { href: run.href } : {},
+		...run.anchor !== void 0 ? { anchor: run.anchor } : {}
+	};
+}
+function sameMarks(a, b) {
+	return a.bold === b.bold && a.italic === b.italic && a.strike === b.strike && a.underline === b.underline && a.vertical === b.vertical && a.href === b.href && a.anchor === b.anchor;
+}
+/**
+* Escape the text, then dress it: markdown delimiters innermost, then the
+* inline-html wrappers for what markdown cannot say. CommonMark §6.2 requires
+* a delimiter to hug non-whitespace, so any leading or trailing space of the
+* span moves outside the marks.
+*
+* A HARD BREAK at either end moves out too, and it matters more than a space
+* does: a closing `**` that a line break stands in front of is not
+* right-flanking, cannot close, and prints as two asterisks. A `w:br` at the
+* end of a bold title — which every deck writes — did exactly that.
+*/
+var SPAN_EDGE = String.raw`(?:\\\n|\s)`;
+function applyMarks(text, marks, ctx, before, after) {
+	const escaped = escapeInline(text);
+	const lead = new RegExp(`^${SPAN_EDGE}*`).exec(escaped)?.[0] ?? "";
+	const trail = new RegExp(`${SPAN_EDGE}*$`).exec(escaped)?.[0] ?? "";
+	const core = escaped.slice(lead.length, escaped.length - trail.length);
+	if (core.length === 0) return escaped;
+	const outerBefore = lead.length > 0 ? lead[lead.length - 1] : before;
+	const outerAfter = trail.length > 0 ? trail[0] : after;
+	let out = core;
+	const levels = [
+		[
+			marks.italic,
+			"*",
+			"em"
+		],
+		[
+			marks.bold,
+			"**",
+			"strong"
+		],
+		[
+			marks.strike,
+			"~~",
+			"del"
+		]
+	];
+	for (const [on, delimiter, tag] of levels) {
+		if (!on) continue;
+		out = canOpen(outerBefore, out[0]) && canClose(out[out.length - 1], outerAfter) ? `${delimiter}${out}${delimiter}` : `<${tag}>${out}</${tag}>`;
+	}
+	if (marks.underline) out = `<u>${out}</u>`;
+	if (marks.vertical !== "baseline") {
+		const tag = marks.vertical === "superscript" ? "sup" : "sub";
+		out = `<${tag}>${out}</${tag}>`;
+	}
+	return `${lead}${linkify(out, marks, ctx)}${trail}`;
+}
+var isSpace = (c) => c === "" || /\s/u.test(c);
+var isPunct = (c) => /[\p{P}\p{S}]/u.test(c);
+/** §6.2 — the delimiter run is left-flanking, so it can open emphasis. */
+function canOpen(before, after) {
+	return !isSpace(after) && (!isPunct(after) || isSpace(before) || isPunct(before));
+}
+/** §6.2 — the delimiter run is right-flanking, so it can close emphasis. */
+function canClose(before, after) {
+	return !isSpace(before) && (!isPunct(before) || isSpace(after) || isPunct(after));
+}
+/**
+* Escape the inline text so nothing in it is read as markup, and map the two
+* control characters the model uses: `\t` (a `w:tab`, which has no medium
+* here) to a space, and `\n` (a `w:br` soft break) to GFM's backslash hard
+* break.
+*
+* `_` is escaped only at a word boundary — GFM does not open intraword
+* emphasis with it, so escaping every one would turn `snake_case` into noise.
+*/
+function escapeInline(text) {
+	return text.replace(/[\\`*[\]<>|~]/g, (c) => `\\${c}`).replace(/(^|[\s\p{P}])_|_(?=[\s\p{P}]|$)/gu, (m) => m.replace("_", "\\_")).replaceAll("	", " ").replaceAll("\n", "\\\n");
+}
+//#endregion
+export { markdownWriter, writeMarkdown };