rapier-markdown-kit 1.2.8 → 1.2.9

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');
@@ -506,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))),
@@ -562,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;
@@ -617,10 +586,7 @@ 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 = [], document: live} = {}) {
-  // An export root is parsed in an inert document (no window, no body); the caller names the page whose sandboxed frames draw its objects.
   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');
@@ -648,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();
@@ -664,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);

package/dist/spec/md-layout.mjs

@@ -1,16 +1,7 @@
 // SPDX-License-Identifier: MIT
 
-// `rotate`: degrees in (-180, 180], one decimal, omitted when 0; never written for a Rapier drawing (its turn lives in its SVG).
-// `opacity`: a picture's fade, a whole percent from 5 to 100, omitted at 100; the picture's bytes never change.
-// `lines`: a picture or paragraph's initial letter spans 1 to 12 lines, from the first line's cap height to the Nth
-// baseline. A picture keeps its aspect ratio; never with `width`.
-// `first`/`indent`: signed levels of 2em, at most six decimals, in [-64,64], omitted at zero. `marker` moves a list
-// item's marker independently of its words, on the same scale; only the item's leading paragraph carries it.
-// `lock=on`: a picture locked in place: a tap goes to the words, never the picture; a hold takes it to unlock it. Omitted when off.
-// `hyphens=auto`, `caps=small`, `hanging=on`: paragraph typography; absence preserves ordinary text.
 export const fields = new Set(['align', 'width', 'lines', 'wrap', 'x', 'y', 'rotate', 'opacity', 'first', 'indent', 'marker', 'lock', 'hyphens', 'caps', 'hanging']);
 export const alignments = new Set(['left', 'center', 'right', 'justify']);
-// `behind`/`front`: out of flow; the paragraph lays out as though the picture were absent.
 export const wraps = new Set(['around', 'box', 'behind', 'front']);
 const has = (value, key) => Object.hasOwn(value, key);
 const percent = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 100;
@@ -18,7 +9,6 @@ const lineCount = value => Number.isInteger(value) && value >= 1 && value <= 12;
 export const INDENT_LIMIT = 64;
 export const indentLevel = value => typeof value === 'number' && Number.isFinite(value) && value !== 0 &&
   Math.abs(value) <= INDENT_LIMIT && Number(value.toFixed(6)) === value;
-// A key press advances an imported measure by one level without truncating its fraction or jumping across zero.
 export function stepIndent(value, step) {
   const next = Number(((value || 0) + step).toFixed(6));
   if (Math.abs(next) > INDENT_LIMIT) return value || 0;
@@ -27,7 +17,6 @@ export function stepIndent(value, step) {
 const oneDecimalDegrees = value => typeof value === 'number' && Number.isFinite(value) &&
   value > -180 && value <= 180 && Math.abs(value * 10 - Math.round(value * 10)) < 1e-9;
 
-/** Validate values independently of their Markdown attachment context. */
 export function validLayout(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value) ||
       Object.keys(value).some(key => !fields.has(key))) return false;
@@ -48,7 +37,6 @@ export function validLayout(value) {
     !(has(value, 'align') && (has(value, 'wrap') || has(value, 'x')));
 }
 
-/** Parse the closed v1 grammar. Geometry values are returned as numbers. */
 export function parseLayout(comment) {
   if (typeof comment !== 'string' || /[^\t\x20-\x7e]/.test(comment)) return null;
   const match = /^<!--md-layout:v1[ \t]+([^\r\n]*?)[ \t]*-->$/.exec(comment);
@@ -65,12 +53,10 @@ export function parseLayout(comment) {
           number[1] === '100' && /[1-9]/.test(number[2] || '')) return null;
       value[key] = Number(raw.slice(0, -1));
     } else if (key === 'y') {
-      // Negative allowed; signed like rotate, never "-0em".
       const number = /^(-)?(0|[1-9]\d*)(?:\.\d+)?em$/.exec(raw);
       if (!number || (number[1] && Number(raw.slice(1, -2)) === 0)) return null;
       value.y = Number(raw.slice(0, -2));
     } else if (key === 'rotate') {
-      // No '+', exponent, '°' or "-0deg"; 0 is unsigned.
       const number = /^(-)?(0|[1-9]\d*)(?:\.(\d))?deg$/.exec(raw);
       if (!number) return null;
       const magnitude = Number(number[2] + (number[3] ? '.' + number[3] : ''));
@@ -90,16 +76,12 @@ export function parseLayout(comment) {
   return validLayout(value) ? value : null;
 }
 
-// Comment delimiters are unsafe in sanitized attributes. Markdown stays literal;
-// rendered attributes carry encodeURIComponent(marker), including its '%' signs.
 export function decodeLayoutAttribute(value) {
   try { return decodeURIComponent(value || ''); } catch (_) { return ''; }
 }
 
 export const parseLayoutAttribute = value => parseLayout(decodeLayoutAttribute(value));
 
-// Indentation uses the document's body type, including on headings. Native table measurements
-// become ordinary CSS points; an item's margin is compensated by its paragraph and nested list.
 export function textStyle(value, {portable = false, pointSize, indentOffset = 0} = {}) {
   if (!validLayout(value)) return '';
   const property = {first: 'text-indent', indent: 'margin-inline-start'};
@@ -115,9 +97,6 @@ export function textStyle(value, {portable = false, pointSize, indentOffset = 0}
   return css.join(';');
 }
 
-// Raw HTML tables carry ordinary paragraph CSS. Read the browser's parsed declarations on the same
-// admitted scale; the native caller supplies the body's point size. A list marker belongs to its own li,
-// never to a paragraph or a picture.
 export function textLayout(style, {listMarker = false, pointSize, offset = 0} = {}) {
   const value = {};
   for (const [key, property] of (listMarker ? [['marker', 'margin-inline-start']] : [['first', 'text-indent'], ['indent', 'margin-inline-start']])) {
@@ -125,16 +104,12 @@ export function textLayout(style, {listMarker = false, pointSize, offset = 0} =
     const match = /^(-?(?:0|[1-9]\d*)(?:\.\d{1,6})?)(em|pt)$/.exec(raw);
     const level = Number(((match ? Number(match[1]) / (match[2] === 'pt' ? pointSize : 1) / 2 : 0) +
       (key === 'first' ? 0 : offset)).toFixed(6));
-    // Public CSS may compensate an enclosing item's margin; the resolved native coordinate,
-    // rather than each intermediate declaration, is the measurement the writer must keep.
     if (Number.isFinite(level) && level) value[key] = level;
   }
   if (!listMarker && style?.getPropertyValue('hyphens').trim() === 'auto') value.hyphens = 'auto';
   return value;
 }
 
-// The picture's own CSS: its normal-flow width and x, its height in lines, and its fade. `1cap` is the cap height of the
-// picture's own text; a renderer that sets the picture beside its anchor measures that paragraph's line and cap instead.
 export function imageStyle(value) {
   if (!validLayout(value)) return '';
   const parts = [];
@@ -144,7 +119,6 @@ export function imageStyle(value) {
       decimal(Number(Math.max(0, Math.min(100 - width, value.x - width / 2)).toFixed(6))) + '%;margin-right:0';
     parts.push('width:' + decimal(width) + '%;height:auto' + left);
   }
-  // Wider than the column at its own aspect, it is contained in the N-line box, never stretched.
   if (value.lines != null) parts.push('width:auto;max-width:100%;height:' + linesHeightCss(value.lines) + ';object-fit:contain');
   if (value.opacity != null && value.opacity < 100) parts.push('opacity:' + decimal(value.opacity / 100));
   return parts.join(';');
@@ -152,23 +126,17 @@ export function imageStyle(value) {
 
 export const linesHeightCss = lines => lines === 1 ? '1cap' : 'calc(' + (lines - 1) + ' * var(--md-line, 1.6em) + 1cap)';
 
-// An HTML object has an outer clip box and an independent browser viewport.
-// SCALE keeps that authored viewport; REFLOW keeps measured content height.
 export function objectHeight(width, naturalHeight, attrs, line) {
   if (attrs.height && attrs.height !== 'auto') return Math.min(4096, Number(attrs.height) * line);
   const [w, h] = (attrs.viewport || '640x360').split('x').map(Number);
   return attrs.resize === 'scale' ? Math.min(4096, width * h / w) : naturalHeight;
 }
 
-// Controls remain real DOM nodes while their surrounding text flows. A checkbox, link or
-// disclosure is not a reason to exclude its entire block from picture placement.
 export function wrapTextBlock(element) {
   return element && /^(P|H[1-6]|UL|OL|BLOCKQUOTE|DETAILS|DL)$/.test(element.tagName) &&
     element.textContent.trim() && !element.querySelector('img,table,pre,figure,math,.math-rendered') ? element : null;
 }
 
-// The one wrap-owner rule (layout/browser.js, kit/render.mjs, editor/share.js): text after, else before, skipping pictures,
-// metadata and empty paragraphs; any other block is a barrier in that direction.
 export function wrapNeighbour(node, classify, step = (n, direction) => n && n[direction > 0 ? 'nextElementSibling' : 'previousElementSibling']) {
   for (const direction of [1, -1]) {
     for (let sibling = step(node, direction); sibling; sibling = step(sibling, direction)) {
@@ -182,7 +150,6 @@ export function wrapNeighbour(node, classify, step = (n, direction) => n && n[di
   return null;
 }
 
-// Narrower than this, a line breaker splits words letter by letter.
 export function wrapColumnFloor(fontSize) {
   return Math.max(40, 3.5 * (fontSize || 16));
 }
@@ -199,7 +166,6 @@ function decimal(value) {
   return digits.slice(0, point) + '.' + digits.slice(point);
 }
 
-/** Write only the supplied facts; no alignment is implied by absence. */
 export function formatLayout(value) {
   if (!validLayout(value)) throw new TypeError('invalid_markdown_layout');
   const pairs = [];