reladraw 0.24.0 → 0.25.1

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { BUNDLE_KEYS, COLOR_KEYS, POINT_KEYS, REGION_KEYS, WAYS, describePoint, fractionAxis, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, TEXT_KEYS, MARK_TEXT_KEYS, POINT_TEXT_SIDES, LINE_KEYS, LINE_VALUES, BORDER_KEYS, CONTENTS_KEYS, EDGE_ORDER_KEYS, LAYOUT_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
+import { BUNDLE_KEYS, DESCRIPTION_NAME_KEY, LINK_NAMES_KEY, COLOR_KEYS, POINT_KEYS, REGION_KEYS, WAYS, describePoint, fractionAxis, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, TEXT_KEYS, MARK_TEXT_KEYS, POINT_TEXT_SIDES, LINE_KEYS, LINE_VALUES, BORDER_KEYS, CONTENTS_KEYS, EDGE_ORDER_KEYS, LAYOUT_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { CHECK_DEFAULTS, CHECK_KINDS, setCheck } from './checks.js';
 import { SourceError } from './errors.js';
 import { STATEMENT_KEYWORDS } from './grammar.js';
@@ -175,14 +175,20 @@ function parseStatement(tokens, line) {
     }
     // What a line break inside a node's or an edge's text should mean has not
     // been decided, so until it is a `"""` string is refused anywhere but the one
-    // place it was made for, rather than drawn in some way that might change.
-    if (keyword.text !== 'icon' && tokens.some((token) => token.triple)) {
-        throw new SourceError('a """ string holds the SVG of an `icon` declaration and is not accepted anywhere else yet — ' +
+    // places it was made for, rather than drawn in some way that might change:
+    // an icon's SVG and a description's text.
+    const holdsTriple = keyword.text === 'icon' || keyword.text === 'description';
+    if (!holdsTriple && tokens.some((token, index) => token.triple && tokens[index - 1]?.text !== 'description:')) {
+        throw new SourceError('a """ string holds an `icon` declaration\'s SVG or a description\'s text, and is not accepted anywhere else yet — ' +
             'use ordinary quotes here', line);
     }
     switch (keyword.text) {
         case 'icon':
             return parseIcon(tokens, line);
+        case 'description':
+            return parseDescription(tokens, line);
+        case 'url':
+            return parseUrl(tokens, line);
         case 'node':
             return parseNode(tokens, line);
         case 'edge':
@@ -716,13 +722,36 @@ function readAttr(tokens, at, attrs, line, subject) {
         // its cards, each named in a bracket after it. The first stays under `url`,
         // so whatever follows one link follows the first of several; the whole
         // list is kept beside it only when there is more than a bare address.
+        // A declared link's name is kept with the list until `resolve` knows what
+        // it declares; `url` holds the first entry meanwhile, so a style's or a
+        // default's refusal of a destination sees one either way.
         const read = readLinks(tokens, at + 1, subject, line);
-        setOnce(attrs, key, read.links[0].href, subject, line, { key, value: quoteOf });
-        if (read.links.length > 1 || read.links.some((link) => link.name !== undefined || link.icon !== undefined)) {
+        const first = read.links[0];
+        setOnce(attrs, key, 'href' in first ? first.href : first.ref, subject, line, { key, value: quoteOf });
+        if (read.links.some((link) => 'ref' in link)) {
+            attrs[LINK_NAMES_KEY] = JSON.stringify(read.links);
+        }
+        else if (read.links.length > 1 || read.links.some((link) => 'href' in link && (link.name !== undefined || link.icon !== undefined))) {
             attrs[LINKS_KEY] = JSON.stringify(read.links);
         }
         return read.next;
     }
+    if (key === 'description') {
+        // Quoted, the text itself; unquoted, the name of a `description` statement,
+        // as `icon:` takes letters quoted and a picture's name bare.
+        const value = tokens[at + 1];
+        if (!value || isAttrKey(value) || value.text === '(' || value.text === ')') {
+            throw new SourceError(`${subject}: description: takes its text in quotes, \`description: "What this does"\`, or the name of a \`description\` statement`, line);
+        }
+        const had = attrs[DESCRIPTION_NAME_KEY] ?? attrs[key];
+        if (had !== undefined)
+            throw new SourceError(`${subject}: "description" is written twice — keep one`, line);
+        if (value.quoted)
+            attrs[key] = descriptionText(value.text);
+        else
+            attrs[DESCRIPTION_NAME_KEY] = value.text;
+        return at + 2;
+    }
     if (key === 'title') {
         // A title is a text, and every text is quoted. Unquoted, its first word
         // would be the title and the rest read as stray words.
@@ -1018,15 +1047,34 @@ function readEdgeTextBracket(tokens, start, subject, text, line) {
             continue;
         }
         // `2 above s1`: the distance from the box, written in front as a box writes it.
-        const distance = /^\d*\.?\d+$/.test(word) && /^(above|below|left|right)$/.test(plain(tokens[i + 1]) ?? '') ? word : undefined;
-        if (distance !== undefined) {
-            if (place.gap !== undefined)
-                throw new SourceError(`${about} says its distance from the box twice (gap: ${place.gap}, ${distance} in front) — keep one`, line);
-            place.gap = distance;
-            seen.add('gap');
+        // `2 above edge`: how far the text rises from its spot on the line.
+        // `clear above edge`, `1/2 clear above edge`: the rise that clears the line, or a fraction of it.
+        const isDirection = (token) => /^(above|below|left|right)$/.test(plain(token) ?? '');
+        const distance = /^\d*\.?\d+$/.test(word) && isDirection(tokens[i + 1]) ? word : undefined;
+        let clear;
+        if (word === 'clear' && isDirection(tokens[i + 1])) {
+            clear = { fraction: 1, written: 'clear' };
             i += 1;
         }
-        const said = distance === undefined ? word : plain(tokens[i]);
+        else if (plain(tokens[i + 1]) === 'clear' && isDirection(tokens[i + 2]) && fractionValue(word) !== undefined) {
+            const fraction = fractionValue(word);
+            if (fraction <= 0)
+                throw new SourceError(`${about}: "${word} clear" — say how much of the way clear, more than none, such as 1/2 clear`, line);
+            clear = { fraction, written: `${word} clear` };
+            i += 2;
+        }
+        else if (/^\d+\/\d+$/.test(word) && isDirection(tokens[i + 1])) {
+            const value = fractionValue(word);
+            const decimal = value === undefined ? word : String(Math.round(value * 1000) / 1000);
+            const way = plain(tokens[i + 1]);
+            const two = way === 'left' || way === 'right';
+            const onEdge = plain(tokens[i + (two ? 3 : 2)]) === 'edge';
+            throw new SourceError(`${about}: "${word} ${way}" — a distance is a number, \`${decimal} ${way}${two ? ' of' : ''}\`` +
+                (onEdge ? `; for part of the way clear of the line, write \`${word} clear ${way}${two ? ' of' : ''} edge\`` : ''), line);
+        }
+        if (distance !== undefined)
+            i += 1;
+        const said = distance === undefined && clear === undefined ? word : plain(tokens[i]);
         let relation;
         if (said === 'straight') {
             const way = plain(tokens[i + 1]);
@@ -1049,12 +1097,23 @@ function readEdgeTextBracket(tokens, start, subject, text, line) {
                 `${EDGE_TEXT_KEYS.join(':, ')}:, relations such as \`2 above s1\`, \`straight right from c\` or \`right of edge\`, \`x even with s1\`, and \`on the line\``, line);
         }
         const besideIt = relation !== 'straight' && plain(tokens[i]) === 'edge';
-        if (besideIt && distance !== undefined) {
-            throw new SourceError(`${about}: "${distance} ${relation} edge" — the distance off the line is written \`edge-gap: ${distance}\``, line);
+        if (clear !== undefined && !besideIt) {
+            throw new SourceError(`${about}: "${clear.written}" says how far off its own line a text moves, so it goes with \`${relation} edge\`` +
+                (relation === 'straight' ? '' : `, not a box — for a distance from the box, write it in front, \`2 ${relation} …\``), line);
+        }
+        if (distance !== undefined && !besideIt) {
+            if (place.gap !== undefined)
+                throw new SourceError(`${about} says its distance from the box twice (gap: ${place.gap}, ${distance} in front) — keep one`, line);
+            place.gap = distance;
+            seen.add('gap');
         }
         if (besideIt) {
             once('a side of the line', `${relation} edge`);
             place.beside = relation;
+            if (distance !== undefined)
+                place.rise = { distance, written: `${distance} ${relation} edge` };
+            if (clear !== undefined)
+                place.rise = { clear: clear.fraction, written: `${clear.written} ${relation} edge` };
             i += 1;
         }
         else {
@@ -1110,6 +1169,9 @@ function readEdgeTextBracket(tokens, start, subject, text, line) {
             throw new SourceError(`${about}: "${written}" and "${other.said}" both say where it sits ${placement.axis === 'x' ? 'across' : 'up and down'} — keep one`, line);
         }
     }
+    if (place.edgeGap !== undefined && place.rise?.distance !== undefined) {
+        throw new SourceError(`${about}: "${place.rise.written}" and "edge-gap: ${place.edgeGap}" both say how far off the line it sits — keep one`, line);
+    }
     if (place.edgeGap !== undefined && !place.beside) {
         throw new SourceError(`${about}: edge-gap: is the distance off the line for a text beside it, and it says no side — add \`right of edge\` or another`, line);
     }
@@ -1976,6 +2038,72 @@ function parseIcon(head, line) {
     }
     return { kind: 'icon', name, source: picture.text, pasted: picture.triple === true || picture.text.trim().startsWith('<'), line };
 }
+/**
+ * A description's text as written between `"""` marks, without the line break
+ * after the opening marks, the blank lines at either end, or the indentation
+ * every line shares, so a description indented under its statement reads as
+ * Markdown from the left margin.
+ */
+export function descriptionText(raw) {
+    const lines = raw.replace(/\r\n?/g, '\n').split('\n');
+    while (lines.length > 0 && lines[0].trim() === '')
+        lines.shift();
+    while (lines.length > 0 && lines[lines.length - 1].trim() === '')
+        lines.pop();
+    const indents = lines.filter((one) => one.trim() !== '').map((one) => one.match(/^[ \t]*/)[0].length);
+    const shared = indents.length === 0 ? 0 : Math.min(...indents);
+    return lines.map((one) => one.slice(shared).trimEnd()).join('\n');
+}
+/**
+ * `description for proxy, cache and api """…"""` or `description notes """…"""`.
+ * `for` keeps the two apart: without it a misspelled box name would silently
+ * declare a description nothing uses.
+ */
+function parseDescription(head, line) {
+    const textAt = head.findIndex((token, index) => index > 0 && token.quoted);
+    const textToken = textAt === -1 ? undefined : head[textAt];
+    const shape = 'write `description for proxy """…"""` to describe things already named, or `description notes """…"""` to declare one for `description: notes`';
+    if (head[1] === undefined)
+        throw new SourceError(`description needs a name or \`for\` — ${shape}`, line);
+    if (textToken === undefined) {
+        throw new SourceError('a description needs its text, between """ marks or in quotes, after what it names', line);
+    }
+    if (textAt + 1 < head.length) {
+        throw new SourceError(`a description ends with its text — "${head[textAt + 1].text}" is left over`, line);
+    }
+    const text = descriptionText(textToken.text);
+    if (text.trim() === '')
+        throw new SourceError('a description\'s text is empty', line);
+    if (follows(head, 1, 'for')) {
+        const targets = [];
+        for (let next = 2; next < textAt; next++) {
+            const token = head[next];
+            if (token.text === 'and' && targets.length > 0)
+                continue;
+            if (isAttrKey(token) || token.text === '(' || token.text === ')') {
+                throw new SourceError(`description for: expected the names of boxes or lines, found "${token.text}"`, line);
+            }
+            const name = token.text.replace(/,$/, '');
+            if (name === '')
+                continue;
+            if (targets.includes(name))
+                throw new SourceError(`description for: "${name}" is named twice — keep one`, line);
+            targets.push(name);
+        }
+        if (targets.length === 0)
+            throw new SourceError(`description for names nothing — ${shape}`, line);
+        return { kind: 'description', targets, text, line };
+    }
+    const name = requireName(head[1], 'description', line, head[2]);
+    if (textAt !== 2) {
+        throw new SourceError(`description "${name}" takes one name — to describe several things at once, write \`description for ${head
+            .slice(1, textAt)
+            .map((token) => token.text.replace(/,$/, ''))
+            .filter((one) => one !== 'and')
+            .join(', ')} """…"""\``, line);
+    }
+    return { kind: 'description', name, text, line };
+}
 /**
  * `diagram <attributes>` — no name, because a file holds one diagram. Unknown
  * keys are refused rather than ignored: a misspelt diagram-wide setting that
@@ -2069,6 +2197,9 @@ function defaultRefusal(kind, key) {
     const takes = `it takes ${DEFAULT_KEYS[kind].map((k) => `${k}:`).join(', ')}`;
     if (key === 'url')
         return `and a destination belongs to one thing rather than to every one of a kind`;
+    if (key === 'description') {
+        return 'and a description belongs to the things it describes — to give several one text, write `description for a, b and c """…"""`';
+    }
     if (key === 'heading') {
         return "and a heading names one node's own child, so it is written on that node";
     }
@@ -2163,18 +2294,20 @@ function readPlacement(tokens, at, line, subject, nested = false) {
             throw new SourceError(`${subject}: a distance is never negative — write \`${word.text.slice(1)} ${flipped}${/left|right/.test(flipped) ? ' of' : ''} …\`, ` +
                 'or inside or on for a box meant to overlap', line);
         }
-        // `3 below and 2 right of a`: a different distance on each axis.
-        const other = tokens[at + 3];
-        if (follows(tokens, at + 2, 'and') && other && !other.quoted && /^\d*\.?\d+(px)?$/.test(other.text) && tokens[at + 4] && isDirection(tokens[at + 4].text)) {
+        // `3 below and 2 right of a`: a different distance on each axis. The first
+        // half may keep its `of`, `2 right of and 3 below a`.
+        const of = follows(tokens, at + 2, 'of') && /left|right/.test(tokens[at + 1].text) ? 1 : 0;
+        const other = tokens[at + 3 + of];
+        if (follows(tokens, at + 2 + of, 'and') && other && !other.quoted && /^\d*\.?\d+(px)?$/.test(other.text) && tokens[at + 4 + of] && isDirection(tokens[at + 4 + of].text)) {
             const first = tokens[at + 1].text;
-            const second = tokens[at + 4].text;
+            const second = tokens[at + 4 + of].text;
             const vertical = (d) => d === 'above' || d === 'below';
             const horizontal = (d) => d === 'left' || d === 'right';
             if (!((vertical(first) && horizontal(second)) || (horizontal(first) && vertical(second)))) {
                 throw new SourceError(`${subject}: "${word.text} ${first} and ${other.text} ${second}" gives two distances, one for each axis, ` +
                     'so one direction is above or below and the other left or right', line);
             }
-            const read = readPlacement(tokens, at + 3, line, subject, true);
+            const read = readPlacement(tokens, at + 3 + of, line, subject, true);
             if (read.placement.kind !== 'offset')
                 return read;
             const y = vertical(first) ? first : second;
@@ -2509,10 +2642,12 @@ function checkColorWord(value, subject, line) {
         throw new SourceError(`${subject}: \`${value}\` is not a color — ${fix} \`#${value}\``, line);
     }
 }
-const URL_QUOTES = 'a url is written in quotes — `url: "https://example.com"`. Without them everything from the `//` onwards is read as a comment';
+const URL_QUOTES = 'a url is written in quotes — `url: "https://example.com"`. Without them everything from the `//` onwards is read as a comment. ' +
+    'An unquoted word is the name of a `url` statement';
 /**
- * `url: "https://a" (name: "A", icon: "A" (fill: red))  "https://b"`: one or
- * more quoted addresses, each with an optional bracket after it. The values in
+ * `url: "https://a" (name: "A", icon: "A" (fill: red))  "https://b"  docs`: one
+ * or more quoted addresses, each with an optional bracket after it, and the
+ * bare names of `url` statements, which take no bracket. The values in
  * a link's bracket are a name (a text, so quoted) and a badge, which is quoted
  * letters or the unquoted name of a picture. `readBracket` takes only unquoted
  * values and no bracket inside a bracket, so links are read here.
@@ -2522,25 +2657,87 @@ function readLinks(tokens, start, subject, line) {
     // `//` opens a comment — so the value is either missing entirely or is the
     // bare scheme, which reads as another attribute key. Neither report says
     // what is wrong, and the remedy is punctuation rather than a missing word.
-    if (!tokens[start]?.quoted)
+    if (!tokens[start] || !(tokens[start].quoted || isLinkName(tokens, start))) {
         throw new SourceError(`${subject}: ${URL_QUOTES}`, line);
+    }
     const links = [];
     let i = start;
-    while (tokens[i]?.quoted) {
-        const link = { href: tokens[i].text };
+    while (tokens[i]?.quoted || isLinkName(tokens, i)) {
+        const token = tokens[i];
         i += 1;
+        if (!token.quoted) {
+            // A declared link's name and badge belong to the destination, so the
+            // same link can't be shown one way on one box and another way on the next.
+            if (follows(tokens, i, '(')) {
+                throw new SourceError(`${subject}: the link "${token.text}" is declared with its own name and badge, so a bracket after it here is refused — ` +
+                    'to show it differently, declare another `url` with the bracket you want', line);
+            }
+            if (token.text.endsWith(',')) {
+                throw new SourceError(`${subject}: links are written one after another, without commas — \`url: ${token.text.slice(0, -1)} …\``, line);
+            }
+            if (links.some((had) => 'ref' in had && had.ref === token.text)) {
+                throw new SourceError(`${subject}: "${token.text}" is linked twice in one \`url:\` — keep one`, line);
+            }
+            links.push({ ref: token.text });
+            continue;
+        }
+        const link = { href: token.text };
         if (follows(tokens, i, '(')) {
             const read = readLinkBracket(tokens, i, link.href, subject, line);
             Object.assign(link, read.link);
             i = read.next;
         }
-        if (links.some((had) => had.href === link.href)) {
+        if (links.some((had) => 'href' in had && had.href === link.href)) {
             throw new SourceError(`${subject}: "${link.href}" is linked twice in one \`url:\` — keep one`, line);
         }
         links.push(link);
     }
     return { links, next: i };
 }
+/**
+ * A bare word in a list of links is a declared link's name, unless it opens a
+ * placement, which may follow a `url:` on the same statement. A `url`
+ * declaration refuses those words as names, so the two never meet.
+ */
+function isLinkName(tokens, at) {
+    const token = tokens[at];
+    if (!token || token.quoted || isAttrKey(token))
+        return false;
+    if (token.text === '(' || token.text === ')' || token.text === ',')
+        return false;
+    return !startsPlacement(token, tokens[at + 1]) && !PLACEMENT_LEADS.includes(token.text);
+}
+/** Words that open a clause after a statement's attributes without `startsPlacement` knowing them. */
+const PLACEMENT_LEADS = ['stays', 'and', 'x', 'y'];
+/**
+ * `url orders-docs "https://…" (name: "Docs", icon: "D")`, or a bundle:
+ * `url orders-links orders-docs orders-code "https://…" (name: "Wiki")`.
+ */
+function parseUrl(head, line) {
+    const shape = 'write `url orders-docs "https://…" (name: "Docs")`, then `url: orders-docs` on whatever links to it';
+    const nameToken = head[1];
+    if (nameToken === undefined || nameToken.quoted)
+        throw new SourceError(`url needs a name — ${shape}`, line);
+    if (isAttrKey(nameToken)) {
+        throw new SourceError(`\`url\` starts a statement that declares a link; to link this, \`${nameToken.text}\` goes on a box or a line as \`url:\` — ${shape}`, line);
+    }
+    const name = requireName(nameToken, 'url', line, head[2]);
+    if (startsPlacement(nameToken, head[2]) || PLACEMENT_LEADS.includes(name)) {
+        throw new SourceError(`url "${name}": "${name}" can't name a link, because after \`url:\` it would start a placement — choose another name`, line);
+    }
+    const subject = `url "${name}"`;
+    if (head[2] === undefined)
+        throw new SourceError(`${subject} links to nothing — ${shape}`, line);
+    // The links are one clause to the formatter, so a bundle's names stay
+    // together after its own name instead of lining up as part of it.
+    clauseStarts?.add(head[2]);
+    const read = readLinks(head, 2, subject, line);
+    const stray = head[read.next];
+    if (stray !== undefined) {
+        throw new SourceError(`${subject}: "${stray.text}" is not a link — a \`url\` statement holds quoted addresses, each with an optional bracket, and the names of other \`url\` statements`, line);
+    }
+    return { kind: 'url', name, entries: read.links, line };
+}
 function readLinkBracket(tokens, start, href, subject, line) {
     const link = {};
     const what = `the link "${href}"`;
@@ -2685,16 +2882,36 @@ function readTargets(tokens, start, subject, placement, line, partFirst = false)
         const read = readOneTarget(tokens, i, subject, line, partFirst);
         targets.push(read.target);
         i = read.next;
+        // `right of a and 2 above c top`: a distance and a direction after the
+        // joiner start the next placement, not a point as another target. A point
+        // meant as a target is named first (design.org 4.5).
         if (follows(tokens, i, 'and')) {
+            if (opensMeasuredPlacement(tokens, i + 1))
+                return { targets, next: i + 1 };
             i += 1;
             continue;
         }
+        if (read.listed && opensMeasuredPlacement(tokens, i))
+            return { targets, next: i };
         comma = read.listed ? nameTarget(read.target) : undefined;
         if (read.listed)
             continue;
         return { targets, next: i };
     }
 }
+/**
+ * Whether a placement written with its distance starts at `at`: `2 above c
+ * top`, or measured from this box's part, `center 2 above c center`.
+ */
+function opensMeasuredPlacement(tokens, at) {
+    const word = tokens[at];
+    if (!word || word.quoted)
+        return false;
+    if (isPart(word.text))
+        return opensPartPlacement(tokens, at);
+    const direction = tokens[at + 1];
+    return /^-?\d*\.?\d+(px)?$/.test(word.text) && direction !== undefined && !direction.quoted && isDirection(direction.text);
+}
 /**
  * One target: a name with its part and how far along, or a point written out
  * (design.org 4.2–4.4). `listed` says it ended on a comma, which promises

package/dist/place.js

@@ -770,12 +770,10 @@ export class Placer {
             // Bare, the direction would give way to the pins (`checkYielded`); it is
             // the distance written on it that they would overrule.
             const [direction] = directions;
-            const pins = statements
-                .filter((statement) => statement.kind === 'align')
-                .map((statement) => `"${describePlacement(statement.placement)}"`)
-                .join(' and ');
+            const aligns = statements.filter((statement) => statement.kind === 'align');
+            const pins = aligns.map((statement) => `"${describePlacement(statement.placement)}"`).join(' and ');
             return new SourceError(`"${node.name}" says how far away "${describePlacement(direction.placement)}" is, but ${pins} already ` +
-                `say where it goes ${AXIS_SAID[axis]} — drop the distance to keep only the direction, or drop the direction`, direction.placement.line);
+                `${aligns.length === 1 ? 'says' : 'say'} where it goes ${AXIS_SAID[axis]} — drop the distance to keep only the direction, or drop the direction`, direction.placement.line);
         }
         return new SourceError(`"${node.name}" says where it goes ${AXIS_SAID[axis]} more than once: ${said}. Each axis is stated ` +
             'once — keep one, or pin two opposite edges with even with to give it a size', statements[statements.length - 1].placement.line);

package/dist/render.js

@@ -1,4 +1,4 @@
-import { ARROW_LENGTH, ARROW_MARKER_WIDTH, DEFAULT_FONT_SIZE, ICON_LINES, LINE_WIDTH, PAD, arrowLength, fontSizeFor, textStyleFor, widestLine, } from './constants.js';
+import { ARROW_LENGTH, ARROW_MARKER_WIDTH, DEFAULT_FONT_SIZE, ICON_LINES, LINE_WIDTH, PAD, arrowLength, fontSizeFor, lineSize, lineTall, textStyleFor, widestLine, } from './constants.js';
 import { SourceError } from './errors.js';
 import { ICON_STROKE } from './icons.js';
 import { insideOutline, isBoxy, isRound, placePath, shapeOf, SUBPROCESS_INSET } from './outline.js';
@@ -9,6 +9,7 @@ import { crossingPoints, planLines, traceRoute, visibleRuns } from './lines.js';
 import { patchPadding, placeLineTexts } from './linetexts.js';
 import { plain } from './text.js';
 import { linkLabel, linksOf } from './links.js';
+import { markdownPlain } from './markdown.js';
 const CORNER = 8;
 /** Turn solved geometry into a standalone SVG document. */
 export function render(layout, options = {}) {
@@ -51,7 +52,7 @@ function drawing(layout, options) {
     const boxes = layout.roots.flatMap((root) => drawNode(root, theme, measurer, fontSize, layout.markup, guides));
     const marks = layout.marks.map((mark) => ({
         mark,
-        item: { key: mark.name, svg: markSvg(mark, theme, guides, layout.markup, fontSize), fills: markFills(mark, theme) },
+        item: { key: mark.name, svg: markSvg(mark, theme, guides, layout.markup, fontSize, measurer), fills: markFills(mark, theme) },
     }));
     const lines = [];
     // Everything the boxes cover. Edges are added to it as they are drawn.
@@ -113,7 +114,7 @@ function drawing(layout, options) {
     }
     const lineSvg = new Map(lines.map((line) => [line.key, line.svg]));
     const body = sequence
-        .map((item) => ({ item, svg: lineSvg.get(item.key) ?? item.svg }))
+        .map((item) => ({ item, svg: described(layout, item, lineSvg.get(item.key) ?? item.svg) }))
         .filter(({ svg }) => svg.length > 0);
     // An edge's geometry is measured rather than solved for, so the resolver sized
     // the canvas from the boxes alone. A curve out of a `top` side, or a text
@@ -183,6 +184,18 @@ export function themeOf(layout, options = {}) {
  * `<g data-name="api" data-line="12">` round each thing drawn: what a page
  * shows on hover, and what a finding about that line lights up.
  */
+/**
+ * A box or a line with a description carries it, marks stripped, as hover
+ * text. A `<title>` is the tooltip of the element it opens, so the drawing is
+ * wrapped in a group of its own; one without a description draws as before.
+ */
+function described(layout, item, svg) {
+    const attrs = item.node?.attrs ?? (item.key.startsWith('edge ') ? layout.edges[Number(item.key.slice('edge '.length))]?.attrs : undefined);
+    const text = attrs?.['description'];
+    if (text === undefined || svg.length === 0)
+        return svg;
+    return `  <g>\n  <title>${escapeXml(markdownPlain(text))}</title>\n${svg}\n  </g>`;
+}
 function tag(layout, item, svg) {
     let name;
     let line;
@@ -475,7 +488,7 @@ function nodeSvg(node, theme, measurer, fontSize, markup) {
         while (behind && behind.body.kind === 'none')
             behind = behind.parent;
         const onFill = behind ? textOnFill(behind.appearance['fill'] ?? '', theme) : undefined;
-        return [sized(textBlock(node.lines, node.x, node.y, textHeight, size, node.textBox, {
+        return [sized(textBlock(node.lines, node.x, node.y, measurer, size, node.textBox, {
                 color: textColorOf(node.textAttrs, theme, onFill ?? theme.text),
                 align: style.align,
                 ink,
@@ -491,7 +504,7 @@ function nodeSvg(node, theme, measurer, fontSize, markup) {
         const style = textStyleFor(node.textAttrs, node.line, 'middle', 'center');
         const drawn = [drawIcon(node.body.icon, node.x + (node.width - glyphSide) / 2, node.y, glyphSide, theme)];
         if (node.lines.some((line) => plain(line).length > 0)) {
-            drawn.push(sized(textBlock(node.lines, node.x, node.y, textHeight, size, node.textBox, {
+            drawn.push(sized(textBlock(node.lines, node.x, node.y, measurer, size, node.textBox, {
                 color: textColorOf(node.textAttrs, theme, theme.text),
                 align: style.align,
                 ink,
@@ -555,7 +568,7 @@ function nodeSvg(node, theme, measurer, fontSize, markup) {
     }
     const titled = node.banded && container;
     const textStyle = textStyleFor(node.textAttrs, node.line, titled ? 'start' : 'middle', titled ? 'top-left' : 'center');
-    parts.push(sized(textBlock(node.lines, node.x, node.y, textHeight, size, node.textBox, {
+    parts.push(sized(textBlock(node.lines, node.x, node.y, measurer, size, node.textBox, {
         color: text,
         align: textStyle.align,
         ink,
@@ -569,12 +582,12 @@ function nodeSvg(node, theme, measurer, fontSize, markup) {
  * primary color; a point is a dot. A guide is drawn only when guides are
  * shown, dashed and unfilled in the guide color.
  */
-function markSvg(mark, theme, guides, markup, fontSize) {
+function markSvg(mark, theme, guides, markup, fontSize, measurer) {
     const said = (key) => mark.appearance[key] ?? (mark.guide ? guides.looks[mark.kind][key] : undefined);
     if (mark.guide && !guides.shown)
         return '';
     const color = (value) => (value === undefined ? undefined : themeColor(value, theme));
-    const label = markTextSvg(mark, theme, mark.guide ? guides.color : theme.text, markup, fontSize);
+    const label = markTextSvg(mark, theme, mark.guide ? guides.color : theme.text, markup, fontSize, measurer);
     if (mark.kind === 'point') {
         const fill = color(said('fill')) ?? (mark.guide ? guides.color : theme.edge);
         return `  <circle cx="${round(mark.x)}" cy="${round(mark.y)}" r="3" fill="${fill}"/>${label}`;
@@ -637,12 +650,12 @@ function markFills(mark, theme) {
     return [{ x: mark.x, y: mark.y, width: mark.width, height: mark.height, ...fill }];
 }
 /** A point's or a region's text (design.org 7.4), on a line of its own after the mark. */
-function markTextSvg(mark, theme, fallback, markup, fontSize) {
+function markTextSvg(mark, theme, fallback, markup, fontSize, measurer) {
     const text = mark.text;
     if (!text)
         return '';
     const align = text.textAttrs['align'];
-    const block = textBlock(text.lines, 0, 0, text.lineHeight, text.size, text.box, {
+    const block = textBlock(text.lines, 0, 0, measurer, text.size, text.box, {
         color: textColorOf(text.textAttrs, theme, fallback),
         align: align === 'left' || align === 'top' ? 'start' : align === 'right' || align === 'bottom' ? 'end' : 'middle',
         ink: (run, own) => runInk(run, own, markup, theme),
@@ -908,7 +921,6 @@ function drawEdge(edge, route, theme, measurer, fontSize, markup) {
     const patches = [];
     for (const placed of placeLineTexts(edge, route)) {
         const { text, center, angle } = placed;
-        const lineHeight = measurer.lineHeight(text.size);
         const { width, height } = text;
         const top = center.y - height / 2;
         const turn = angle === 0 ? '' : ` transform="rotate(${round(angle)} ${round(center.x)} ${round(center.y)})"`;
@@ -923,7 +935,7 @@ function drawEdge(edge, route, theme, measurer, fontSize, markup) {
             center,
             ...(text.textAttrs['fill'] !== undefined ? { fill: text.textAttrs['fill'] } : {}),
         });
-        rest.push(...(turn ? ['  <g' + turn + '>'] : []), marker, sized(textBlock(text.lines, center.x - width / 2, top, lineHeight, text.size, { x: 0, y: 0, width, height }, {
+        rest.push(...(turn ? ['  <g' + turn + '>'] : []), marker, sized(textBlock(text.lines, center.x - width / 2, top, measurer, text.size, { x: 0, y: 0, width, height }, {
             // A colored edge carries its meaning into its text; an uncolored
             // one leaves the words to read as ordinary text.
             color: textColorOf(text.textAttrs, theme, lineOf(edge.appearance, theme, theme.text)),
@@ -1272,13 +1284,13 @@ function sized(block, size, fontSize) {
  * sized from it, so nearly all of them — the two coincide and `side` changes
  * nothing.
  */
-function textBlock(lines, x, y, lineHeight, fontSize, box, style) {
+function textBlock(lines, x, y, heights, fontSize, box, style) {
     if (style.reads === 'up' || style.reads === 'down') {
         // `box` is the turned ink, so the level block is the same box on its side.
         const cx = x + box.x + box.width / 2;
         const cy = y + box.y + box.height / 2;
         const level = { x: cx - box.height / 2, y: cy - box.width / 2, width: box.height, height: box.width };
-        const inner = textBlock(lines, 0, 0, lineHeight, fontSize, level, { ...style, reads: undefined });
+        const inner = textBlock(lines, 0, 0, heights, fontSize, level, { ...style, reads: undefined });
         return `  <g transform="rotate(${style.reads === 'up' ? -90 : 90} ${round(cx)} ${round(cy)})">\n${inner}\n  </g>`;
     }
     // `box` is the ink the text occupies, worked out by the resolver — the one
@@ -1291,26 +1303,38 @@ function textBlock(lines, x, y, lineHeight, fontSize, box, style) {
         : style.align === 'end'
             ? blockLeft + box.width
             : blockLeft;
+    // Each line is as tall as its largest text (design.org 7.1), so the lines are
+    // stacked by their own heights rather than at one spacing.
+    let lineTop = top;
     return lines
-        .map((line, index) => {
+        .map((line) => {
+        const tall = lineTall(line, heights, fontSize);
+        const largest = lineSize(line, fontSize);
+        const at = lineTop;
+        lineTop += tall;
         if (plain(line).length === 0)
             return '';
-        const baseline = top + index * lineHeight + lineHeight / 2 + fontSize * 0.35;
+        // The runs on a line share one baseline, set by the largest of them.
+        const baseline = at + tall / 2 + largest * 0.35;
         // One `<text>` per line, with a `<tspan>` per run inside it, so the runs
         // flow from the line's own anchor and a mark never moves a character.
-        // A line drawn in one color says so on the `<text>` and emits no spans at
-        // all, which is what keeps a whole quiet line identical to what the
-        // `subtext:` it replaced produced.
+        // A line drawn in one color and one size says so on the `<text>` and
+        // emits no spans at all, which is what keeps a whole quiet line identical
+        // to what the `subtext:` it replaced produced.
         const colors = line.map((run) => style.ink(run, style.color));
-        const uniform = colors.every((color) => color === colors[0]);
+        const sizes = line.map((run) => run.size);
+        const uniform = colors.every((color) => color === colors[0]) && sizes.every((size) => size === sizes[0]);
+        const sizeAttr = (size) => (size === undefined ? '' : ` font-size="${size}px"`);
         const body = uniform
             ? escapeXml(plain(line))
             : line
-                .map((run, run_index) => colors[run_index] === style.color
-                ? escapeXml(run.text)
-                : `<tspan fill="${colors[run_index]}">${escapeXml(run.text)}</tspan>`)
+                .map((run, run_index) => {
+                const fill = colors[run_index] === style.color ? '' : ` fill="${colors[run_index]}"`;
+                const sized = sizeAttr(run.size);
+                return fill || sized ? `<tspan${fill}${sized}>${escapeXml(run.text)}</tspan>` : escapeXml(run.text);
+            })
                 .join('');
-        return `  <text x="${round(anchorX)}" y="${round(baseline)}" fill="${uniform ? colors[0] ?? style.color : style.color}" text-anchor="${style.align}">${body}</text>`;
+        return `  <text x="${round(anchorX)}" y="${round(baseline)}" fill="${uniform ? colors[0] ?? style.color : style.color}"${uniform ? sizeAttr(sizes[0]) : ''} text-anchor="${style.align}">${body}</text>`;
     })
         .filter((element) => element.length > 0)
         .join('\n');
@@ -1320,12 +1344,12 @@ function textBlock(lines, x, y, lineHeight, fontSize, box, style) {
  * color, so the word borrows a meaning the file already has rather than
  * restating a value that goes stale the day the thing it means is recolored.
  * The resolver has already refused a mark naming a style that does not exist or
- * that says nothing about text.
+ * that gives text neither a color nor a size; a style that lends only a size
+ * leaves the run in the text's own color.
  */
 function runInk(run, own, markup, theme) {
-    if (run.style === undefined)
-        return own;
-    return themeColor(markup[run.style], theme);
+    const color = run.style === undefined ? undefined : markup[run.style];
+    return color === undefined ? own : themeColor(color, theme);
 }
 /**
  * A text's own color, the same words `fill:` and `border:` take — so