rapier-markdown-kit 1.2.8 → 1.2.9

package/dist/kit/render-ink.mjs

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: MIT
-// Published typography is measured once; an annotation keeps its words and paths in one inert, scalable group.
 import {check, pause} from './render-work.mjs';
 import {apply as applyTypography} from '../layout/typography.mjs';
 import {documentLanguage} from '../spec/document-settings.mjs';
@@ -75,7 +74,6 @@ export async function freezePublishedInk(root, {document: doc, css, fontCss = ''
       group.style.cssText = 'display:flow-root;position:relative;width:100%;margin:0;padding:0;border:0;overflow:visible';
       main.insertBefore(group, captured.nodes[first]);
       for (let index = first; index <= last; index++) group.appendChild(captured.nodes[index]);
-      // A fixed group cannot grow after disclosure. Show each marked passage in full.
       for (const span of group.querySelectorAll(MARK)) {
         for (let parent = span.parentElement; parent && parent !== group; parent = parent.parentElement)
           if (parent.localName === 'details') parent.open = true;
@@ -88,7 +86,6 @@ export async function freezePublishedInk(root, {document: doc, css, fontCss = ''
       try { await image.decode(); }
       catch (_) { throw failure('an embedded picture could not be decoded.'); }
     })));
-    // The captured CSS supplies the faces; validate them before measuring typography or ink.
     main.getBoundingClientRect();
     await wait(waitForFonts(main, {settings, css, fontCss, install: false}));
     if (paper.fonts?.ready) await wait(paper.fonts.ready);
@@ -114,8 +111,6 @@ export async function freezePublishedInk(root, {document: doc, css, fontCss = ''
       results.push(svg);
       await pause(work);
     }
-    // Keep the measured typography outside annotated groups too. The caller's detached
-    // projection changes only after every resource and group has succeeded.
     for (const [index, group] of prepared.entries()) group.replaceWith(results[index]);
     const projected = doc.createDocumentFragment();
     for (const node of main.childNodes) {

package/dist/kit/render-markdown.mjs

@@ -6,17 +6,15 @@ const RAPIER_PORTABLE_HIGHLIGHT_HEX = Object.freeze({
 	green: '#35c57a', red: '#f05a62', blue: '#4f91f7', yellow: '#e6b91e', purple: '#9b6dea',
 });
 const _RAPIER_RTL_SCRIPT = /[\p{Script=Hebrew}\p{Script=Arabic}\p{Script=Syriac}\p{Script=Thaana}\p{Script=Nko}\p{Script=Samaritan}\p{Script=Mandaic}\p{Script=Adlam}\p{Script=Phoenician}\p{Script=Imperial_Aramaic}\p{Script=Palmyrene}\p{Script=Nabataean}\p{Script=Hatran}\p{Script=Old_South_Arabian}\p{Script=Old_North_Arabian}\p{Script=Mende_Kikakui}\p{Script=Old_Hungarian}\p{Script=Old_Sogdian}\p{Script=Sogdian}\p{Script=Elymaic}\p{Script=Chorasmian}\p{Script=Yezidi}\p{Script=Old_Uyghur}\p{Script=Hanifi_Rohingya}]/u;
-// The document's renderer. DOM, codecs and host state are explicit inputs.
 function createMarkdownRenderer(runtime) {
   const {Node, _rapierPrefixPortableAnchors, RAPIER_HIGHLIGHT_COLOR_BY_MARKER, RAPIER_MARKDOWN_SPEC, RAPIER_RENDERED_HEADING_SELECTOR, _rapierApplyMarkdownSpec, _rapierChromeOwnsId, _rapierCodeHtml, _rapierDeriveDarkColor, _rapierDormantHeadings, _rapierEmbedAssetSource, _rapierHeadingSlugBase, _rapierNextHeadingSlug, _rapierHighlightAdmitted, _rapierInstallMarkdownMath, _rapierMarkdownPreview, _rapierPlainLayout, _rapierProviders, _rapierRemoteContent, _rapierRemoteImagePlaceholder, _rapierRemoteSubresourceOrigin, _rapierRenderedAnchorOriginalIds, _rapierSourceCharEscaped, _rapierSplitOpeningFrontmatter, _rapierUiDiagram, _rapierUiMath, document, escapeRapierHtmlText, globalThis, sanitizeRapierHtml, window} = runtime;
   let md = runtime.md;
 function initMarkdownIt() {
 	if (typeof window.markdownit !== 'function') throw new Error('markdownit');
-	if (typeof _rapierMarkdownPreview === 'function') globalThis.rapierRenderPreview = _rapierMarkdownPreview; // Notes' cards read through here; the Node witnesses that run this function alone have no such neighbour
+	if (typeof _rapierMarkdownPreview === 'function') globalThis.rapierRenderPreview = _rapierMarkdownPreview;
 
 	md = window.markdownit({
 		...RAPIER_MARKDOWN_SPEC.options,
-		// The first paint is coloured: the CPU reading, synchronously, for every admitted fence.
 		highlight: (code, lang) => lang && _rapierHighlightAdmitted(code) ? _rapierCodeHtml(code, lang) : '',
 	});
 
@@ -50,8 +48,6 @@ function initMarkdownIt() {
 		return markOpenDefault(tokens, idx, opts, env, self);
 	};
 
-	// Every authored spelling lowers to the same admitted style facts. Original delimiters are
-	// transient edit-projection data; only the source owner can write them back.
 	const renderTypography = (tokens, index) => {
 		const typed = globalThis.RapierMarkdownSpec.typography, held = tokens[index].meta?.typography;
 		if (!held) return '<span>';
@@ -74,13 +70,8 @@ function initMarkdownIt() {
 	};
 	md.renderer.rules.rapier_typography_open = renderTypography;
 	md.renderer.rules.rapier_typography_close = () => '</span>';
-	// Ink: the span carries its opener's body (the grammar's inkOpenBody: a sanitizer drops an attribute holding the
-	// comment's close); the ink layer reads it back through the one grammar and draws the stroke over the words' own boxes.
-	// The span itself shows nothing.
 	md.renderer.rules.rapier_ink_open = (tokens, idx) => {
 		const body = String(tokens[idx].attrGet('data-rapier-ink') || '');
-		// The dark-page colour on the span, as the colour span's: an exported page draws its ink with no engine to ask (the
-		// rules run on this thread alone; the Worker plants the parser, not the renderer).
 		const spec = globalThis.RapierMarkdownSpec;
 		const mark = spec && typeof spec.parseInkBody === 'function' ? spec.parseInkBody(body) : null;
 		return '<span class="rapier-ink-mark" data-rapier-ink="' + md.utils.escapeHtml(body) + '"'
@@ -98,10 +89,6 @@ function initMarkdownIt() {
 	};
 	md.renderer.rules.softbreak = () =>
 		sourceToken('\n', '\u2060', 'rapier-source-token--softbreak');
-	// A backslash escape the edit surface's writer would not write itself (`https\://`, `www\.`, `a\@b`: an unlinked
-	// address, or a person's own escape) is carried through the edit projection as a source token, as a soft break and
-	// an emoji are; the parser joins escapes into plain text before rendering, so they are kept apart first. The
-	// characters the writer escapes on its own (\ * ` [ ] _) stay the writer's.
 	md.core.ruler.before('text_join', 'rapier_escape_token', state => {
 		for (const token of state.tokens) {
 			if (token.type !== 'inline' || !token.children) continue;
@@ -134,7 +121,6 @@ function initMarkdownIt() {
 		const alt = suffix && semanticAlt.endsWith(suffix) ? semanticAlt.slice(0, -suffix.length) : semanticAlt;
 		const layout = token.meta?.mdLayout?.imageOnly ? token.meta.mdLayout.marker : '';
 		const asset = globalThis.RapierImageAssets.dataImage(src), reference = token.meta?.mdImage?.reference;
-		// A connected host's own asset; a host without one (the server) supplies no port.
 		if (!env.rapierPage && typeof globalThis.RapierEmbeddedImages?.imageHtml === 'function' &&
 			(_rapierEmbedAssetSource?.(src) || asset && (reference || asset.codec === 'image/jxl' || asset.codec === 'image/gif' || asset.codec === 'image/svg+xml'))) return globalThis.RapierEmbeddedImages.imageHtml(
 			reference, alt, title, size, layout, rawAlt, token.meta?.mdImage?.source, src, env.rapierImagePresentation !== false);
@@ -172,8 +158,6 @@ function initMarkdownIt() {
 		if (title) attrs.push('title="' + md.utils.escapeHtml(title) + '"');
 		if (shownAlt !== alt || size && !token.meta?.mdLayout?.layout?.width) attrs.push('data-rapier-image-alt-source="' + md.utils.escapeHtml(rawAlt) + '"');
 		if (layout) attrs.push('data-rapier-image-layout="' + md.utils.escapeHtml(encodeURIComponent(layout)) + '"');
-		// Portable semantic consumers keep their existing native image attributes. Only
-		// live editor/reader presentation needs provisional geometry and its load consumer.
 		if (env.rapierImagePresentation === false) return '<img ' + attrs.join(' ') + _rapierImageSizeAttributes(size, layout) + '>';
 		const geometry = !env.rapierPage && globalThis.RapierEmbeddedImages?.geometry
 			? globalThis.RapierEmbeddedImages.geometry(src) : globalThis.RapierImageAssets.imagePlaceholderDimensions(src);
@@ -189,17 +173,8 @@ function initMarkdownIt() {
 	md.renderer.rules.rapier_break = () =>
 		'<div class="rapier-page-break" data-md-break="page" contenteditable="false" role="separator" aria-label="Page break"></div>\n';
 
-	// Raw HTML carries no editor hooks. Keep its fragment boundaries until the complete Markdown
-	// markup reaches DOMPurify: sanitizing each HTML token closes containers before their body.
-	// The harness runs this installer alone for the parser's acceptance; without the page's sanitizer the tokens pass.
 	const inPage = typeof sanitizeRapierHtml === 'function' && typeof _rapierChromeOwnsId === 'function';
-	// HTML separates attributes and ends an unquoted value only at ASCII whitespace: JavaScript's \s also takes U+00A0,
-	// which would read a quoted value the browser never sees and keep the attributes hidden inside it.
 	const rawAttribute = /[\t\n\f\r ]+([A-Za-z_:][A-Za-z0-9_.:-]*)(?:[\t\n\f\r ]*=[\t\n\f\r ]*("[^"]*"|'[^']*'|[^"'=<>`\t\n\f\r ]+))?/g;
-	// The id is read as HTML reads it: a numeric character reference (`&#115;ource-textarea` is `source-textarea`,
-	// `&#x73;` the same) and the named references that spell a character an id can hold are decoded before the
-	// chrome's ids are asked; every other name stays literal (no named reference spells a letter, a digit or a
-	// hyphen). A string walk, not a parser: the render pass is the one HTML parser this markup meets.
 	const RAW_ID_NAMED = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", lowbar: '_', UnderBar: '_', num: '#', colon: ':',
 		period: '.', sol: '/', excl: '!', quest: '?', commat: '@', plus: '+', ast: '*', percnt: '%', dollar: '$', semi: ';',
 		equals: '=', comma: ',', lpar: '(', rpar: ')', lsqb: '[', lbrack: '[', rsqb: ']', rbrack: ']', lcub: '{', lbrace: '{',
@@ -224,7 +199,6 @@ function initMarkdownIt() {
 		md.renderer.rules.html_inline = (tokens, idx) => cleanTag(tokens[idx].content);
 		md.renderer.rules.html_block = (tokens, idx) => _rapierRawHtmlFragment(tokens[idx].content, cleanTag, md);
 	}
-	// A highlight written in one of the picker's colours is that swatch, as `==🟢x==` is, and follows the theme.
 	const inlineHtml = md.renderer.rules.html_inline || ((tokens, idx) => tokens[idx].content);
 	md.renderer.rules.html_inline = (tokens, idx, ...rest) => {
 		const swatch = /^<mark style="background-color:(#[0-9a-f]{6});?">$/i.exec(tokens[idx].content);
@@ -306,6 +280,8 @@ function initMarkdownIt() {
 			token.attrSet('data-rapier-fence', token.markup || '```');
 			token.attrSet('data-rapier-fence-info', token.info == null ? '' : String(token.info));
 			const lang = String(token.info || '').trim().split(/\s+/)[0].toLowerCase();
+			if (lang === 'math' && token.meta?.rapierFenceClosed !== false && token.meta?.mathSource !== undefined)
+				return md.renderer.rules.math_block(tokens, idx, opts, env, self);
 			if (lang === 'html') {const block = htmlPlaceholder(token, md.utils.escapeHtml); if (block) return block;}
 			if (lang !== 'mermaid') return _fenceDefault(tokens, idx, opts, env, self);
 			const src = String(token.content || '').replace(/\n$/, '');
@@ -316,7 +292,6 @@ function initMarkdownIt() {
 				'" data-rapier-fence-info="' + md.utils.escapeHtml(info) + '">' + escapedSrc + '</code></pre>';
 			const encoded = encodeURIComponent(src);
 			if (token.meta?.rapierFenceClosed === false) {
-				// No render request: even a valid diagram body must not conceal an unfinished fence.
 				return '<figure class="diagram-block diagram-block--error" data-diagram-state="error"' +
 					' data-diagram-unclosed="" data-diagram-src="' + encoded + '">' +
 					'<p class="diagram-reason">Mermaid block may be missing its closing <code>' + fence +
@@ -363,19 +338,21 @@ function initMarkdownIt() {
 		const _renderMath = (src, displayMode, env, authored) => {
 			const marker = displayMode ? '$$' : '$';
 			const source = authored || marker + src + marker, literal = md.utils.escapeHtml(source);
-			if (env.rapierPage) return '<span data-rapier-math-source="">' + literal + '</span>';
+			let encoded;
+			try { encoded = encodeURIComponent(source); }
+			catch (error) { if (!(error instanceof URIError)) throw error; }
+			const sourceHtml = '<span data-rapier-math-source="' + (encoded || '') + '">' + literal + '</span>';
+			if (env.rapierPage) return sourceHtml;
 			const mathProvider = env.rapierProviders === false ? null : _rapierProviders.math;
 			if (!mathProvider || mathProvider.status !== 'ready' || typeof mathProvider.renderToString !== 'function') {
 				if (!mathProvider?.request?.() && env.rapierProviders !== false && !_mathPromptedOnce) {
 					_mathPromptedOnce = true;
 					try { _rapierUiMath.request(); } catch (_) {}
 				}
-				return '<span class="math-placeholder" data-rapier-math-source="" title="Install the math plug-in in Settings to show this equation.">'
+				return '<span class="math-placeholder" data-rapier-math-source="' + (encoded || '') + '" title="Install the math plug-in in Settings to show this equation.">'
 						 + literal + '</span>';
 			}
 			try {
-				// The explicit output-only call keeps structured results beside the unchanged SVG
-				// islands. MathML never enters editable text projections or source serialization.
 				let rendered;
 				if (env.rapierMathEquations) {
 					const combined = mathProvider.renderWithMathML(src, {displayMode});
@@ -386,20 +363,13 @@ function initMarkdownIt() {
 					env.rapierMathEquations.push({source, tex: src, displayMode,
 						semantics: combined.semantics, errors: combined.errors});
 				} else rendered = mathProvider.renderToString(src, {displayMode});
-				let encoded;
-				try { encoded = encodeURIComponent(source); }
-				catch (error) {
-					// An ill-formed UTF-16 source cannot enter the URI-encoded edit marker.
-					// Keep the ordinary source-only HTML and the collected refusal diagnostic.
-					if (!(error instanceof URIError)) throw error;
-					return '<span data-rapier-math-source="">' + literal + '</span>';
-				}
+				if (encoded === undefined) return sourceHtml;
 				return '<span class="math-rendered" data-math-src="'
 						 + encoded + '">' + rendered + '</span>';
 			}
 			catch (error) {
 				if (env.rapierMathEquations) throw error;
-				return '<span data-rapier-math-source="">' + literal + '</span>';
+				return sourceHtml;
 			}
 		};
 		md.renderer.rules.math_inline = (tokens, idx, _opts, env) => _renderMath(tokens[idx].content, false, env, tokens[idx].meta?.mathSource);
@@ -427,10 +397,6 @@ function _rapierRenderSemanticRoot(canonical, metadata, options = {}) {
 	}
 
 	const markdown = _rapierSplitOpeningFrontmatter(canonical).body;
-	// Source-semantic output is independent of installed rendering providers. Complete
-	// artifacts keep the default provider path and materialize their visual content.
-	// A portable projection keeps natural sizing. Live readers opt into the same transient
-	// AUTO policy as the editor; neither a saved page nor its source inherits that choice.
 	const env = {rapierImagePresentation: options.imagePresentation === true, ...(options.page ? {rapierPage: true} : {}), ...(options.providers === false ? {rapierProviders: false} : {})};
 	if (options.mathEquations) env.rapierMathEquations = options.mathEquations;
 	let rendered = md
@@ -493,9 +459,6 @@ async function _rapierRenderSemanticRootAsync(canonical, metadata, options = {})
 			}
 		}
 		if (html) append();
-		// Token/environment objects are no longer inputs once their complete HTML
-		// is admitted. Drop our references before the document-wide DOM passes;
-		// never mutate an optional parsed result retained by another caller.
 		parsed = tokens = env = labels = null;
 		await finishAsync(_rapierSemanticDecorations(root), work);
 		await pause(work, .6);
@@ -690,9 +653,6 @@ function _rapierImageAltText(value, env = {}) {
 	return md.renderer.renderInlineAsText(tokens[0]?.children || [], md.options, env);
 }
 
-// Intrinsic facts are a presentation input, never an authored width or a resource admission.
-// Contain both edges within the column, sharing a 1.6-column sum-of-edges budget.
-// Reciprocal portraits/landscapes have equal weight; the native-width cap never enlarges art.
 function _rapierImageGeometryFacts(geometry, automatic) {
     const w = Number(geometry?.width), h = Number(geometry?.height);
     const known = Number.isFinite(w) && Number.isFinite(h) && w > 0 && h > 0 && Number.isFinite(w / h) && w / h > 0;
@@ -707,8 +667,6 @@ function _rapierImageGeometryFacts(geometry, automatic) {
     return {width, height, styles};
 }
 
-// Native loads supply their current element's dimensions synchronously. Embedded images
-// supply an admitted row only after their existing document/resource ticket checks.
 function _rapierApplyImageGeometry(image, geometry) {
     if (image?.tagName !== 'IMG' || image.hasAttribute('data-rapier-html')) return false;
     const mode = image.getAttribute('data-rapier-image-geometry');
@@ -726,8 +684,6 @@ function _rapierApplyImageGeometry(image, geometry) {
     ].filter(([name, value]) => image.getAttribute(name) !== value);
     const styles = facts.styles.filter(([name, value]) => (name === 'aspect-ratio'
         ? image.style.getPropertyValue(name).replace(/\s/g, '') : image.style.getPropertyValue(name)) !== value);
-    // Ordinary mutations revisit mounted images. Settled facts need no source-URL
-    // read or parse (which can be the entire inline image), nor any DOM writes.
     if (!attributes.length && !styles.length) return false;
     if (native) {
         const src = image.getAttribute('src'), current = image.currentSrc;
@@ -742,13 +698,9 @@ function _rapierApplyImageGeometry(image, geometry) {
 
 function _rapierImageSizeAttributes(size, marker, geometry, automatic = true) {
     const layout = globalThis.RapierMarkdownLayout.parseLayout(marker || '');
-    // Plain (rung 0, docs/standard-adoption.md): every picture renders at its natural width, the
-    // same as a reader with no layout facts at all -- Obsidian's `![alt|N]` alt-text width (the
-    // `size` fallback below) is a different, established convention and is unaffected.
     let style = layout && !_rapierPlainLayout() ? globalThis.RapierMarkdownLayout.imageStyle(layout) : '';
     let attributes = '';
     if (layout?.width != null && style) attributes = ' data-md-image-width="' + layout.width + '"';
-    // A fade rides beside any width, the alt-text's own included.
     else if (size) {
         attributes = ' width="' + size.width + '" data-rapier-image-size="' + size.width + '"';
         style = '--md-image-width:' + size.width + 'px' + (style ? ';' + style : '');
@@ -923,9 +875,6 @@ function* _rapierDisambiguateRenderedAnchorsSteps(root) {
 }
 
 function _rapierDecodeHash(hash) {
-	// A document's own address may carry a heading after it (`#d/<id>/<heading>`): the heading is the
-	// anchor, and an address with no heading names nothing to jump to. A view's (`#v/draw`,
-	// `#v/notes`) names no heading either (docs/agents.md "The address of a document").
 	let raw = String(hash || '').replace(/^#/, '');
 	const own = /^[dnv]\/[^/]*(?:\/(.*))?$/.exec(raw);
 	if (own) raw = own[1] || '';
@@ -958,8 +907,6 @@ function* _rapierDecorateJumpListsSteps(root) {
 		}
 	}
 
-	// Do not retain a live collection on the root that Copy will consume. Some
-	// DOM hosts eagerly refresh it on every later removal of a complete unit.
 	const first = root.firstElementChild, only = first && !first.nextElementSibling ? first : null;
 	if (only && only.tagName === 'P' && /^jump\s+to:?$/i.test(String(only.textContent || '').trim())) {
 		only.classList.add('rapier-jump-label-candidate');
@@ -969,7 +916,6 @@ function* _rapierDecorateJumpListsSteps(root) {
 function _rapierMarkFigureCaptions(root) { return finish(_rapierMarkFigureCaptionsSteps(root)); }
 
 function* _rapierMarkFigureCaptionsSteps(root) {
-	// Same path as a table caption: an ordinary paragraph after the picture, still the source line.
 	const figureCaption = /^Figure: /;
 	for (const paragraph of root.querySelectorAll('p')) { yield;
 		if (!figureCaption.test(paragraph.textContent || '')) continue;
@@ -1006,11 +952,6 @@ function* _rapierMarkListContinuationsSteps(blocks) {
 function _rapierMarkTableCaptions(root) { return finish(_rapierMarkTableCaptionsSteps(root)); }
 
 function* _rapierMarkTableCaptionsSteps(root) {
-	// The source convention is untouched: the caption stays an ordinary trailing paragraph
-	// (docs/markdown-standard.md). Only this rendered projection associates it with its table —
-	// via a generated id plus aria-describedby, not a real <caption>, which would have to move the
-	// paragraph inside <table> and break the one-DOM-node-per-source-block correspondence other
-	// passes (heading slugs, portable export) rely on for this same root.
 	const used = new Set(Array.from(root.querySelectorAll('[id]'), element => element.id));
 	let ordinal = 0;
 	for (const table of root.querySelectorAll('table')) { yield;
@@ -1038,7 +979,6 @@ function _rapierNormalizeCodeElement(code) {
 
 function _rapierLanguageClass(element) {
 	if (!element || !element.classList) return '';
-	// CommonMark's first info word is an identifier, including Unicode and punctuation.
 	const found = Array.from(element.classList).find(name => /^language-.+/i.test(name));
 	return found ? found.slice(9) : '';
 }
@@ -1174,28 +1114,15 @@ function* _rapierProjectPortableRootSteps(semanticRoot, options) {
 
 function* _rapierProjectPortableNodesSteps(semanticRoot, options) {
 	const opts = options || {};
-	// This projection is HTML-shaped (width baked into a CSS `style`, `data-*` stripped) for the
-	// consumers that read HTML -- publishing/fragment export, TXT. DOCX is not an HTML consumer: its
-	// writer (interchange/docx.mjs) reads the layout comment itself, so stripping it first and
-	// handing back CSS only throws the fact away before the writer ever sees it. `keepLayoutData`
-	// leaves the image and text layout records, ink meaning and paragraph alignment exactly as
-	// the semantic root carries them. Ordinary paragraph/list CSS measurements also reach their
-	// native reader; no derived private CSS is needed.
 	const keepLayoutData = !!opts.keepLayoutData;
-	// Copy owns its freshly rendered, detached root. Other callers retain their
-	// semantic tree and receive the usual independent portable projection.
 	const root = opts.inPlace ? semanticRoot : yield* cloneTree(semanticRoot), nativeElements = new Set();
-	// A source soft break is a reading space, never the editor's invisible token.
 	yield* _rapierResolveSoftBreakTokensSteps(root);
-	// Word consumes these source-bearing islands as pictures with TeX alternatives. Keep
-	// their SVG through this projection; the normal export sanitizer still owns admission.
 	if (opts.keepMath) for (const math of root.querySelectorAll('.math-rendered[data-math-src],.math-placeholder,[data-rapier-math-source]')) {
 		for (const element of [math, ...math.querySelectorAll('*')]) nativeElements.add(element);
 	}
 	if (opts.keepDiagrams) for (const figure of root.querySelectorAll('.diagram-block[data-diagram-native]')) {
 		const svg = figure.querySelector('.diagram-cache > svg.rapier-native-flowchart');
 		if (figure.getAttribute('data-diagram-state') === 'ready' && svg) {
-			// A class in authored HTML grants no exemption: only the native materialization above does.
 			for (const element of [svg, ...svg.querySelectorAll('*')]) nativeElements.add(element);
 			figure.replaceWith(svg);
 		}
@@ -1279,8 +1206,6 @@ function* _rapierProjectPortableNodesSteps(semanticRoot, options) {
 	for (const element of root.querySelectorAll('*')) { yield;
 		if (nativeElements.has(element)) continue;
 		const lang = element.tagName === 'CODE' ? _rapierLanguageClass(element) : '';
-		// The native note reader needs these transient roles to omit the renderer's
-		// separator and return-link spacing before it compares source-owned review notes.
 		const footnoteRole = keepLayoutData ? ['footnote-backref', 'footnotes-sep']
 			.filter(name => element.classList.contains(name)).join(' ') : '';
 		const captionRole = keepLayoutData ? ['rapier-table-caption', 'rapier-figure-caption']
@@ -1292,7 +1217,6 @@ function* _rapierProjectPortableNodesSteps(semanticRoot, options) {
 		const imageLayout = element.tagName === 'IMG' ? globalThis.RapierMarkdownLayout.parseLayoutAttribute(element.getAttribute('data-rapier-image-layout')) : null;
 		const measurements = keepLayoutData && /^(?:P|H[1-6]|LI|OL|UL)$/.test(element.tagName)
 			? ['text-indent', 'margin-inline-start'].map(property => [property, element.style.getPropertyValue(property)]) : [];
-		// The native table reader admits automatic hyphenation from ordinary paragraph CSS.
 		if (keepLayoutData && element.tagName === 'P' && element.closest('table') && element.style.getPropertyValue('hyphens').trim() === 'auto')
 			measurements.push(['hyphens', 'auto']);
 		if (keepLayoutData && element.closest('pre')) for (const property of ['color', 'font-weight', 'font-style'])
@@ -1312,8 +1236,6 @@ function* _rapierProjectPortableNodesSteps(semanticRoot, options) {
 		const isPageBreak = element.hasAttribute('data-md-break');
 		for (const attribute of Array.from(element.attributes)) { yield;
 			const name = attribute.name.toLowerCase();
-			// Copy reads these inert words from the final admitted nodes, then removes
-			// them before emitting HTML. They grant no rendering or resource authority.
 			if (opts.heldPictures && /^(?:SPAN|IMG)$/.test(element.tagName) &&
 					(name === 'data-rapier-remote-src' || name === 'data-rapier-remote-alt')) continue;
 			if (keepLayoutData && (name === 'data-rapier-image-layout' || name === 'data-md-layout' || name === 'data-md-align' || name === 'data-rapier-ink'
@@ -1344,8 +1266,6 @@ function* _rapierProjectPortableNodesSteps(semanticRoot, options) {
 		}
 		if (highlightHex) element.style.backgroundColor = highlightHex;
 		if (isTableCaption) { element.style.fontStyle = 'italic'; element.style.color = '#555555'; }
-		// Already validated facts serialize directly. An inert host's partial CSSOM must
-		// not silently discard a quoted family or round an authored decimal.
 		const css = typed.style(typography);
 		if (css) element.setAttribute('style', (element.getAttribute('style') ? element.getAttribute('style') + ';' : '') + css);
 
@@ -1370,9 +1290,6 @@ function _rapierPortableHtml(root) {
 }
 async function _rapierPortableHtmlAsync(root, work) { return finishAsync(serializeTree(root, sanitizeRapierHtml, true), work); }
 
-// One captured document owns this pipeline and its detached nodes. Global semantic
-// facts are resolved before projection. Final admission consumes the old tree a
-// complete fragment at a time; HTML and words then share that admitted tree.
 async function _rapierClipboardPayloadAsync(canonical, metadata, options = {}) {
 	const work = options.work;
 	let semantic;
@@ -1389,8 +1306,6 @@ async function _rapierClipboardPayloadAsync(canonical, metadata, options = {}) {
 		const plain = await finishAsync((function* () {
 			for (const html of htmlParts(semantic, 16384, true)) {
 				if (html === null) { yield; continue; }
-				// Reparse the complete transformed unit at the existing final export
-				// boundary. Both formats consume these admitted nodes before release.
 				admitHtml(part, html, sanitizeRapierHtml, runtime.sanitizeRapierFragment);
 				yield;
 				if (words) yield* words.write(part);
@@ -1408,9 +1323,6 @@ async function _rapierClipboardPayloadAsync(canonical, metadata, options = {}) {
 		check(work);
 		if (!options.formatted) return {plain};
 		return {plain, html: parts.join('').trim(), withoutPictures: pictures ? async () => {
-			// Only this writer's finished HTML reaches this closure. On refusal,
-			// reconstruct one complete fragment, change pictures to text and admit
-			// that changed output. No full fallback DOM survives the operation.
 			return finishAsync((function* () {
 				const output = [], part = document.createElement('div');
 				try {
@@ -1441,15 +1353,12 @@ function _rapierNormalizeInlineText(value) {
 		.trim();
 }
 
-// What a text file says where a picture stands: its words, and its address unless the picture is carried in the document itself.
 function _rapierPictureWords(alt, src) {
 	if (/^data:image\//i.test(src)) return alt ? '[Image: ' + alt + ']' : '[Image]';
 	if (src) return alt ? '[Image: ' + alt + ' — ' + src + ']' : '[Image: ' + src + ']';
 	return alt ? '[Image: ' + alt + ']' : '[Image]';
 }
 
-// Held Markdown and HTML pictures keep their addresses as inert data. Text export reads them before
-// the portable projection removes editor attributes, without restoring a fetching image source.
 function _rapierHeldPicturesAsWords(root) { return finish(_rapierHeldPicturesAsWordsSteps(root)); }
 async function _rapierHeldPicturesAsWordsAsync(root, work) { return finishAsync(_rapierHeldPicturesAsWordsSteps(root), work); }
 
@@ -1473,7 +1382,6 @@ function* _rapierPortableInlineTextSteps(node, options) {
 		return _rapierPictureWords(String(node.getAttribute('data-rapier-remote-alt') || '').trim(),
 			String(node.getAttribute('data-rapier-remote-src') || '').trim());
 	if (tag === 'BR') return '\n';
-	// A task's box is what the person sees of it.
 	if (tag === 'INPUT') return /^checkbox$/i.test(node.type || '') ? (node.checked || node.hasAttribute('checked') ? '☑ ' : '☐ ') : '';
 	if (tag === 'IMG') {
 		if (opts.visible) return '';
@@ -1510,7 +1418,6 @@ function* _rapierPortableListTextSteps(list, depth, options) {
 			else content.push(yield* _rapierPortableInlineTextSteps(child, opts));
 		}
 		const normalized = _rapierNormalizeInlineText(content.join('')), indent = '  '.repeat(level);
-		// A task shows its box where a bullet would be.
 		const marker = /^[☐☑☒]/.test(normalized) ? '' : ordered ? (counter++) + '. ' : '• ';
 		const parts = normalized.split('\n');
 		lines.push(indent + marker + (parts.shift() || ''));
@@ -1523,12 +1430,11 @@ function* _rapierPortableListTextSteps(list, depth, options) {
 	return lines.join('\n');
 }
 
-// A table, or a part of one a selection clipped out (a head, a body, a row): its rows.
 function _rapierPortableTableText(table, options) { return finish(_rapierPortableTableTextSteps(table, options)); }
 
 function* _rapierPortableTableTextSteps(table, options) {
 	const opts = options || {}, rows = [];
-	const walker = document.createTreeWalker(table, 1 /* SHOW_ELEMENT */);
+	const walker = document.createTreeWalker(table, 1 );
 	let row = table.tagName === 'TR' ? table : walker.nextNode();
 	while (row) {
 		yield;
@@ -1587,8 +1493,6 @@ function _rapierPortableTextWriter(options) {
 		for (let child = parent.firstChild; child; child = child.nextSibling) {
 			yield;
 			if (tablePart(child)) {
-				// A clipped table can cross an output fragment. Retain its words,
-				// not detached rows, until the next non-table node closes the block.
 				if (!current.table) { flush(current); current.table = []; }
 				current.table.push(yield* _rapierPortableTableTextSteps(child, opts));
 				continue;
@@ -1599,7 +1503,6 @@ function _rapierPortableTextWriter(options) {
 				flush(current);
 				yield* collectBlock(child);
 			} else if (opts.visible && child.nodeType === Node.ELEMENT_NODE && child.tagName === 'CODE' && String(child.textContent || '').includes('\n')) {
-				// Lines clipped from a code block retain every authored space.
 				flush(current);
 				pushBlock(String(child.textContent || ''), true);
 			} else current.inline.push(yield* _rapierPortableInlineTextSteps(child, opts));
@@ -1612,7 +1515,6 @@ function _rapierPortableTextWriter(options) {
 		const tag = node.tagName;
 		if (/^H[1-6]$/.test(tag) || tag === 'P') {
 			const text = _rapierNormalizeInlineText(yield* _rapierPortableInlineTextSteps(node, opts));
-			// An empty paragraph (the line Enter makes) is a line of its own, as it is in Word's plain text: one newline more between its neighbours.
 			if (tag === 'P' && !text && node.childNodes.length && !node.hasAttribute('data-md-break')) blocks.push({ text: '', blank: true });
 			else pushBlock(text, false);
 			return;
@@ -1667,7 +1569,6 @@ function _rapierPortableTextWriter(options) {
 	const pending = state();
 	return {write: root => collectChildren(root, pending, false), finish: function* () {
 	flush(pending);
-	// Each block stands a blank line from the next, and each empty paragraph between them adds one newline more.
 	let joined = '', blanks = 0;
 	for (const block of blocks) {
 		yield;
@@ -1680,8 +1581,6 @@ function _rapierPortableTextWriter(options) {
 	}};
 }
 
-// The text file Export writes: a Markdown document's portable words and one final newline, any other document's own text.
-// The editor's Export and the door's txt both end here.
 function _rapierPlainTextFile(context) {
 	return context.metadata.docKind === 'markdown'
 		? _rapierPortablePlainText(_rapierProjectPortableRoot(_rapierHeldPicturesAsWords(context.semanticRoot), { baseName: context.baseName }), { finalNewline: true })
@@ -1717,8 +1616,6 @@ function* _rapierResolveSoftBreakTokensSteps(root) {
 	return root;
 }
 
-// Markup parsed in a document of its own, which runs no script and loads nothing (Copy's clipboard tree): one element per
-// markup, or no boxes where the joined parse did not keep them apart.
 function _rapierInertParse(markups) {
 	const doc = new DOMParser().parseFromString(markups.map((html, at) => '<div data-rapier-batch="' + at + '">' + html + '</div>').join(''), 'text/html');
 	const boxes = [...doc.body.childNodes];
@@ -1739,8 +1636,6 @@ function _rapierBidiStrong(cp) {
 	return null;
 }
 
-// A consuming operation, not an editable DOM mode. Both outputs share one admitted
-// parse per equation; callers decide whether and how to expose the MathML to people.
 function renderWithMathML(source, metadata = {}) {
 	const provider = _rapierProviders.math;
 	if (!provider || provider.status !== 'ready' || typeof provider.renderToString !== 'function' ||