rapier-markdown-kit 1.2.8 → 1.2.9

package/dist/spec/md-marks.mjs

@@ -1,8 +1,6 @@
 // SPDX-License-Identifier: MIT
-// The one owner of inline typography, ink and page breaks.
 import {markdownSourcePositions} from './md-source.mjs';
 
-// The exported page retains this reader alone. The editor uses the same closure, then adds its writers and scans.
 const inkReader = () => {
 	// SPDX-License-Identifier: MIT
 	const TEXT_COLOR_NAMES = Object.freeze({ green: '#1c7547', red: '#b32034', blue: '#175dc4', gold: '#865818', purple: '#7924d7' });
@@ -10,16 +8,6 @@ const inkReader = () => {
 	const COLOR_NAME_ALT = Object.keys(TEXT_COLOR_NAMES).join('|');
 	const COLOR_VALUE = '(?:#[0-9a-f]{6}|' + COLOR_NAME_ALT + ')';
 
-	// Ink (docs/markdown-standard.md, "Ink"): a pen stroke that stays with the words it marks, a paired comment with the color span's shape. The
-	// opener holds the stroke:
-	//   <!--ink KIND [NUMBER] [COLOUR] [w=N] [box=W,H] [at=X,Y] [PATH]-->words<!--/ink-->
-	// KIND is the stroke's kind, decided once when it was lifted; COLOUR is exactly the color span's value, red when absent; box is the frame's
-	// size when the stroke was drawn and at the frame's offset from the words' box, both in hundredths of an em; w is the pen's width as Draw
-	// counts a nib (2 to 24; 9 is the default and is never written): the stroke is drawn 0.11 em wide at 9 and in proportion to w otherwise; PATH
-	// is the stroke, its first point absolute in the frame and the rest as moves, hundredths of an em. One spelling: the fields in this order,
-	// one space between, integers only. A comment that does not read this way is ordinary comment text and marks nothing. Ink pairs nest:
-	// each closer takes the innermost open ink opener. Arrow/end alone take a pairing number, an end takes no other data; under, strike and arrow may omit a path for a line
-	// derived from their words.
 	const INK_KINDS = Object.freeze(['under', 'strike', 'ring', 'bracket', 'free', 'arrow', 'end']);
 
 	const INK_PATH_MAX = 160;
@@ -88,7 +76,6 @@ export const FONT_STACKS = Object.freeze({
 	hand: Object.freeze({stack: 'hand', css: 'cursive', word: 'Segoe Print'}),
 });
 
-// A family is one font-table name, never a CSS list or an HTML fragment.
 export function normalizeFontFamily(value) {
 	if (typeof value !== 'string') return null;
 	const family = value.trim();
@@ -106,8 +93,6 @@ export function formatFontRun(family, content) {
 	return typography.wrap({family}, content);
 }
 
-// One typed interpretation for source, DOM and native-file adapters. The worker carries this
-// exact factory and its explicit grammar inputs; no DOM, CSS evaluator or resource loader.
 export function createTypography({normalizeFontFamily, fontFamilyCss, FONT_STACKS}) {
 	const LIMIT = 4096, DEPTH = 64;
 	const generics = {serif: 'serif', 'sans-serif': 'sans', monospace: 'mono', cursive: 'hand',
@@ -127,7 +112,6 @@ export function createTypography({normalizeFontFamily, fontFamilyCss, FONT_STACK
 	function color(value) {
 		if (typeof value !== 'string') return null;
 		if (/^#[0-9a-f]{6}$/i.test(value.trim())) return value.trim().toLowerCase();
-		// CSSOM serializes admitted hex to opaque rgb(). Native HTML import uses this same boundary.
 		const rgb = /^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*(?:,\s*1\s*)?\)$/i.exec(value.trim());
 		return rgb && rgb.slice(1).every(channel => Number(channel) <= 255)
 			? '#' + rgb.slice(1).map(channel => Number(channel).toString(16).padStart(2, '0')).join('') : null;
@@ -154,7 +138,6 @@ export function createTypography({normalizeFontFamily, fontFamilyCss, FONT_STACK
 			}
 		} else if (!/^[\p{L}_-][\p{L}\p{N}_ -]*$/u.test(css) || /^(?:inherit|initial|unset|revert|revert-layer)$/i.test(css)) return null;
 		name = normalizeFontFamily(name);
-		// These five names are the existing family-choice aliases, not custom font identities.
 		if (name && Object.hasOwn(FONT_STACKS, name.toLowerCase())) return null;
 		return name ? Object.freeze({name, css: '"' + name.replace(/[\\"]/g, '\\$&') + '"', custom: true}) : null;
 	}
@@ -178,8 +161,6 @@ export function createTypography({normalizeFontFamily, fontFamilyCss, FONT_STACK
 		}
 		return Object.freeze(result);
 	}
-	// Rendering drops unsupported declarations; rich editing admits only wholly owned
-	// spans so unrelated HTML and rejected attributes keep their exact-source editor.
 	function parseStyle(value, editable = false) {
 		if (typeof value !== 'string' || value.length > LIMIT) return editable ? null : Object.freeze({});
 		const parts = []; let quote = '', start = 0;
@@ -212,15 +193,11 @@ export function createTypography({normalizeFontFamily, fontFamilyCss, FONT_STACK
 	const wrap = (value, content) => {
 		const start = open(value);
 		if (!start || !content) return content;
-		// Importers can supply a styled break by itself, or before/after words. Keep
-		// those exact line-edge bytes outside the new span so its opener has words.
 		const prefix = /^(?:[ \t]*(?:\r\n|\r(?!\n)|\n))+/.exec(content)?.[0] || '';
 		let body = content.slice(prefix.length);
 		const suffix = /(?:[ \t]*(?:\r\n|\r(?!\n)|\n))+[ \t]*$/.exec(body)?.[0] || '';
 		body = body.slice(0, body.length - suffix.length);
 		if (!body) return content;
-		// Soft/hard line breaks can belong to one Markdown paragraph. A blank line or
-		// an opener on a line of its own would instead change the block grammar.
 		if (/^\s*\n|\n[ \t]*\n/.test(body.replace(/\r\n?/g, '\n')))
 			throw new TypeError('Typography wraps one inline paragraph at a time.');
 		return prefix + start + body + '</span>' + suffix;
@@ -323,8 +300,6 @@ const inkPair = (value, name, nonNegative = false) => {
 	return pair;
 };
 
-// {kind, id?, hex?, width?, box?, at?, path?} to the opener; the path's points are absolute in the frame and become moves after the
-// first. Refuses with a TypeError rather than writing a spelling the reader would not read.
 export function formatInkOpen(mark) {
 	if (!mark || typeof mark !== 'object') throw new TypeError('ink: a mark is an object');
 	if (!INK_KINDS.includes(mark.kind)) throw new TypeError('ink: the kind is one of ' + INK_KINDS.join(', '));
@@ -358,7 +333,6 @@ export function formatInkRun(mark, content) {
 	return formatInkOpen(mark) + content + INK_CLOSE;
 }
 
-// Returns {mark, length in UTF-16 units} or null; not end-anchored.
 export function matchInkOpen(text) {
 	if (typeof text !== 'string') return null;
 	const match = new RegExp('^' + INK_OPEN_PATTERN).exec(text);
@@ -367,10 +341,6 @@ export function matchInkOpen(text) {
 	return mark && { mark, length: match[0].length };
 }
 
-// The opener's body is what a rendered span carries (a renderer's sanitizer drops an attribute whose value holds the
-// comment's own close): the opener after `<!--ink ` and before `-->`, so the attribute reads `under red box=… 0,95 …`,
-// and only a body that reads as a mark goes back. Read and write through the same grammar, so an invalid body cannot
-// invent a mark.
 export function inkOpenBody(opener) {
 	if (typeof opener !== 'string') return null;
 	const match = new RegExp('^' + INK_OPEN_PATTERN + '$').exec(opener);
@@ -384,10 +354,6 @@ export function isInkClose(comment) {
 	return comment === INK_CLOSE;
 }
 
-// Every ink marker in order: {start, end, mark} for an opener (mark null for a closer, and an opener whose path
-// overflows is not a marker at all).
-// Without a prior arrow or adjacent marker bytes, only an edit boundary can empty a span.
-// Read those boundaries through the planned rows before asking the full grammar to retire ink.
 export function mayRetireInk(source, rows) {
   if (source.contains('<!--ink arrow ') || source.contains('<!--ink end ') || source.contains('--><!--')) return true;
   let pieces = [{from: 0, length: source.length}], length = source.length;
@@ -430,20 +396,14 @@ export function scanInkMarkers(source) {
 	return markers;
 }
 
-// Ink nests so independent strokes can share the same words. A marker that pairs with nothing is text
-// (it shows nothing and marks nothing) and is listed under strays.
 export function pairInkMarkers(source, markers = null) {
 	return pairMarkers(source, 'ink', markers);
 }
 
-// A document parser may supply its semantic markers, leaving literal code comments untouched.
-// Local inline parsing and source planners need an endpoint's span even when its mate is in another block.
 export function pairInkSpans(source, markers = null) {
 	return pairSpanMarkers(source, 'ink', markers);
 }
 
-// Color keeps its first opener; ink pairs each closer with the innermost opener. The shared range
-// shape lets custody owners keep every independent stroke, including strokes on identical words.
 export function pairMarkers(source, kind, markers = null) {
 	const paired = pairSpanMarkers(source, kind, markers);
 	if (kind !== 'ink') return paired;
@@ -470,9 +430,6 @@ export function pairMarkers(source, kind, markers = null) {
 	return { runs, strays, arrows };
 }
 
-// Where a Will marker may stand (docs/will.md, Conversion). A pair inside a fence, a raw HTML block
-// (until its blank line) or the opening front matter is text: the line is quoted,
-// and a Word or PDF writer that met it as a marker would govern the wrong region. The same frame
 // as spec/frontmatter.mjs, copied here so this grammar stays inside the MIT kit's closure.
 const WILL_BLOCK_TAGS = new Set('address article aside base basefont blockquote body caption center col colgroup dd details dialog dir div dl dt fieldset figcaption figure footer form frame frameset h1 h2 h3 h4 h5 h6 head header hr html iframe legend li link main menu menuitem nav noframes ol optgroup option p param search section summary table tbody td tfoot th thead title tr track ul'.split(' '));
 const WILL_VOID_TAGS = new Set('area base br col embed hr img input link meta param source track wbr'.split(' '));
@@ -620,9 +577,6 @@ function willLeaf(stack) {
 	return kind === 'fence' || kind === 'pre' || kind === 'html' || kind === 'raw';
 }
 
-// `spans` are [start, end) of marker lines in `source` (the Will reader's own offsets).
-// Returns the first quoted span, {start, end, where}, or null when every span may stand.
-// `where` is `fence`, `raw-pre`, `raw-div`, `raw-table`, `raw-html` (any other raw HTML block) or `frontmatter`.
 export function quotedWillSpan(source, spans) {
 	const text = String(source ?? '');
 	const marks = Array.isArray(spans) ? spans : [];
@@ -703,8 +657,6 @@ function pairSpanMarkers(source, kind, markers = null) {
 	return { runs, strays };
 }
 
-// Copy carries an arrow only when both complete anchor words are selected. A partial selection removes just
-// its endpoint comments from the copied slice, including a comment clipped at the selection's boundary.
 export function sliceInkArrows(source, start = 0, end = String(source ?? '').length, markers = null) {
 	const text = String(source ?? '');
 	if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end > text.length) throw new RangeError('ink: invalid source slice');
@@ -728,8 +680,6 @@ export function sliceInkArrows(source, start = 0, end = String(source ?? '').len
 	return result + text.slice(at, end);
 }
 
-// The paste owns only its incoming markers: an orphan cannot adopt an existing document's endpoint, and a
-// complete pair with an occupied number gets a new number in both openers without rewriting its stroke bytes.
 export function prepareInkPaste(source, existing = '', markers = null) {
 	const text = String(source ?? ''), paired = pairInkMarkers(text, markers), edits = [];
 	for (const marker of paired.strays) if (marker.mark?.id != null || marker.arrowId != null) edits.push({ start: marker.start, end: marker.end, text: '' });
@@ -767,7 +717,6 @@ export function hasInkMarker(text) {
 	return scanInkMarkers(text).length > 0;
 }
 
-// The only spelling.
 export function formatPageBreak() {
 	return PAGE_BREAK_MARKER;
 }

package/dist/spec/md-source.mjs

@@ -1,9 +1,6 @@
 // SPDX-License-Identifier: MIT
 import {splitOpeningFrontmatter} from './frontmatter.mjs';
 
-// The standard parser owns literal regions and comment boundaries. Offsets are original UTF-16,
-// including BOM/CRLF and list/quote prefixes. A private parser view observes rules; it changes no
-// live rule or token. Call once per source, then ask isText(position) or isComment(start, end).
 export function markdownSourcePositions(source, parser) {
   if (typeof source !== 'string' || !parser) throw new TypeError('Source positions require text and its Markdown parser');
   const {body, bodyOffset} = splitOpeningFrontmatter(source), lines = [bodyOffset];
@@ -17,8 +14,6 @@ export function markdownSourcePositions(source, parser) {
   ruler.getRules = chain => parser.inline.ruler.getRules(chain).map(rule => (state, silent) => {
     const start = state.pos, first = state.tokens.length;
     const matched = rule(state, silent), token = state.tokens.at(-1);
-    // A pending text token may flush before this token. Never overwrite a nested rule's span
-    // with its enclosing link's range.
     if (matched && !silent && state.tokens.length > first && !observed.has(token) &&
         ['code_inline', 'html_inline', 'image', 'footnote_ref'].includes(token?.type)) {
       observed.set(token, {start, end: state.pos, source: state.src,
@@ -28,8 +23,6 @@ export function markdownSourcePositions(source, parser) {
     }
     return matched;
   });
-  // A core rule may rewrite an inline token's content after its children were parsed (a task item drops
-  // its `[ ] `). Map rows from the text the inline rules read.
   const read = new WeakMap();
   inline.parse = function (text, md, env, children) { read.set(children, text); return parser.inline.parse.call(this, text, md, env, children); };
   const {tokens, cells} = markdownTableSources(body, owner, {}, lines);
@@ -37,8 +30,6 @@ export function markdownSourcePositions(source, parser) {
     for (const child of children || []) {
       const span = observed.get(child);
       if (!span || span.source !== content) continue;
-      // Inline footnotes are moved to a generated footer without line maps. Their parser-owned
-      // child tokens still stand inside the original ^[...] carrier, not in that footer.
       if (span.footnote?.tokens) {
         readInline(span.footnote.tokens, span.footnote.content, pos => rawOffset(span.start + 2 + pos));
       } else if (child.type !== 'footnote_ref') {
@@ -58,9 +49,6 @@ export function markdownSourcePositions(source, parser) {
     if (token.map && ['fence', 'code_block', 'html_block', 'reference_definition'].includes(token.type)) {
       const start = lineAt(token.map[0]), end = lineAt(token.map[1]);
       add(start, end);
-      // A comment-carrier block can contain several adjacent comments. Keep each carrier,
-      // including a closer surviving damage to its opener. Never promote nested comments or
-      // comment-shaped text in a raw tagged HTML block (pre, script, div, ...).
       if (token.type === 'html_block' && /^\s*<!--/.test(token.content)) {
         let at = source.indexOf('<!--', start);
         while (at >= start && at < end) {
@@ -81,8 +69,6 @@ export function markdownSourcePositions(source, parser) {
       for (let i = 0; i < rows.length; i++) {
         const start = lineAt(token.map[0] + i), end = lineAt(token.map[0] + i + 1), line = source.slice(start, end).replace(/\0/g, '\ufffd');
         let at = line.indexOf(rows[i]), lead = 0;
-        // A container that consumes part of a tab leaves the rest as spaces the source does not hold.
-        // They all stand for that tab.
         if (at < 0) { const rest = rows[i].replace(/^ +/, ''); lead = rows[i].length - rest.length; at = line.indexOf(rest); if (!lead || line[at - 1] !== '\t') at = -1; }
         if (at < 0) throw new Error('Markdown inline source mapping failed');
         starts.push(local); spaces.push(lead); offsets.push(start + at - lead); local += rows[i].length + 1;
@@ -113,8 +99,6 @@ export function markdownSourcePositions(source, parser) {
   return {isText, isComment: (start, end) => comments.get(start) === end, typography: typography.sort((a, b) => a.start - b.start)};
 }
 
-// Capture only table-cell provenance while the parser still owns container-adjusted row
-// bounds. Looking for cell text in a whole row aliases literal pipes and quote/list markers.
 export function markdownTableSources(source, parser, environment, lineStarts = null, parse = null) {
   const cells = new WeakMap();
   const read = owner => {

package/dist/spec/word-sidecar.mjs

@@ -1,6 +1,4 @@
 // SPDX-License-Identifier: MIT
-// An inert document asset, kept in Source and excluded from the reading surface.
-// This is recognition only: interchange/docx.mjs admits the bounded JSON and native XML.
 export const WORD_SIDECAR_OPEN = '<!-- rapier-word:v1\n';
 export function isWordSidecarBlock(raw) {
   return typeof raw === 'string' && /^<!-- rapier-word:v1\r?\n[^\r\n]*\r?\n-->[ \t\r\n]*$/.test(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rapier-markdown-kit",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "Read, render and write Self-contained Markdown: one .md file that carries its pictures, drawings and layout, and that any Markdown app can read. HTML renderer, stylesheet, text layout, Will/1 agent permissions, and an edit history with authorship and offline merge. MIT, no dependencies.",
   "keywords": [
     "markdown",

package/style.css

@@ -6,6 +6,7 @@
 /* The reference scale's unit (docs/markdown-standard.md, "The reference scale"): 16 px at M, a length every reader can read
    back as pixels (a planner scales its own lengths by it). */
 @property --md-unit{syntax:'<length>';inherits:true;initial-value:16px}
+@property --md-item-line{syntax:'<length>';inherits:true;initial-value:0px}
 :root,.md-render{
 	--md-unit:1rem;
 	--md-hair:calc(var(--md-unit) / 16);
@@ -362,21 +363,28 @@
 	position:relative;
 	--md-marker:0px;
 	counter-increment:rapier-ol;
-	min-height:0;
-	padding-top:0;
+	/* The circle's size follows the item's own line (--md-item-line is registered, so 1lh resolves here on the li,
+	   not in the marker's font): 2 units from the house line of 1.75 units up, never taller than the line at 1.48 units
+	   or less, growing in between. The li makes room for it: at the house line exactly 0.15 units above
+	   and 2 units' height, none once the circle fits the line. */
+	--md-item-line:1lh;
+	--md-ol-circle:min(2 * var(--md-unit), max(var(--md-item-line), 2 * var(--md-item-line) - 1.48 * var(--md-unit)));
+	--md-ol-top:calc(min(0.15 * var(--md-unit), 0.6 * max(0px, var(--md-ol-circle) - var(--md-item-line))) - min(0.125 * var(--md-unit), max(0px, var(--md-ol-circle) - var(--md-item-line)) / 2) + max(0px, var(--md-item-line) - var(--md-ol-circle)) / 2);
+	min-height:var(--md-ol-circle);
+	padding-top:min(0.15 * var(--md-unit), 0.6 * max(0px, var(--md-ol-circle) - var(--md-item-line)));
 }
 .md-render ol>li::before{
 	content:counter(rapier-ol);
 	position:absolute;
-	/* The circle is centered on the item's first line: the li's own padding, plus half of what the 2rem circle is taller than one line. */
-	inset-inline-start:calc(-2.75 * var(--md-unit) + var(--md-marker, 0px)); top:0;
-	width:min(2 * var(--md-unit), 1lh); height:min(2 * var(--md-unit), 1lh);
+	/* Centered on the item's first line and on the dotted line's axis, 1.75 units before the item's text. */
+	inset-inline-start:calc(-1.75 * var(--md-unit) - var(--md-ol-circle) / 2 + var(--md-marker, 0px)); top:var(--md-ol-top);
+	width:var(--md-ol-circle); height:var(--md-ol-circle);
 	display:flex; align-items:center; justify-content:center;
 	border:2px solid var(--md-color-line);
 	border-radius:999px;
 	background:var(--md-color-bg);
 	color:var(--md-color-line);
-	font:var(--md-fw-semibold) calc(0.95 * var(--md-unit))/1 var(--md-font-sans);
+	font:var(--md-fw-semibold) min(0.95 * var(--md-unit), 0.55 * var(--md-ol-circle))/1 var(--md-font-sans);
 	font-variant-numeric:tabular-nums;
 	box-sizing:border-box;
 	z-index:1;
@@ -387,8 +395,10 @@
 	position:absolute;
 
 	inset-inline-start:calc(calc(-1.75 * var(--md-unit)) - 1.5px + var(--md-marker, 0px));
-	top:calc(2.2 * var(--md-unit));
-	bottom:calc(var(--md-line) / -4);
+	/* From just below this circle into the next one: at least to the next item's top (--md-item-gap is the gap between
+	   items the spacing settings give), and at least a quarter line, which the next circle covers. */
+	top:calc(var(--md-ol-top) + 1.0875 * var(--md-ol-circle));
+	bottom:calc(-1 * max(var(--md-item-gap, 0px), var(--md-line) / 4));
 	border-inline-start:3px dotted var(--md-color-line);
 	z-index:0;
 }
@@ -426,37 +436,43 @@
 .md-render .rapier-jump-label strong{font:inherit}
 .md-render ul.rapier-jump-list{
 	--md-jump-gap:calc(.9 * var(--md-unit));
+	--md-jump-pad:calc(.18 * var(--md-unit));
+	--md-jump-circle:10px;
 	--md-jump-marker-inline-start:calc(-1.18 * var(--md-unit));
-	--md-jump-marker-center:1em;
 	list-style:none;
 	padding-inline-start:calc(1.85 * var(--md-unit));
 	margin:0 0 var(--md-gap-block);
 }
 .md-render ul.rapier-jump-list>li{
 	position:relative;
+	/* The circle sits on the first line's center: --md-item-line is registered, so 1lh resolves here on the li. */
+	--md-item-line:1lh;
+	--md-jump-circle-top:calc(var(--md-jump-pad) + (var(--md-item-line) - var(--md-jump-circle)) / 2);
 	margin:0 0 var(--md-jump-gap);
-	padding:calc(.18 * var(--md-unit)) 0 calc(.18 * var(--md-unit)) calc(.15 * var(--md-unit));
+	padding:var(--md-jump-pad) 0 var(--md-jump-pad) calc(.15 * var(--md-unit));
 }
 .md-render ul.rapier-jump-list>li:last-child{margin-bottom:0}
 .md-render ul.rapier-jump-list>li::before{
 	content:'';
 	position:absolute;
 	inset-inline-start:var(--md-jump-marker-inline-start);
-	top:calc(var(--md-jump-marker-center) - 5px);
-	width:10px;height:10px;
+	top:var(--md-jump-circle-top);
+	width:var(--md-jump-circle);height:var(--md-jump-circle);
 	box-sizing:border-box;
 	border:2px solid var(--md-color-accent-text);
 	background:var(--md-color-bg);
 	border-radius:50%;
 	z-index:1;
 }
+/* The dotted line is a numbered list's (3px, the text's black or white): from below this circle to the next circle's
+   center, which covers its end; none after the last item. --md-item-gap is the gap the spacing settings give. */
 .md-render ul.rapier-jump-list>li:not(:last-child)::after{
 	content:'';
 	position:absolute;
-	inset-inline-start:calc(var(--md-jump-marker-inline-start) + 4px);
-	top:var(--md-jump-marker-center);
-	bottom:calc(0px - var(--md-jump-gap) - var(--md-jump-marker-center));
-	border-inline-start:2px dotted color-mix(in srgb,var(--md-color-accent-text) 42%,transparent);
+	inset-inline-start:calc(var(--md-jump-marker-inline-start) + var(--md-jump-circle) / 2 - 1.5px);
+	top:calc(var(--md-jump-circle-top) + var(--md-jump-circle));
+	bottom:calc(-1 * (var(--md-item-gap, var(--md-jump-gap)) + var(--md-jump-circle-top) + var(--md-jump-circle) / 2));
+	border-inline-start:3px dotted var(--md-color-line);
 	z-index:0;
 }
 .md-render ul.rapier-jump-list>li>a{