reladraw 0.23.1 → 0.25.0

package/dist/ast.js

@@ -462,10 +462,10 @@ export const PADDING_SIDE_KEYS = PADDING_SIDES.map((side) => `padding-${side}`);
 /** `right-edge-order: ae, ad, ac`: the lines on one side of a box, in reading order. */
 export const EDGE_ORDER_KEYS = ['top-edge-order', 'bottom-edge-order', 'left-edge-order', 'right-edge-order'];
 export const ATTR_KEYS = {
-    shape: ['style', 'overlap', 'layout', 'gather-children', 'padding', ...PADDING_SIDE_KEYS, ...SIZE_KEY_NAMES, 'heading', 'join-with', 'badge', 'cards', 'shape', 'fill', 'border', 'corners', 'text', 'url', 'depth', ...EDGE_ORDER_KEYS],
-    icon: ['style', 'overlap', 'icon', 'join-with', 'text', 'url', 'depth', ...EDGE_ORDER_KEYS],
-    none: ['style', 'overlap', 'layout', 'gather-children', 'padding', ...SIZE_KEY_NAMES, 'heading', 'join-with', 'shape', 'text', 'url', 'depth', ...EDGE_ORDER_KEYS],
-    edge: ['style', 'from', 'to', 'via', 'from-mark', 'to-mark', 'line', 'text', 'url', 'depth'],
+    shape: ['style', 'overlap', 'layout', 'gather-children', 'padding', ...PADDING_SIDE_KEYS, ...SIZE_KEY_NAMES, 'heading', 'join-with', 'badge', 'cards', 'shape', 'fill', 'border', 'corners', 'text', 'url', 'description', 'depth', ...EDGE_ORDER_KEYS],
+    icon: ['style', 'overlap', 'icon', 'join-with', 'text', 'url', 'description', 'depth', ...EDGE_ORDER_KEYS],
+    none: ['style', 'overlap', 'layout', 'gather-children', 'padding', ...SIZE_KEY_NAMES, 'heading', 'join-with', 'shape', 'text', 'url', 'description', 'depth', ...EDGE_ORDER_KEYS],
+    edge: ['style', 'from', 'to', 'via', 'from-mark', 'to-mark', 'line', 'text', 'url', 'description', 'depth'],
 };
 /**
  * What a node's `corners:` takes, the default first: a box is drawn rounded
@@ -488,3 +488,11 @@ export const NODE_CORNERS = ['rounded', 'sharp'];
 export const ALL_ATTR_KEYS = [
     ...new Set([...Object.values(ATTR_KEYS).flat(), ...DIAGRAM_KEYS, ...REGION_KEYS]),
 ];
+/** Where `description: notes` keeps the name until `resolve` swaps in the text. */
+export const DESCRIPTION_NAME_KEY = 'description.name';
+/**
+ * Where a `url:` that names declared links keeps its list, declared names and
+ * quoted addresses in the order written, until `resolve` swaps each name for
+ * the links it declares.
+ */
+export const LINK_NAMES_KEY = 'url.names';

package/dist/cli.js

@@ -19,7 +19,7 @@ const USAGE = `reladraw — draw a diagram from stated placement
   reladraw format <input.reladraw>... [--check]
   reladraw format - [--check]
   reladraw format --init
-  reladraw install-skill [skills options]
+  reladraw install-skill [--claude] [--agents]
 
   render      draw the diagram to an SVG, and print any findings: places
               where the picture, drawn as written, may not read as meant.
@@ -37,9 +37,10 @@ const USAGE = `reladraw — draw a diagram from stated placement
               default with what it does.
   install-skill
               install the agent skill that came with this version of
-              reladraw, so it teaches what this tool accepts. It runs
-              npx skills add with --copy, and passes on what follows:
-              -g for every project, -a claude-code for one agent.
+              reladraw, so it teaches what this tool accepts, for every
+              project: --claude in ~/.claude/skills, --agents in
+              ~/.agents/skills (Codex and others), or both. With neither,
+              it asks.
 
   -o, --out   where render writes the SVG. Defaults to the input path with
               its extension replaced by .svg. Use - for standard output.
@@ -62,17 +63,113 @@ const USAGE = `reladraw — draw a diagram from stated placement
 const COMMANDS = ['render', 'check', 'format', 'install-skill'];
 // The version of skills this was tried with, so a change there can't break it.
 const SKILLS_PACKAGE = 'skills@1.7.6';
+// The two places the skill is installed, each picked by its flag. skills
+// knows a folder by an agent that reads it: ~/.agents/skills is its "codex",
+// and other agents read it too. Left to itself, skills installs for every
+// agent it knows of, more than fifty, so the agents are always named.
+const SKILL_TARGETS = [
+    { flag: '--claude', agent: 'claude-code', label: 'Claude Code', dir: '~/.claude/skills' },
+    { flag: '--agents', agent: 'codex', label: 'Codex and others', dir: '~/.agents/skills' },
+];
+function ownVersion() {
+    // package.json ships beside dist/, so the number is the installed one.
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
+// For any other agent, or a single project, skills is run by hand on this
+// install's skill, so it still matches this reladraw.
+function skillsCommand(skills, agent = '<agent>') {
+    const path = /\s/.test(skills) ? JSON.stringify(skills) : skills;
+    return `npx ${SKILLS_PACKAGE} add ${path} --copy -g -a ${agent}`;
+}
+const NAME_THE_TARGETS = SKILL_TARGETS.map((t) => `${t.flag} (${t.dir}, for ${t.label})`).join(', ') + ', or both';
+// In a terminal, a bare install-skill asks; otherwise, as when an agent runs
+// it, the flags must say, because there is no one to ask.
+async function askTargets(skills) {
+    const { createInterface } = await import('node:readline/promises');
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const closed = new Promise((done) => rl.once('close', () => done(undefined)));
+    const both = SKILL_TARGETS.length + 1;
+    process.stdout.write(`Install the reladraw ${ownVersion()} skill for which agents?\n` +
+        SKILL_TARGETS.map((t, i) => `  ${i + 1}  ${t.label.padEnd(17)} ${t.dir}\n`).join('') +
+        `  ${both}  both\n  ${both + 1}  another agent\n`);
+    try {
+        for (;;) {
+            const answer = await Promise.race([rl.question(`Choose [${both}]: `), closed]);
+            if (answer === undefined) {
+                process.stdout.write('\n');
+                return undefined;
+            }
+            const n = Number(answer.trim() || both);
+            if (n >= 1 && n <= SKILL_TARGETS.length)
+                return [SKILL_TARGETS[n - 1].agent];
+            if (n === both)
+                return SKILL_TARGETS.map((t) => t.agent);
+            if (n === both + 1)
+                return 'other';
+            process.stdout.write(`Type a number from 1 to ${both + 1}.\n`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
 // The skill ships in the package beside dist/, as the one in the repository.
-// skills does the work of knowing where each agent keeps its skills; --copy
-// because an npx run leaves the package in a cache, where a link would break.
-function installSkill(args) {
+// skills does the work of copying it in; --copy because an npx run leaves the
+// package in a cache, where a link would break.
+async function installSkill(args) {
     const skills = fileURLToPath(new URL('../.claude/skills/', import.meta.url));
     if (!existsSync(skills)) {
         process.stderr.write(`reladraw: the skill isn't in this install of reladraw (looked in ${skills})\n`);
         return 1;
     }
+    let agents = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const target = SKILL_TARGETS.find((t) => t.flag === arg);
+        if (target) {
+            if (!agents.includes(target.agent))
+                agents.push(target.agent);
+        }
+        else if (arg === '-g' || arg === '--global') {
+            // Always global now; skills from before 0.24 tell the user to write -g.
+        }
+        else if (arg === '-h' || arg === '--help') {
+            process.stdout.write(`reladraw install-skill [--claude] [--agents]\n\n` +
+                `Installs the skill that came with reladraw ${ownVersion()}, for every project:\n` +
+                SKILL_TARGETS.map((t) => `  ${t.flag.padEnd(9)} ${t.dir}, for ${t.label}\n`).join('') +
+                `With neither, it asks. For another agent, run:\n  ${skillsCommand(skills)}\n`);
+            return 0;
+        }
+        else if (arg === '-a' || arg === '--agent') {
+            const agent = args[i + 1];
+            process.stderr.write(`reladraw: install-skill takes ${NAME_THE_TARGETS}, not -a. ` +
+                `For ${agent ? `the agent ${agent}` : 'another agent'}, run:\n  ${skillsCommand(skills, agent)}\n`);
+            return 1;
+        }
+        else {
+            process.stderr.write(`reladraw: install-skill doesn't take ${arg}; it takes ${NAME_THE_TARGETS}. ` +
+                `For another agent, run:\n  ${skillsCommand(skills)}\n`);
+            return 1;
+        }
+    }
+    if (agents.length === 0) {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            process.stderr.write(`reladraw: say which agents to install the skill for: ${NAME_THE_TARGETS}. ` +
+                `For another agent, run:\n  ${skillsCommand(skills)}\n`);
+            return 1;
+        }
+        const picked = await askTargets(skills);
+        if (picked === undefined)
+            return 1;
+        if (picked === 'other') {
+            process.stdout.write(`For another agent, run this, with its name from skills' list:\n  ${skillsCommand(skills)}\n`);
+            return 0;
+        }
+        agents = picked;
+    }
     const windows = process.platform === 'win32';
-    const command = [SKILLS_PACKAGE, 'add', skills, '--copy', ...args];
+    // -y because the choice is already made; skills would otherwise ask again.
+    const command = [SKILLS_PACKAGE, 'add', skills, '--copy', '-g', '-y', '-a', ...agents];
     // On Windows npx is a .cmd, which Node runs only through a shell.
     const result = spawnSync(windows ? 'npx.cmd' : 'npx', windows ? command.map((a) => `"${a}"`) : command, {
         stdio: 'inherit',
@@ -85,7 +182,7 @@ function installSkill(args) {
     return result.status ?? 1;
 }
 async function main(argv) {
-    // Everything after install-skill is for skills, -h and -v included.
+    // install-skill reads its own flags, -h included.
     if (argv[0] === 'install-skill')
         return installSkill(argv.slice(1));
     if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
@@ -93,9 +190,7 @@ async function main(argv) {
         return argv.length === 0 ? 1 : 0;
     }
     if (argv.includes('-v') || argv.includes('--version')) {
-        // package.json ships beside dist/, so the number is the installed one.
-        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-        process.stdout.write(`${pkg.version}\n`);
+        process.stdout.write(`${ownVersion()}\n`);
         return 0;
     }
     const verb = argv[0];
@@ -420,7 +515,7 @@ function nearestSettings(folder, found) {
 // The exit code is set, not exited with: process.exit ends the process at
 // once, and a write to a pipe that hasn't drained yet is lost, which cut
 // `format -` and `render -o -` off at 64 KB. Node exits on its own once the
-// output is written. `./dev.sh pipe` checks it.
+// output is written.
 main(process.argv.slice(2)).then((code) => {
     process.exitCode = code;
 }, (error) => {

package/dist/constants.d.ts

@@ -72,6 +72,26 @@ export declare function arrowLength(thickness: number): number;
  * places that block in the room the node gave it.
  */
 export declare function widestLine(lines: Line[], measurer: Measurer, fontSize: number): number;
+/**
+ * How wide one line is. A line all at the text's own size is measured whole;
+ * a line with a marked run of another size is the runs side by side, each at
+ * its own size.
+ */
+export declare function lineWidth(line: Line, measurer: Measurer, fontSize: number): number;
+/**
+ * The largest size on a line: its own, or a marked run's. Only runs with
+ * something to draw count, so a plain space between two small marked words
+ * doesn't make their line a normal one.
+ */
+export declare function lineSize(line: Line, fontSize: number): number;
+/**
+ * How tall one line is: as tall as its largest text (design.org 7.1), so a
+ * line that is all small takes a small line's spacing and a line mixing sizes
+ * takes the largest's.
+ */
+export declare function lineTall(line: Line, measurer: Measurer, fontSize: number): number;
+/** How tall a block of lines is: each line as tall as its own largest text. */
+export declare function linesTall(lines: Line[], measurer: Measurer, fontSize: number): number;
 /**
  * An icon is two lines of the text tall, and that ratio is what makes it a
  * *text-sized* ornament rather than a picture with a size of its own. It is
@@ -93,7 +113,7 @@ export declare const DEFAULT_FONT_SIZE = 14;
  * `small` is sampled rather than chosen. In
  * `examples/reference/arch.png` the box and container texts run 25
  * pixels baseline to baseline and every annotation runs 21, which is this
- * ratio; `./dev.sh textrows` is how that was read off. `large` is the same step
+ * ratio. `large` is the same step
  * taken the other way, so the scale is symmetric about the document size.
  */
 export declare const TEXT_SIZES: Record<string, number>;

package/dist/constants.js

@@ -88,7 +88,40 @@ export function arrowLength(thickness) {
  * places that block in the room the node gave it.
  */
 export function widestLine(lines, measurer, fontSize) {
-    return lines.reduce((widest, line) => Math.max(widest, measurer.measure(plain(line), fontSize).width), 0);
+    return lines.reduce((widest, line) => Math.max(widest, lineWidth(line, measurer, fontSize)), 0);
+}
+/**
+ * How wide one line is. A line all at the text's own size is measured whole;
+ * a line with a marked run of another size is the runs side by side, each at
+ * its own size.
+ */
+export function lineWidth(line, measurer, fontSize) {
+    if (line.every((run) => run.size === undefined))
+        return measurer.measure(plain(line), fontSize).width;
+    return line.reduce((sum, run) => sum + measurer.measure(run.text, run.size ?? fontSize).width, 0);
+}
+/**
+ * The largest size on a line: its own, or a marked run's. Only runs with
+ * something to draw count, so a plain space between two small marked words
+ * doesn't make their line a normal one.
+ */
+export function lineSize(line, fontSize) {
+    const inked = line.filter((run) => run.text.trim().length > 0);
+    if (inked.length === 0)
+        return fontSize;
+    return Math.max(...inked.map((run) => run.size ?? fontSize));
+}
+/**
+ * How tall one line is: as tall as its largest text (design.org 7.1), so a
+ * line that is all small takes a small line's spacing and a line mixing sizes
+ * takes the largest's.
+ */
+export function lineTall(line, measurer, fontSize) {
+    return measurer.lineHeight(lineSize(line, fontSize));
+}
+/** How tall a block of lines is: each line as tall as its own largest text. */
+export function linesTall(lines, measurer, fontSize) {
+    return lines.reduce((sum, line) => sum + lineTall(line, measurer, fontSize), 0);
 }
 /**
  * An icon is two lines of the text tall, and that ratio is what makes it a
@@ -111,7 +144,7 @@ export const DEFAULT_FONT_SIZE = 14;
  * `small` is sampled rather than chosen. In
  * `examples/reference/arch.png` the box and container texts run 25
  * pixels baseline to baseline and every annotation runs 21, which is this
- * ratio; `./dev.sh textrows` is how that was read off. `large` is the same step
+ * ratio. `large` is the same step
  * taken the other way, so the scale is symmetric about the document size.
  */
 export const TEXT_SIZES = {

package/dist/format.js

@@ -164,8 +164,12 @@ function statementCells(all, keywordCount, starts, settings) {
     const result = [];
     const keyword = all.slice(0, keywordCount);
     result.push({ text: joinTokens(keyword), kind: 'keyword' });
-    const runs = clauseRuns(all.slice(keywordCount), starts);
+    let runs = clauseRuns(all.slice(keywordCount), starts);
     const head = runs[0] && !isAttrKey(runs[0][0].token) && !starts.has(runs[0][0].token) ? runs.shift() : undefined;
+    // A `url` declaration's links are one list, addresses and names alike, kept
+    // together after its name rather than spread over the columns of texts.
+    if (all[0].token.text === 'url' && runs.length > 1)
+        runs = [runs.flat()];
     if (head) {
         if (all[0].token.text === 'edge' && settings['edge-name-and-ends'] === 'own-columns')
             result.push(...edgeHeadCells(head));

package/dist/grammar.d.ts

@@ -64,7 +64,7 @@ export interface Span {
  * it. A word missing here is a word that draws in the plain color, which is a
  * dull page rather than a wrong one.
  */
-export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default", "icon", "point", "region", "bundle", "guide"];
+export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default", "icon", "description", "url", "point", "region", "bundle", "guide"];
 /**
  * Every word that says something about where a thing goes. Assembled from the
  * lists the parser itself reads, so a direction or a passage axis added there

package/dist/grammar.js

@@ -33,9 +33,9 @@ import { DEFAULT_TARGETS, DIRECTIONS, MARKS, PARTS, POINT_TEXT_SIDES, POSITIONS,
  * it. A word missing here is a word that draws in the plain color, which is a
  * dull page rather than a wrong one.
  */
-export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default', 'icon', 'point', 'region', 'bundle', 'guide'];
+export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default', 'icon', 'description', 'url', 'point', 'region', 'bundle', 'guide'];
 /** Statements whose second word declares a name. `diagram` has none. */
-const DECLARES_NAME = ['node', 'style', 'icon', 'point', 'region', 'bundle'];
+const DECLARES_NAME = ['node', 'style', 'icon', 'point', 'region', 'bundle', 'url'];
 /**
  * Keywords that take another after them: `guide region channel`, `default
  * leaf`, `default guide edge`. The words that may follow are the kinds a
@@ -233,7 +233,20 @@ export function highlightLine(line) {
                     push('keyword', at + next.length);
                     keyword = next;
                 }
-                if (DECLARES_NAME.includes(keyword)) {
+                if (keyword === 'description') {
+                    // `description notes """…"""` declares a name; `description for a, b`
+                    // names things declared elsewhere, so `for` colors as a keyword.
+                    const space = match(SPACE, line, at);
+                    if (space !== null) {
+                        push('plain', at + space.length);
+                        const word = match(WORD, line, at);
+                        if (word === 'for')
+                            push('keyword', at + word.length);
+                        else if (word !== null && !word.endsWith(':'))
+                            push('name', at + word.length);
+                    }
+                }
+                else if (DECLARES_NAME.includes(keyword)) {
                     const space = match(SPACE, line, at);
                     if (space !== null) {
                         push('plain', at + space.length);

package/dist/linetexts.d.ts

@@ -32,7 +32,10 @@ export interface PlacedText {
         maxX: number;
         maxY: number;
     };
-    /** Moved off its line by `right of edge` and the rest, rather than sitting on it. */
+    /**
+     * Moved off its line by `right of edge` and the rest, rather than sitting on it,
+     * and meant to be clear of it: not a stated distance or part of the way clear.
+     */
     beside: boolean;
 }
 /**

package/dist/linetexts.js

@@ -335,9 +335,18 @@ export function placeLineTexts(edge, route) {
             const out = { above: [0, -1], below: [0, 1], 'left of': [-1, 0], 'right of': [1, 0] }[place.by.side];
             center = { x: spot.x + (out[0] * size.width) / 2, y: spot.y + (out[1] * size.height) / 2 };
         }
-        if (place.beside) {
+        if (place.beside && place.rise?.distance !== undefined) {
+            // `2 above edge`: that far from its spot on the line, the stated way, whatever the line does.
+            const by = gapPixels(place.rise.distance, `${subject}: the text "${text.text}" ${place.rise.written}`, edge.line);
+            const out = { above: [0, -1], below: [0, 1], 'left of': [-1, 0], 'right of': [1, 0] }[place.beside];
+            center = { x: center.x + out[0] * by, y: center.y + out[1] * by };
+        }
+        else if (place.beside) {
             const gap = place.edgeGap === undefined ? TEXT_GAP : gapPixels(place.edgeGap, `${subject}: the text "${text.text}" edge-gap`, edge.line);
-            center = besideLine(whole, s, center, size, place.beside, gap);
+            const clear = besideLine(whole, s, center, size, place.beside, gap);
+            // `1/2 clear above edge`: that fraction of the move that clears it.
+            const fraction = place.rise?.clear ?? 1;
+            center = { x: center.x + (clear.x - center.x) * fraction, y: center.y + (clear.y - center.y) * fraction };
         }
         const pad = patchPadding(text, subject, edge.line);
         const knockout = turned(text.width + pad.x * 2, text.height + pad.y * 2, angle);
@@ -359,7 +368,8 @@ export function placeLineTexts(edge, route) {
                 maxX: center.x + knockout.width / 2,
                 maxY: center.y + knockout.height / 2,
             },
-            beside: place.beside !== undefined,
+            // A stated distance, or less than the whole way clear, may leave it across its line on purpose.
+            beside: place.beside !== undefined && place.rise?.distance === undefined && (place.rise?.clear ?? 1) >= 1,
         };
     });
 }

package/dist/links.d.ts

@@ -21,6 +21,10 @@ export interface Link {
     name?: string;
     icon?: LinkIcon;
 }
+/** One item in a `url:` list or a `url` declaration: an address with its bracket, or a declared link's name. */
+export type LinkEntry = Link | {
+    ref: string;
+};
 /** Every link a thing carries, in the order the source writes them. */
 export declare function linksOf(attrs: Attrs): Link[] | undefined;
 /**

package/dist/markdown.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The Markdown a description is written in: paragraphs, lists (`-`, `*` or
+ * `1.`), `**bold**`, `*italic*` or `_italic_`, `` `code` `` and
+ * `[text](address)`. Anything else is shown as the characters written.
+ *
+ * Two readings of one text: HTML for the page's panel, and plain text for an
+ * SVG's hover text, which can't show formatting.
+ */
+/** Every link address in a description that the page would refuse to follow. */
+export declare function unsafeLinks(text: string): string[];
+/** A description as HTML, for the page's panel. */
+export declare function markdownHtml(text: string): string;
+/** A description with its marks taken out, for an SVG's hover text. A link keeps its address after its text. */
+export declare function markdownPlain(text: string): string;

package/dist/markdown.js

@@ -0,0 +1,102 @@
+/**
+ * The Markdown a description is written in: paragraphs, lists (`-`, `*` or
+ * `1.`), `**bold**`, `*italic*` or `_italic_`, `` `code` `` and
+ * `[text](address)`. Anything else is shown as the characters written.
+ *
+ * Two readings of one text: HTML for the page's panel, and plain text for an
+ * SVG's hover text, which can't show formatting.
+ */
+const BULLET = /^\s*[-*]\s+(.*)$/;
+const NUMBERED = /^\s*\d+[.)]\s+(.*)$/;
+function blocksOf(text) {
+    const blocks = [];
+    let open;
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') {
+            open = undefined;
+            continue;
+        }
+        const bullet = line.match(BULLET);
+        const numbered = bullet ? null : line.match(NUMBERED);
+        const item = bullet ?? numbered;
+        if (item) {
+            const ordered = numbered !== null;
+            if (open?.kind !== 'list' || open.ordered !== ordered) {
+                open = { kind: 'list', ordered, items: [] };
+                blocks.push(open);
+            }
+            open.items.push(item[1].trim());
+        }
+        else if (open?.kind === 'list' && /^\s/.test(line)) {
+            // An indented line under an item continues it.
+            open.items[open.items.length - 1] += ` ${line.trim()}`;
+        }
+        else if (open?.kind === 'paragraph') {
+            open.lines.push(line.trim());
+        }
+        else {
+            open = { kind: 'paragraph', lines: [line.trim()] };
+            blocks.push(open);
+        }
+    }
+    return blocks;
+}
+const LINK = /\[([^\]]+)\]\(([^)\s]+)\)/g;
+/** The addresses a description may link to: the web, mail, or a path with no scheme. */
+const SAFE_ADDRESS = /^(https?:|mailto:|[^:]*$)/i;
+/** Every link address in a description that the page would refuse to follow. */
+export function unsafeLinks(text) {
+    return [...text.matchAll(LINK)].map((match) => match[2]).filter((href) => !SAFE_ADDRESS.test(href));
+}
+function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** One line's marks as HTML. Code is set aside first, so nothing inside it is read as a mark. */
+function inlineHtml(text) {
+    const codes = [];
+    let out = text.replace(/`([^`]+)`/g, (_, code) => {
+        codes.push(`<code>${escapeHtml(code)}</code>`);
+        return `\u0000${codes.length - 1}\u0000`;
+    });
+    const links = [];
+    out = out.replace(LINK, (_, label, href) => {
+        const safe = SAFE_ADDRESS.test(href) ? href : '#';
+        links.push(`<a href="${escapeHtml(safe)}" target="_blank" rel="noopener">${marks(escapeHtml(label))}</a>`);
+        return `\u0001${links.length - 1}\u0001`;
+    });
+    out = marks(escapeHtml(out));
+    return out
+        .replace(/\u0001(\d+)\u0001/g, (_, index) => links[Number(index)])
+        .replace(/\u0000(\d+)\u0000/g, (_, index) => codes[Number(index)]);
+}
+function marks(html) {
+    return html
+        .replace(/\*\*(?=\S)(.+?)(?<=\S)\*\*/g, '<strong>$1</strong>')
+        .replace(/(^|[^*\w])\*(?=\S)(.+?)(?<=\S)\*(?![*\w])/g, '$1<em>$2</em>')
+        .replace(/(^|[^_\w])_(?=\S)(.+?)(?<=\S)_(?![_\w])/g, '$1<em>$2</em>');
+}
+/** A description as HTML, for the page's panel. */
+export function markdownHtml(text) {
+    return blocksOf(text)
+        .map((block) => {
+        if (block.kind === 'paragraph')
+            return `<p>${block.lines.map(inlineHtml).join(' ')}</p>`;
+        const tag = block.ordered ? 'ol' : 'ul';
+        return `<${tag}>${block.items.map((item) => `<li>${inlineHtml(item)}</li>`).join('')}</${tag}>`;
+    })
+        .join('');
+}
+/** A description with its marks taken out, for an SVG's hover text. A link keeps its address after its text. */
+export function markdownPlain(text) {
+    const inline = (line) => line
+        .replace(LINK, (_, label, href) => `${label} (${href})`)
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\*\*(?=\S)(.+?)(?<=\S)\*\*/g, '$1')
+        .replace(/(^|[^*\w])\*(?=\S)(.+?)(?<=\S)\*(?![*\w])/g, '$1$2')
+        .replace(/(^|[^_\w])_(?=\S)(.+?)(?<=\S)_(?![_\w])/g, '$1$2');
+    return blocksOf(text)
+        .map((block) => block.kind === 'paragraph'
+        ? block.lines.map(inline).join(' ')
+        : block.items.map((item, index) => `${block.ordered ? `${index + 1}.` : '•'} ${inline(item)}`).join('\n'))
+        .join('\n\n');
+}

package/dist/model.d.ts

@@ -307,9 +307,10 @@ export interface Layout {
     roots: LayoutNode[];
     edges: LayoutEdge[];
     /**
-     * Every style the file's markup names, resolved to the color it lends. The
-     * renderer needs it because a marked run borrows its color from a style
-     * rather than stating one, and styles are otherwise merged away by here.
+     * Every style the file's markup names that lends a color, resolved to that
+     * color. The renderer needs it because a marked run borrows its color from a
+     * style rather than stating one, and styles are otherwise merged away by
+     * here. A size a style lends is carried on the run itself.
      */
     markup: Record<string, string>;
     /** The pictures links' badges name, by name, for the page that draws the badges. */

package/dist/page.js

@@ -2,6 +2,7 @@ import { fileChecks, findings } from './checks.js';
 import { SourceError } from './errors.js';
 import { blame, parse } from './parser.js';
 import { linkLabel, linksOf } from './links.js';
+import { markdownHtml } from './markdown.js';
 import { iconSvg, renderTagged, themeOf } from './render.js';
 import { resolve } from './resolve.js';
 import { luminance } from './themes.js';
@@ -38,6 +39,8 @@ export function drawPage(source, file, options = {}, at = new Date()) {
         throw error instanceof SourceError ? blame(source, error, run) : error;
     }
 }
+/** A description as the panel shows it: its Markdown as HTML, or nothing. */
+const describe = (attrs) => attrs['description'] === undefined ? {} : { description: markdownHtml(attrs['description']) };
 const BADGE_SIDE = 20;
 function graphOf(layout, theme) {
     const views = (links) => (links ?? []).map((link) => {
@@ -62,7 +65,7 @@ function graphOf(layout, theme) {
     const nodes = {};
     for (const node of layout.nodes) {
         const text = plainText(node.text);
-        nodes[node.name] = { label: text === '' ? node.name.split('.').pop() : text, links: views(linksFor(node)) };
+        nodes[node.name] = { label: text === '' ? node.name.split('.').pop() : text, links: views(linksFor(node)), ...describe(node.attrs) };
     }
     const edges = layout.edges.map((edge) => {
         // The upstream end is the one a line runs from: the end without a mark
@@ -71,7 +74,7 @@ function graphOf(layout, theme) {
         const backwards = start !== '' && end === '';
         const [up, down] = backwards ? [edge.to, edge.from] : [edge.from, edge.to];
         const text = edge.texts.map((one) => plainText(one.text)).filter((one) => one !== '').join(' · ');
-        return { up: up.name, down: down.name, label: text, links: views(linksOf(edge.attrs)) };
+        return { up: up.name, down: down.name, label: text, links: views(linksOf(edge.attrs)), ...describe(edge.attrs) };
     });
     return { nodes, edges };
 }
@@ -202,6 +205,11 @@ const PAGE = `<!doctype html>
   }
   #selected h3 svg { flex: none; }
   #selected .none { color: var(--muted); font-size: 13px; }
+  #selected .description { font-size: 13px; line-height: 1.45; overflow-wrap: anywhere; }
+  #selected .description p, #selected .description ul, #selected .description ol { margin: 0 0 8px; }
+  #selected .description ul, #selected .description ol { padding-left: 20px; }
+  #selected .description code { font-size: 12px; padding: 0 3px; border-radius: 3px; background: color-mix(in srgb, var(--ink) 12%, transparent); }
+  #selected .description a { color: inherit; text-decoration: underline; }
   #selected .link {
     display: flex; align-items: center; gap: 9px; padding: 4px 6px; margin: 0 -6px;
     border-radius: 5px; color: var(--ink); text-decoration: none;
@@ -689,11 +697,12 @@ const PAGE = `<!doctype html>
       selectedPanel.append(element('p', 'empty', 'Click a box or a line to see its links and what it connects to.'));
       return;
     }
-    var heading, links, from, to;
+    var heading, links, from, to, description;
     if (selection.kind === 'node') {
       var node = graph.nodes[selection.key];
       heading = node ? node.label : selection.key;
       links = node ? node.links : [];
+      description = node && node.description;
       from = []; to = [];
       graph.edges.forEach(function (edge) {
         if (edge.down === selection.key && from.indexOf(edge.up) < 0) from.push(edge.up);
@@ -704,6 +713,7 @@ const PAGE = `<!doctype html>
       var name = function (key) { return graph.nodes[key] ? graph.nodes[key].label : key; };
       heading = edge.label || name(edge.up) + ' \\u2192 ' + name(edge.down);
       links = edge.links;
+      description = edge.description;
       from = [edge.up]; to = [edge.down];
     }
     selectedPanel.append(element('h2', '', heading));
@@ -730,6 +740,14 @@ const PAGE = `<!doctype html>
     all.setAttribute('aria-pressed', String(everything));
     all.onclick = function () { everything = !everything; select(selection); };
     selectedPanel.append(all);
+    // Last, so a long description never pushes the rest out of view, and the
+    // sections above stay where they are whatever is selected.
+    if (description) {
+      // Written by reladraw from the file's Markdown, every character escaped.
+      var about = element('div', 'description');
+      about.innerHTML = description;
+      selectedPanel.append(element('h3', '', 'Description'), about);
+    }
   }
 
   // The pan and zoom capture the pointer, so the click lands on the view; what

package/dist/parser.d.ts

@@ -54,3 +54,10 @@ export declare function parse(source: string, seen?: (statement: Gathered) => vo
 export declare function blame(source: string, error: SourceError, run: (source: string) => unknown): SourceError;
 /** Whether a token is an arrow, or begins one: a bracketed mark, or a run of dashes with marks at its ends. */
 export declare function looksLikeArrow(token: Token): boolean;
+/**
+ * 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 declare function descriptionText(raw: string): string;