rapier-markdown-kit 1.2.7 → 1.2.9

package/dist/spec/document-settings.mjs

@@ -1,17 +1,10 @@
 // SPDX-License-Identifier: MIT
-// One reader of document-wide settings and the inherited font snapshot.
-// Framing stays in spec/frontmatter.mjs. Reading never rewrites source.
-// The live view reads fontsize, the three font scopes and linestretch. It ignores papersize,
-// geometry and pagestyle: a scroll has no page. Word and the PDF read all of them.
 import {frontMatterFrame, frontMatterLine} from './frontmatter.mjs';
 import {normalizeFontFamily, fontFamilyCss, FONT_STACKS} from './md-marks.mjs';
 
-// Twelve points are one reference unit (16 px at the default reading scale).
 const NUMBER = /^(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
 export const DOCUMENT_LEADING = 1.75 / 1.1;
 
-// Before/after are points; line is a multiple of the element's own type size.
-// Presets and native exports read this same table. Explicit measures do not grow with font size.
 export const SPACING_TYPES = Object.freeze(['paragraph', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
 	'list', 'item', 'table', 'picture', 'drawing', 'quote', 'code', 'rule', 'footnote', 'toc']);
 export const SPACING_PRESETS = Object.freeze({compact: .7, standard: 1, roomy: 1.5});
@@ -19,7 +12,7 @@ const SPACING_SELECTORS = Object.freeze({paragraph: 'p', h1: 'h1', h2: 'h2', h3:
 	list: ':is(ul,ol)', item: 'li', table: ':is(table,.table-scroll-wrap)', picture: 'p[data-md-picture]',
 	drawing: ':is(.diagram-block,p[data-md-picture]:has(img[data-md-svg],img[src^="data:image/svg+xml"]))', quote: 'blockquote',
 	code: 'pre', rule: 'hr:not(.footnotes-sep):not([data-md-break])', footnote: '.footnotes', toc: '.rapier-jump-list'});
-const HEADING_LINE = [2 / 2.6, 1.5 / 1.9, 1.2 / 1.5, 1 / 1.25, .9 / 1.1, .82];
+const HEADING_LINE = [1.75 / 2.2, 1.5 / 1.75, 1.2 / 1.5, 1 / 1.25, .9 / 1.1, .82];
 
 export function normalizeDocumentSpacing(value) {
 	if (typeof value === 'string') {
@@ -60,7 +53,6 @@ export function documentSpacing(settings, kind = 'paragraph') {
 	return {before: before * scale * size, after: after * scale * size, line, ...spacing?.[type]};
 }
 
-// Word's widely supported Calibri/11 pt Normal template. Explicit document settings always win.
 export function wordDocumentSettings(settings) {
 	return {...settings, word: true, fontsize: settings?.fontsize || fontSize('11pt'),
 		mainfont: settings?.mainfont || documentFont('Calibri'), sansfont: settings?.sansfont || documentFont('Calibri'),
@@ -68,7 +60,7 @@ export function wordDocumentSettings(settings) {
 }
 export function documentHeadingSize(settings, level) {
 	const body = (settings?.fontsize?.unit || 1.1) * 12;
-	return body * (settings?.word ? [16/11,13/11,12/11,1,1,1] : [2.6,1.9,1.5,1.25,1.1,1])[level - 1];
+	return body * (settings?.word ? [16/11,13/11,12/11,1,1,1] : [2.2,1.75,1.5,1.25,1.1,1])[level - 1];
 }
 
 export function documentSpacingCss(settings, scope = '.md-render', defaults = false) {
@@ -80,7 +72,6 @@ export function documentSpacingCss(settings, scope = '.md-render', defaults = fa
 		css += selector + '{margin-block:' + length(row.before) + ' ' + length(row.after) + ';line-height:' + row.line + '}';
 		if (settings?.word && /^h[1-6]$/.test(type)) css += selector + '{font-size:' + length(documentHeadingSize(settings, Number(type[1]))) + '}';
 	}
-	// Compound blocks own the outside gap; the last child does not add it again.
 	css += scope + ' :is(li,td,th,blockquote)>:last-child{margin-bottom:0}' +
 		scope + ' li:last-child{margin-bottom:0}' + scope + ' li>:is(ul,ol){margin-bottom:0}' +
 		scope + ' .table-scroll-wrap>table{margin-block:0}' +
@@ -88,7 +79,10 @@ export function documentSpacingCss(settings, scope = '.md-render', defaults = fa
 		scope + ' pre code{line-height:inherit}' + scope + ' .footnotes{padding-top:0}' +
 		scope + ' .footnotes-list{margin-block:0}' + scope + ' blockquote:not(.callout){padding-block:0}';
 	const item = documentSpacing(settings, 'item');
-	css += scope + ' ul.rapier-jump-list>li{padding-block:0;margin-block:' + length(item.before) + ' ' + length(item.after) + '}' +
+	css += scope + ' li{--md-item-gap:' + length(Math.max(item.before, item.after)) + '}';
+	const list = documentSpacing(settings, 'list'), heading = documentSpacing(settings, 'h2');
+	css += scope + '{--md-list-heading-before:' + length(Math.max(list.after, heading.before)) + ';--md-list-heading-after:' + length(Math.max(heading.after, list.before)) + '}';
+	css += scope + ' ul.rapier-jump-list>li{--md-jump-pad:0px;margin-block:' + length(item.before) + ' ' + length(item.after) + '}' +
 		scope + ' ul.rapier-jump-list>li:last-child{margin-bottom:0}';
 	for (const [type, selector] of [['item','li>p'], ['table',':is(td,th)>p'], ['quote','blockquote>p'], ['footnote','.footnotes p'], ['toc','.rapier-jump-list li']])
 		css += scope + ' ' + selector + '{line-height:' + documentSpacing(settings, type).line + '}';
@@ -144,7 +138,6 @@ function marginOf(value) {
 	return Object.freeze({margin: match[1] + unit, twips});
 }
 
-// Token spans retain the source's quotes, comments and collection punctuation.
 function quotedEnd(text, start = 0, limit = text.length) {
 	const quote = text[start];
 	for (let at = start + 1; at < limit; at++) {
@@ -223,7 +216,6 @@ function fieldLine(line, indented = false) {
 function valueSpan(source, field, limit) {
 	let at = field.start;
 	const first = source[at];
-	// Tags and anchors may name other YAML values. They are retained, never rewritten by a control.
 	if (first === '&' || first === '*' || first === '!') {
 		field.opaque = true;
 		while (at < field.line.end && /[&*!]/.test(source[at])) {
@@ -268,7 +260,6 @@ function mapFields(source, lines, indent) {
 	return {fields, invalid};
 }
 
-// An append must never enter an unclosed collection or quoted value, including one under an unrelated key.
 function structureIsClosed(source, lines) {
 	let blockIndent = null, through = 0;
 	const limit = lines.at(-1)?.end ?? 0;
@@ -305,7 +296,6 @@ export function documentFont(value) {
 	return Object.freeze(named ? {...named, family} : {family, stack: 'named', css: fontFamilyCss(family), word: family});
 }
 
-// Font controls use the same source spans as the other document settings.
 export function writeDocumentFontSetting(markdown, key, value) {
 	if (!['mainfont', 'sansfont', 'monofont', 'defaultfont'].includes(key)) throw new TypeError('font: unknown document key');
 	const family = value == null ? null : normalizeFontFamily(value);
@@ -313,7 +303,6 @@ export function writeDocumentFontSetting(markdown, key, value) {
 	return updateDocumentSettings(markdown, {[key]: family});
 }
 
-// A language tag is metadata, never CSS or markup. Its source spelling stays untouched.
 export function languageTag(value) {
 	if (typeof value !== 'string' || value.length > 128 || !/^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/i.test(value)) return null;
 	try { return Intl.getCanonicalLocales(value)[0] || null; }
@@ -324,7 +313,6 @@ export function documentLanguage(settings, device = globalThis.navigator?.langua
 	return languageTag(settings?.lang) || languageTag(device) || 'en';
 }
 
-// Unrecognized fields remain authored bytes. A duplicate key has no single value.
 export function readDocumentSettings(markdown) {
 	const source = String(markdown ?? ''), {frame, fields} = fieldsOf(source);
 	if (!frame.closing) return EMPTY;
@@ -347,7 +335,6 @@ export function readDocumentSettings(markdown) {
 	});
 }
 
-// Change only supplied settings. Unrelated YAML, comments, line endings, BOM and body are never reprinted.
 export function updateDocumentSettings(markdown, patch) {
 	const source = String(markdown ?? ''), parsed = fieldsOf(source), {frame, fields} = parsed, before = readDocumentSettings(source);
 	const changes = [], append = [];
@@ -389,15 +376,11 @@ export function updateDocumentSettings(markdown, patch) {
 	return next;
 }
 
-// The page's <title>, the PDF's document title. Subtitle follows the title.
-// An absent title returns '' so the caller keeps the filename.
 export function documentTitle(settings) {
 	if (!settings || !settings.title) return '';
 	return settings.subtitle ? settings.title + ' \u2014 ' + settings.subtitle : settings.title;
 }
 
-// A supplied personal default replaces only the inherited snapshot. Explicit scopes win.
-// Omitted means use the portable source; null means the reader's factory default.
 export function documentSettingsFonts(settings, defaultFont) {
 	const inherited = defaultFont === undefined ? settings?.defaultfont : documentFont(defaultFont);
 	const main = settings?.mainfont || inherited;
@@ -416,8 +399,6 @@ export function documentSettingsStyle(settings, defaultFont) {
 	return (decls.length ? '.md-render{' + decls.join(';') + '}' : '') + documentSpacingCss(settings);
 }
 
-// Null when the page keys do not change the print sheet. The view never asks.
-// The default rule stays the writer's own: size:auto; margin:12mm 14mm 14mm.
 export function documentSettingsPageRule(settings) {
 	if (!settings || (!settings.papersize && !settings.geometry && settings.pagestyle !== 'plain')) return null;
 	const size = settings.papersize ? settings.papersize.css : 'auto';

package/dist/spec/frontmatter.mjs

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: MIT
-// Framing owns only offsets. No field interpretation or source normalization belongs here.
 export function frontMatterLine(text, start) {
 	let end = start;
 	while (end < text.length && text[end] !== '\r' && text[end] !== '\n') end++;

package/dist/spec/html-blocks.mjs

@@ -1,15 +1,12 @@
 // SPDX-License-Identifier: MIT
-// Fenced HTML stays source. Its preview has no document authority.
 import {inspectGIF} from '../images/gif.mjs';
 import {createMediaPlayback} from '../images/playback.mjs';
 import {sha256} from '../kit/ledger/hash.mjs';
 import {formatLayout, parseLayout, validLayout, imageStyle, objectHeight} from './md-layout.mjs';
 
-// The elements a preview keeps; every other element is removed with its content.
 export const HTML_ELEMENTS = Object.freeze('a abbr address article aside b bdi bdo blockquote br button caption circle clipPath code col colgroup dd defs del details dfn div dl dt ellipse em fieldset figcaption figure filter feBlend feColorMatrix feComponentTransfer feComposite feFlood feFuncA feFuncB feFuncG feFuncR feGaussianBlur feMerge feMergeNode feOffset footer g h1 h2 h3 h4 h5 h6 header hr i image img input kbd label legend li line linearGradient main mark mask meter nav ol optgroup option p path pattern picture polygon polyline pre progress q radialGradient rect s samp section select small source span stop strong style sub summary sup svg table tbody td text textarea th thead time title tr tspan u ul use var animate animateTransform animateMotion set mpath'.toLowerCase().split(' '));
 const VOID = new Set('area base br col embed hr img input link meta source track wbr'.split(' '));
 
-// The element names a preview removes from this body, in first-seen order. Content inside a removed element goes with it.
 export function htmlRemoved(body) {
   const allowed = new Set(HTML_ELEMENTS), removed = new Set(), tag = /<(\/?)([A-Za-z][\w:-]*)[^>]*?(\/?)>/g;
   for (let found; (found = tag.exec(body));) {
@@ -17,7 +14,6 @@ export function htmlRemoved(body) {
     if (found[1] || allowed.has(name)) continue;
     removed.add(name);
     if (VOID.has(name) || found[3]) continue;
-    // Skip to this element's own end tag; nested same-name elements stay counted.
     const inner = new RegExp('<(/?)' + name + '\\b[^>]*>', 'gi'); inner.lastIndex = tag.lastIndex;
     for (let depth = 1, next; depth && (next = inner.exec(body));) {depth += next[1] ? -1 : 1; tag.lastIndex = inner.lastIndex;}
     if (!new RegExp('</' + name + '\\b', 'i').test(body.slice(found.index))) break;
@@ -25,7 +21,6 @@ export function htmlRemoved(body) {
   return [...removed];
 }
 
-// Placement belongs to the trailing md-layout comment alone. Unknown keys are kept and ignored.
 export function htmlAttributes(info) {
   const match = /^html(?:\s+\{([^{}]*)\})?\s*$/i.exec(String(info));
   if (!match) return null;
@@ -64,7 +59,6 @@ export function htmlFence(raw) {
     layout: layout || HTML_FLOW, marker: attached ? {start: end + attached[1].length, end: end + attached[1].length + attached[2].length, text: attached[2]} : null};
 }
 
-// Without a layout comment a block is in normal flow across the column.
 const HTML_FLOW = Object.freeze({width: 100});
 
 export function htmlImageRecord(raw) {
@@ -73,8 +67,6 @@ export function htmlImageRecord(raw) {
     tokenEnd: raw.length, source: raw, placement: fence.layout, standalone: true, imageOnly: true};
 }
 
-// The first phase of the editor's bounded worker splits before layout annotation. Join only
-// the exact adjacent marker proven by this same source grammar, preserving offsets.
 export function mergeHtmlObjectBlocks(blocks, source) {
   for (let index = 0; index + 1 < blocks.length; index++) {
     const block = blocks[index], next = blocks[index + 1];
@@ -91,7 +83,6 @@ export function mergeHtmlObjectBlocks(blocks, source) {
 export function htmlLayoutEdit(record, value) {
   const fence = htmlFence(record.block.raw); if (!fence) return null;
   const layout = Object.fromEntries(Object.entries(value).filter(([,v]) => v != null));
-  // HTML height is its clipping viewport in document lines, not drop-cap sizing.
   const height = layout.lines; delete layout.lines;
   if (!validLayout(layout)) return null;
   const resizedHeight = height ?? (fence.attrs.resize === 'scale' && fence.attrs.height && fence.attrs.height !== 'auto' && layout.width && fence.layout.width
@@ -103,7 +94,6 @@ export function htmlLayoutEdit(record, value) {
     text: info + fence.source.slice(fence.infoEnd, fence.fenceEnd) + (marker ? line + marker : '') + tail};
 }
 
-// Change only owned header tokens. Body, fence spelling, class/id and unrelated attributes stay exact.
 function htmlInfoEdit(info, changes) {
   let text = info;
   for (const [key, value] of Object.entries(changes)) {
@@ -125,13 +115,10 @@ export function htmlPlaceholder(token, escape) {
   const layout = token.meta?.mdLayout?.layout || HTML_FLOW, marker = encodeURIComponent(formatLayout(layout));
   const height = attrs.height && attrs.height !== 'auto' ? attrs.height : 8;
   const source = encodeURIComponent(JSON.stringify({info: token.info, body: token.content, attrs, layout}));
-  // The image is the existing placement owner's measurable box. Preview content is mounted separately.
   const pixel = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=';
   return '<p class="rapier-html-block" data-md-layout="' + escape(marker) + '"><img data-rapier-markdown-image="" data-rapier-image-index="0" data-rapier-html="' + escape(source) + '" data-rapier-image-layout="' + escape(marker) + '" src="' + pixel + '" alt="' + escape(attrs.id || 'HTML block') + '" style="' + imageStyle(layout) + ';height:calc(' + height + ' * var(--md-line, 1.6em));object-fit:fill" /></p>\n';
 }
 
-// The frame owns CSS layout and pixels only. All commands are scoped to this
-// opaque window instance; no measurement or playback reply can edit source.
 function htmlFrameRuntime(config, media, win) {
   const send = value => win.parent.postMessage({type: 'rapier-object-state', id: config.id, ...value}, '*');
   let paused = true, disposed = false, generation = 0, timer = 0, motion = 0, signature = '', busy = false;
@@ -219,7 +206,6 @@ function htmlFrameRuntime(config, media, win) {
         for (const property of style) copy.style.setProperty(property, style.getPropertyValue(property), 'important');
         if (element.tagName === 'IMG' && element.dataset.rapierAnimation) copy.style.setProperty('visibility', rasters.find(row => row.image === element)?.visibility || 'visible', 'important');
         copy.style.setProperty('animation', 'none', 'important'); copy.style.setProperty('transition', 'none', 'important');
-        // SVG animated geometry is not represented by serialized timeline state.
         for (const attr of element.attributes) {
           const value = element[attr.name]?.animVal;
           if (value && typeof value.value === 'number') copy.setAttribute(attr.name, String(value.value));
@@ -236,8 +222,6 @@ function htmlFrameRuntime(config, media, win) {
           const p = element.animatedPoints.getItem(index); return p.x + ',' + p.y;
         }).join(' '));
         if (element.tagName === 'IMG' && element.dataset.rapierFirstFrame) copy.src = element.dataset.rapierFirstFrame;
-        // Pseudo content is a separate painted box; materialize it before removing
-        // stylesheets so media queries cannot run again in the smaller raster SVG.
         for (const pseudo of ['::before', '::after']) {
           const computed = win.getComputedStyle(element, pseudo), content = computed.content;
           if (!content || content === 'none' || content === 'normal') continue;
@@ -266,7 +250,6 @@ function htmlFrameRuntime(config, media, win) {
       if (!disposed && (width !== Math.ceil(win.innerWidth) || height !== Math.ceil(win.innerHeight))) {signature = ''; schedule();}
     }
   }
-  // A pending snapshot is never pushed back: a steady stream of resize notices (Firefox sends one per frame) must not starve it.
   const schedule = () => {if (!timer) timer = win.setTimeout(snapshot, 80); for (const row of rasters) rasterPosition(row);};
   const observer = new win.ResizeObserver(schedule); observer.observe(root);
   win.addEventListener('resize', schedule);
@@ -286,8 +269,6 @@ export function htmlRuntimeSource() {
   return '{const HTML_ELEMENTS=' + JSON.stringify(HTML_ELEMENTS) + ';(' + mountHtmlBlocks.toString() + ')(document,{media:(' + createMediaPlayback.toString() + ')(window,' + inspectGIF.toString() + '),frameRuntime:' + htmlFrameRuntime.toString() + ',heightOf:' + objectHeight.toString() + '});}';
 }
 
-// A poster is an ordinary existing Markdown image definition, bound to source
-// and the canonical export viewport. Placement still belongs only to md-layout.
 export function objectPosterLabel(image, width = 640) {
   if (!image.hasAttribute('data-rapier-html')) return posterLabel(image.getAttribute('data-rapier-animation'));
   const source = JSON.parse(decodeURIComponent(image.dataset.rapierHtml));
@@ -302,12 +283,8 @@ const posterLabel = (object, layout, width = 640) => {
   return 'rapier-poster-v1-' + sha256('rapier-object-poster-v1\nlight\n' + value);
 };
 
-// An act that removes or changes an object removes the still that belonged to it, in the same act.
-// Only objects the act touched are hashed; an identical untouched object keeps the shared still.
-// Picture definitions the same act retires (`retired`, offsets in after) take their stills with them.
 export function retiredPosterSplices(before, after, splices, retired = []) {
   if (!splices.length || !after.includes('rapier-poster-v1-')) return [];
-  // The changed window: the one splice itself, or the common prefix and suffix of a several-splice act.
   let start = 0, endBefore = before.length, endAfter = after.length;
   if (splices.length === 1) {start = splices[0].pos; endBefore = start + splices[0].removed.length; endAfter = start + splices[0].inserted.length;}
   else {
@@ -340,7 +317,6 @@ export function retiredPosterSplices(before, after, splices, retired = []) {
   return rows.reverse();
 }
 
-// One host presentation adapter: existing image geometry remains the authority.
 export function mountHtmlBlocks(doc, options = {}) {
   if (!options.root && doc.rapierObjects) return doc.rapierObjects;
   const root = options.root || doc.body;
@@ -351,7 +327,6 @@ export function mountHtmlBlocks(doc, options = {}) {
   const owned = new Map(), local = new Map(), reduced = win.matchMedia('(prefers-reduced-motion: reduce)');
   let pending = 0, dead = false, sequence = 0, noticed = false, identity = options.identity?.();
   const pixel = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR4nGNgAAIAAAUAAXpeqz8AAAAASUVORK5CYII=';
-  // Each frame gets its own nonce; the page's script nonce never enters a preview.
   const random = () => [...win.crypto.getRandomValues(new Uint8Array(16))].map(n => n.toString(16).padStart(2, '0')).join(''), prefix = random();
   const sheet = doc.createElement('style');
   sheet.textContent = 'img[data-rapier-live-surface]{filter:opacity(0)!important}@media print{[data-rapier-html-preview],[data-rapier-object-preview],[data-rapier-playback-control]{display:none!important}img[data-rapier-live-surface]{filter:none!important}}';
@@ -414,7 +389,6 @@ export function mountHtmlBlocks(doc, options = {}) {
           image.dispatchEvent(new win.Event('rapier-html-resize', {bubbles: true}));
         }
       }
-      // The control stacks just above its own object, never over the editor's toolbars, menus or notices.
       if (row.button) {row.button.hidden = !width || !height; row.button.style.zIndex = String((parseInt(css.zIndex) || 0) + 2); row.button.style.left = box.right - origin.left + parent.scrollLeft - parent.clientLeft - 44 + 'px'; row.button.style.top = box.top - origin.top + parent.scrollTop - parent.clientTop + 'px';}
     }
   }
@@ -429,7 +403,6 @@ export function mountHtmlBlocks(doc, options = {}) {
       const decoded = value.replace(/\\([0-9a-f]{1,6})\s?|\\([^\r\n])/gi, (_, hex, char) => hex ? String.fromCodePoint(Math.min(0x10ffff, parseInt(hex,16))) : char);
       if (value.includes('\\') && /(?:url|image-set|image|src)\s*\(|@import/i.test(decoded)) throw new Error('Escaped CSS resource is unsupported');
       if (/(?:image-set|image|src)\s*\(/i.test(decoded)) throw new Error('CSS image resources require an image element');
-      // A space keeps the token boundary: removing an import must not join image-@import x;set( into a new function.
       return value.replace(/@import(?![\w-])[^;{}]*;?/gi, ' ').replace(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)]*))\s*\)/gi, (_, a,b,c) => {
         const url = (a || b || c || '').trim();
         if (/^#[A-Za-z][\w.-]*$/.test(url)) return 'url("' + url + '")';
@@ -451,14 +424,12 @@ export function mountHtmlBlocks(doc, options = {}) {
         for (const attr of [...el.attributes]) {
           const name = attr.name.toLowerCase(), value = attr.value;
           if (name.startsWith('on') || name.startsWith('data-rapier-') || ['nonce','srcdoc','is','autofocus','form','formaction','action','target','download','ping','xmlns:xlink'].includes(name)) el.removeAttribute(attr.name);
-          // The local name: an SVG parsed as XML may bind XLink to any prefix (x:href).
           if (['src','srcset','href'].includes(attr.localName.toLowerCase()) && !(name.endsWith('href') && /^#[A-Za-z][\w.-]*$/.test(value) ||
               (name === 'src' && tag === 'img' || name.endsWith('href') && tag === 'image') && /^data:image\/(?:png|jpeg|webp|gif|jxl|svg\+xml);/i.test(value))) el.removeAttribute(attr.name);
         }
         if (tag.startsWith('animate') || tag === 'set') {
           const attribute = (el.getAttribute('attributeName') || '').trim().toLowerCase().split(':').pop();
           if (/^(?:href|base|on.*|style|src)$/.test(attribute)) {el.remove(); continue;}
-          // Event-triggered timelines have no interactive authority in this preview.
           if (/[a-z_]\w*\./i.test(el.getAttribute('begin') || '')) el.setAttribute('begin', '0s');
         }
         if (tag === 'button') el.setAttribute('type', 'button');
@@ -474,6 +445,7 @@ export function mountHtmlBlocks(doc, options = {}) {
             if (info) {pixels += info.width * info.height; if (pixels > 24000000) throw new Error('HTML image pixel budget'); admitted[url] = {width: info.width, height: info.height, animated: !!info.animated};}
             if (match[1].toLowerCase() === 'image/svg+xml') {
               const svgText = new win.TextDecoder('utf-8', {fatal: true}).decode(bytes);
+              if (/<!\s*(?:DOCTYPE|ENTITY)\b/i.test(svgText)) throw new Error('SVG declarations are unsupported');
               const parsed = new win.DOMParser().parseFromString(svgText, 'image/svg+xml');
               if (parsed.querySelector('parsererror') || parsed.documentElement.localName !== 'svg') throw new Error('Invalid SVG image');
               const svg = doc.importNode(parsed.documentElement, true);
@@ -505,7 +477,6 @@ export function mountHtmlBlocks(doc, options = {}) {
     const row = {image, key, parent, id: prefix + '-' + ++sequence, generation: 0, attrs: {}, visible: !visibility, paused: local.get(key) ?? reduced.matches};
     try {
       if (image.hasAttribute('data-rapier-html') || /^data:image\/svg\+xml;/i.test(key)) {
-        // A body over 1 MiB is refused below; refusing its base64 first keeps every synchronous decode that small.
         if (!image.hasAttribute('data-rapier-html') && key.length > 1398200) return;
         const value = image.hasAttribute('data-rapier-html') ? JSON.parse(decodeURIComponent(key)) : {
           body: new win.TextDecoder('utf-8', {fatal: true}).decode(Uint8Array.from(win.atob(key.slice(key.indexOf(',') + 1)), c => c.charCodeAt(0))),
@@ -561,7 +532,6 @@ export function mountHtmlBlocks(doc, options = {}) {
     const row = [...owned.values()].find(item => item.id === value.id && item.frame?.contentWindow === event.source);
     if (!row || keyOf(row.image) !== row.key || !row.image.isConnected) return;
     if (Number.isFinite(value.height) && value.height > 0 && value.height <= 4096) {
-      // A box whose own media queries answer its height turns back and forth forever: after a few turns it only grows.
       const turn = value.height > row.measured ? 1 : value.height < row.measured ? -1 : 0;
       if (turn && row.turn && turn !== row.turn) row.turns = (row.turns || 0) + 1;
       if (turn) row.turn = turn;
@@ -616,10 +586,8 @@ export function mountHtmlBlocks(doc, options = {}) {
   win.addEventListener('pagehide', hidden); win.addEventListener('pageshow', shown); if (!options.root) doc.rapierObjects = api; scan(); return api;
 }
 
-// Cold export uses the same opaque renderer, independently of the visible editor
-// and its caches. The caller owns original bytes; only detached display nodes change.
-export async function materializeObjects(root, {signal, width = 640, imageInfo, poster, bestEffort = false, issues = []} = {}) {
-  const doc = root.ownerDocument, win = doc.defaultView;
+export async function materializeObjects(root, {signal, width = 640, imageInfo, poster, bestEffort = false, issues = [], document: live} = {}) {
+  const doc = root.ownerDocument.defaultView ? root.ownerDocument : live, win = doc.defaultView;
   const images = [...root.querySelectorAll('img[data-rapier-html],img[data-rapier-animation]')];
   if (images.length > 64) throw new Error('Object export count budget');
   for (const image of images) {
@@ -646,7 +614,6 @@ export async function materializeObjects(root, {signal, width = 640, imageInfo,
       }
       await api.first(clone);
       const started = win.performance.now();
-      // A block that takes its content's height is captured at that height: a frame taken before it settled shows only its top.
       const settles = image.hasAttribute('data-rapier-html') && (() => {const attrs = JSON.parse(decodeURIComponent(image.dataset.rapierHtml)).attrs || {};
         return (!attrs.height || attrs.height === 'auto') && attrs.resize !== 'scale';})();
       const first = new win.Image();
@@ -662,7 +629,6 @@ export async function materializeObjects(root, {signal, width = 640, imageInfo,
           const frame = clone.dataset.rapierFirstFrame; first.src = frame;
           await first.decode(); signal?.throwIfAborted();
           if (!settles || !first.naturalWidth || Math.abs(clone.offsetWidth * first.naturalHeight / first.naturalWidth - clone.offsetHeight) <= 2) break;
-          // The next snapshot follows the settled viewport; wait for it.
           if (clone.dataset.rapierFirstFrame === frame) delete clone.dataset.rapierFirstFrame;
         }
         if (!first.naturalWidth || !first.naturalHeight || first.naturalWidth * first.naturalHeight > 24000000) throw new Error('First-frame image budget');

package/dist/spec/md-assets.mjs

@@ -10,19 +10,14 @@ let configured = null, splitSource = null;
 export function configureParser(parser, split) { configured = parser; splitSource = split; cached.length = 0; preparedDefinitions = []; }
 function fail(reason) { throw new Error(reason); }
 export const normalizeLabel = label => String(label).trim().replace(/\s+/g, ' ').toLowerCase().toUpperCase();
-// New titles have one identity before hashing, serializing or matching a repeated append.
-// Existing document bytes are never rewritten; CommonMark entity decoding must not change a title.
 export const assetTitle = value => String(value || '').replace(/[\r\n]/g, ' ').replace(/\0/g, '\ufffd');
 
-// The same hook runs in the editor, its parse worker and the agent's parser.
 export function installMarkdownImages(md) {
   if (md.__rapierImagesInstalled) return md;
   md.__rapierImagesInstalled = true;
   const validate = md.validateLink;
   md.validateLink = url => /^data:image\/(?:jxl|svg\+xml);base64,[A-Za-z0-9+/]+={0,2}$/i.test(url) || validate(url);
   const normalize = md.normalizeLink;
-  // An exact base64 data URL contains no URI escapes or host name to normalize.
-  // Preserve its spelling and avoid allocating one URI-normalizer item per raster byte.
   md.normalizeLink = url => /^data:image\/(?:jxl|png|jpeg|webp|gif|svg\+xml);base64,[A-Za-z0-9+/]+={0,2}$/i.test(url) ? url : normalize(url);
   const reference = md.block.ruler.__rules__.find(row => row.name === 'reference').fn;
   md.block.ruler.at('reference', (state, start, end, silent) => {
@@ -74,34 +69,21 @@ function parserFor(factory = configured || globalThis.markdownit) {
 export {parserFor as markdownParser};
 export const markdownBodyOffset = source => splitSource ? splitSource(source).bodyOffset : 0;
 
-// markdown-it's block state builds five tables with one entry per line of its whole input, and its rules index
-// them by line. A long body gets the parser's one block pass with tables that hold a run of lines instead: a read
-// past the lines they hold fills them further from the parser's own line scan, and they are emptied between
-// top-level blocks. No line is parsed twice, so every token and `env` are the ones a whole-input state yields.
 const BLOCK_WINDOW = 1024, TABLE_STEP = 128, WINDOW_END = Symbol('block window end');
 const LINE_TABLES = ['bMarks', 'eMarks', 'tShift', 'sCount', 'bsCount'];
 const lineIndex = key => typeof key === 'string' && /^(?:0|[1-9]\d*)$/.test(key);
-// An array reaches its prototype only for an index it does not hold. One prototype serves every pass, so the
-// parser's table reads see one more array shape, not one per pass.
 let unheldLine = null;
 const unheldLines = new Proxy(Array.prototype, {
   get: (target, key, table) => unheldLine && lineIndex(key) ? unheldLine(table, Number(key)) : Reflect.get(target, key, table),
   set: (target, key, value, table) => unheldLine && lineIndex(key) ? unheldLine(table, Number(key), true, value) : Reflect.set(target, key, value, table),
 });
 
-// The parser's block pass over source.slice(bodyOffset). `visit` receives top-level blocks as they finish:
-// `tokens` with line numbers counted from `firstLine`, and lineStart(line), the source offset where one of those
-// lines begins (undefined when the source ends before it). `env` is the whole pass's. The tables hold at most
-// the lines between two visits: BLOCK_WINDOW of them, or as many as one block's rules read.
 export function eachBlockWindow(source, bodyOffset, parser, env, visit, keepNul = false) {
   for (const window of blockWindows(source, bodyOffset, parser, env, keepNul)) visit(window);
 }
 
-// The same tokenizer can pause between complete top-level windows; no grammar rule is suspended.
 export function* blockWindows(source, bodyOffset, parser, env, keepNul = false) {
   const lineEnds = source.slice(bodyOffset).replace(/\r\n?/g, '\n'), body = keepNul ? lineEnds : lineEnds.replace(/\0/g, '\ufffd');
-  // The body is the source with every CRLF one unit shorter: count the pairs before a body offset, from the last
-  // offset asked.
   let pair = source.indexOf('\r\n', bodyOffset), shift = bodyOffset;
   const sourceOffset = at => {
     while (pair >= 0 && at + shift > pair) { shift++; pair = source.indexOf('\r\n', pair + 2); }
@@ -110,7 +92,6 @@ export function* blockWindows(source, bodyOffset, parser, env, keepNul = false)
   };
   const tokens = [];
   let origin = 0, first = 0, state;
-  // A line begins after the newline that ends the line before it. No rule writes eMarks.
   const report = () => ({tokens, firstLine: first, lineStart: line => {
     if (!line) return sourceOffset(origin);
     const end = Object.hasOwn(state.eMarks, line - 1) ? state.eMarks[line - 1] : body.length;
@@ -120,18 +101,17 @@ export function* blockWindows(source, bodyOffset, parser, env, keepNul = false)
   for (let at = 0; at < body.length; at++) if (body.charCodeAt(at) === 10) lines++;
   if (lines <= BLOCK_WINDOW) {
     state = new parser.block.State(body, parser, env, tokens);
+    state.rapierSourceSlice = (from, to) => source.slice(sourceOffset(from), sourceOffset(to));
     parser.block.tokenize(state, state.line, state.lineMax);
     yield report(); return;
   }
-  // The parser's own count of a last line that no newline ends: it does not count one of only spaces.
   state = new parser.block.State(body.slice(body.lastIndexOf('\n') + 1), parser, env, tokens);
+  state.rapierSourceSlice = (from, to) => source.slice(sourceOffset(from), sourceOffset(to));
   lines += state.lineMax;
   state.src = body;
   const tables = new WeakMap();
   for (const name of LINE_TABLES) { state[name].length = 0; tables.set(Object.setPrototypeOf(state[name], unheldLines), name); }
   let frontier = 0, ended = false, betweenBlocks = false;
-  // A rule may be reading a table when it grows, so the five arrays are replaced whole; an array a rule still
-  // holds is left empty, and `answer` reads and writes the state's current one in its place.
   const fill = line => {
     while (!ended && line >= state.bMarks.length) {
       const held = state.bMarks.length;
@@ -142,7 +122,6 @@ export function* blockWindows(source, bodyOffset, parser, env, keepNul = false)
       }
       const scanned = new parser.block.State(body.slice(frontier, until), parser, env, []);
       ended = until === body.length;
-      // The scan's last entry stands for the end of its input, which is the body's end only for the last scan.
       const added = ended ? scanned.lineMax + 1 : scanned.lineMax;
       for (const name of LINE_TABLES) {
         const old = state[name], next = scanned[name], offset = name === 'bMarks' || name === 'eMarks' ? frontier : 0, table = [];
@@ -167,8 +146,6 @@ export function* blockWindows(source, bodyOffset, parser, env, keepNul = false)
     else Object.defineProperty(current, line, {value, writable: true, enumerable: true, configurable: true});
     return true;
   };
-  // The top-level loop calls this between two blocks with the line it stands on. There every token is a finished
-  // block and no rule is running, so the pass can leave the tokenizer and enter it again at that line.
   const skipEmptyLines = state.skipEmptyLines;
   state.skipEmptyLines = function (line) {
     if (this.level || line !== this.line || !line) return skipEmptyLines.call(this, line);
@@ -179,7 +156,6 @@ export function* blockWindows(source, bodyOffset, parser, env, keepNul = false)
     return line;
   };
   for (;;) {
-    // Between top-level blocks the parser's loop only steps over empty lines, so a run of them is never tabled.
     for (let at = origin; at < body.length; at++) {
       const code = body.charCodeAt(at);
       if (code === 10) { origin = at + 1; first++; }
@@ -213,7 +189,6 @@ export function dataImage(url) {
   return {codec: match[1].toLowerCase(), byteLength, payloadStart: match[0].length - match[2].length};
 }
 
-// Markdown-it owns recognition, nesting, duplicate precedence and escapes; block parse only.
 export function parseAssets(source, factory = configured || globalThis.markdownit, bodyOffset = 0) {
   const steps = assetSteps(source, factory, bodyOffset);
   let next = steps.next();
@@ -249,7 +224,6 @@ function* assetSteps(source, factory = configured || globalThis.markdownit, body
       let end = stop;
       if (source[end - 1] === '\n') end--;
       if (source[end - 1] === '\r') end--;
-      // Repeated definitions are source, not additional image owners.
       const raw = source.slice(start, end), found = raw.indexOf(definition.href);
       const repeated = found >= 0 ? raw.indexOf(definition.href, found + 1) : -1;
       const labelContainsUrl = definition.href.length <= id.length && id.includes(parser.utils.normalizeReference(definition.href));
@@ -277,8 +251,6 @@ function* assetSteps(source, factory = configured || globalThis.markdownit, body
 }
 export function documentAssets(source, factory) { return parseAssets(source, factory, markdownBodyOffset(source)); }
 
-// The source worker admits these rows with the same Markdown grammar. Send positions and
-// small facts back, then take the large picture strings from the exact request's source.
 export function packAssetIndex(index, offset = 0) {
   const positions = ['start', 'end', 'urlStart', 'urlEnd', 'payloadStart', 'payloadEnd'];
   const blocks = index.blocks.map(row => {
@@ -314,8 +286,6 @@ export function restoreAssetIndex(source, packet, {offset = 0, bodyOffset = 0, f
   const index = {assets, blocks, duplicateLabels: new Set(packet.duplicateLabels), appendixStart: packet.appendixStart + offset, references};
   cached.unshift({source, factory, bodyOffset, index});
   if (cached.length > 3) cached.pop();
-  // A top-level reference token is exactly the block the editor keeps. Its own parse has
-  // one first definition even when it followed a duplicate in the whole document.
   preparedDefinitions = blocks.filter(row => row.topLevel).map(row => {
     const local = {...row, start: 0, end: row.source.length, active: true, status: 'unverified'};
     for (const key of positions.slice(2)) if (Number.isSafeInteger(local[key])) local[key] -= row.start;
@@ -327,8 +297,6 @@ export function restoreAssetIndex(source, packet, {offset = 0, bodyOffset = 0, f
   return index;
 }
 
-// Project only parser-recognized payload spans. Their ordinary data URL remains a data URL,
-// with every source newline intact; the parser never needs megabytes of picture bytes.
 export function projectImageDefinitions(source, index) {
   const records = [], parts = [];
   let at = 0, length = 0;
@@ -350,14 +318,6 @@ export function projectImageDefinitions(source, index) {
   return {source: records.length ? parts.join('') : source, records, references};
 }
 
-// The same index folded from the document's top-level blocks: `rows` are the blocks as markdown-it's block parse
-// of the body cuts them, each {start, raw} with `start` absolute in `source`, and `parse(raw, row)` is parseAssets
-// over one block (the caller may cache it by the row). A definition the whole parse finds is one a block's own parse
-// finds at the block's place, because a top-level block's lines parse the same alone as in the document; labels,
-// duplicates, the first definition's precedence, the count limit and the appendix fold as parseAssets folds them.
-// Null when the rows are not this source: a block's bytes elsewhere than its start, rows out of order or overlapping,
-// or text that could hold a definition (`]:`) between the body's start, the rows and the end, where no row parses
-// it. Positions are the source's own, never normalized.
 export function blockwiseAssets(source, rows, parse = raw => parseAssets(raw), bodyOffset = markdownBodyOffset(source)) {
   if (typeof source !== 'string' || !Array.isArray(rows)) return null;
   const blocks = [], references = Object.create(null), duplicateLabels = new Set(), seen = new Set(), assets = new Map();
@@ -368,8 +328,6 @@ export function blockwiseAssets(source, rows, parse = raw => parseAssets(raw), b
     cursor = start + raw.length;
     if (!raw.includes(']:')) continue;
     const index = parse(raw, row);
-    // Every label the block defines, picture or not: an earlier definition of a label, of any kind, is the one
-    // the document resolves, so a later picture under it is inactive and the label a duplicate.
     const labels = Object.keys(index.references);
     for (const label of index.duplicateLabels) duplicateLabels.add(label);
     for (const label of labels) {
@@ -439,7 +397,6 @@ function imageUses(source, factory, env = {}) {
     for (const [raw, rows] of groups) {
       const found = [];
       for (let at = body.indexOf(raw, start); at >= 0 && at + raw.length <= end; at = body.indexOf(raw, at + raw.length)) found.push(at);
-      // Repeated text in code or an unmapped container is not deletion proof.
       if (found.length !== rows.length) continue;
       found.forEach((at, index) => images.push({...rows[index], start: originalOffset(at), end: originalOffset(at + raw.length)}));
     }
@@ -449,7 +406,6 @@ function imageUses(source, factory, env = {}) {
   return {urls, images, simple, html: html.join('\n').toUpperCase()};
 }
 
-// A parse failure answers true: uncertainty keeps the definition.
 export function referenceOccurs(source, id, factory) {
   try { return imageUses(source, factory).images.some(image => image.id === id); }
   catch (_) { return true; }
@@ -469,11 +425,8 @@ function occurrenceChange(image, splices) {
   return changed ? {start, end} : null;
 }
 
-// A permissive gate keeps ordinary typing out of full-document image parsing.
-// Recognition and retirement proof still belong to Markdown-it below.
 export function mayRetireImageDefinitions(source, splices, factory, hint) {
   const store = typeof source === 'string' ? null : source;
-  // A definition's closing bracket is immediately followed by its colon (parseAssets uses the same necessary condition).
   if (store ? !store.contains(']:') || !store.contains('data:image/', true)
     : !source.includes(']:') || !/data:image\//i.test(source)) return false;
   const original = (at, right, count) => {
@@ -488,8 +441,6 @@ export function mayRetireImageDefinitions(source, splices, factory, hint) {
     if (!row.removed && !row.inserted) return false;
     const start = original(row.pos, false, index), end = original(row.pos + row.removed.length, true, index);
     if (store) {
-      // No image use exists without this marker. A definition appendix alone must
-      // not make a prose keystroke join the document to prove that.
       if (!store.contains('![')) return false;
       const from = Math.max(0, start - 8192);
       const local = store.readSlice(from, Math.min(store.length, end + 4));
@@ -502,9 +453,6 @@ export function mayRetireImageDefinitions(source, splices, factory, hint) {
         return false;
       };
       if (separator >= 0 || from === 0) return exclude(separator >= 0 ? from + separator + 4 : 0);
-      // Still inside a longer paragraph. Walk back in slices to the blank line.
-      // Finding an image there is the same "possible" answer as the 8KiB window;
-      // finding the break, or none, does not read the joined document.
       let cursor = from;
       while (cursor > 0) {
         const sliceFrom = Math.max(0, cursor - 8192);
@@ -540,8 +488,6 @@ export function mayRetireImageDefinitions(source, splices, factory, hint) {
   } catch (_) { return true; }
 }
 
-// Whole deletion or a valid replacement at the rebased occurrence may retire
-// bytes. Unfinished source edits and pre-existing unused definitions do not.
 export function retireDeletedImageDefinitions(before, after, splices, factory) {
   if (before === after || !mayRetireImageDefinitions(before, splices, factory)) return [];
   try {
@@ -567,8 +513,6 @@ export function retireDeletedImageDefinitions(before, after, splices, factory) {
   } catch (_) { return []; }
 }
 
-// Disclosure stays conservative even for code examples and malformed definitions.
-// Keep labels and readable prose; omit only the binary destination.
 export function assetOmissions(source) {
   if (typeof source !== 'string') return [];
   const pattern = /data:(image\/[a-z0-9.+-]+);base64,[A-Za-z0-9+/=\\;&%#._~-]*/ig, spans = [];
@@ -594,7 +538,6 @@ export function isAssetBlock(raw) {
   return /^[ \t\r\n]*$/.test(raw.slice(at));
 }
 
-// Mirrors engine.js _rapierEscapeImageAlt without importing the editor bundle.
 export function escapeImageAlt(value) {
   return String(value ?? '').replace(/[\r\n]+/g, ' ')
     .replace(/[\\[\]*_`~^+$=<&]/g, '\\$&').replace(/\|(?=[1-9]\d{1,3}$)/, '\\|');
@@ -604,8 +547,6 @@ export function serializeAsset(asset) {
   const value = assetTitle(asset.title), title = value ? ' "' + value.replace(/&/g, '&amp;').replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"' : '';
   return '[' + asset.label + ']: ' + asset.url + title;
 }
-// Pure: re-derived at commit against the moved document; appends only at the text's end.
-// A replay supplies the retained definition's line ending instead of choosing one from later prose.
 export function appendAssetText(source, asset, lineEnding, {preserveLabel = false} = {}) {
   if (typeof source !== 'string' || !asset || normalizeLabel(asset.label) !== asset.id) return fail('image_source_invalid');
   const parsed = documentAssets(source), title = assetTitle(asset.title);