reladraw 0.1.0 → 0.3.0

package/dist/constants.js

@@ -1,13 +1,15 @@
+import { POSITIONS, isPosition } from './ast.js';
 import { SourceError } from './errors.js';
+import { plain } from './text.js';
 /** Inside a box, between its border and its contents. */
 export const PAD = 14;
 /** Between stacked children of one container. */
 export const CHILD_GAP = 10;
-/** Between a container's own label and its first child. */
+/** Between a container's own text and its first child. */
 export const HEADER_GAP = 10;
 /**
  * How far each deck copy is offset behind the front face. It has to clear a
- * whole line of text plus the padding above it, or a copy's label is drawn and
+ * whole line of text plus the padding above it, or a copy's text is drawn and
  * then immediately covered by the copy in front of it.
  */
 export const DECK_STEP = 34;
@@ -33,7 +35,7 @@ export const GAPS = {
  */
 export const SEPARATION_GAP = GAPS['tight'];
 /**
- * Between two links meeting the same side of the same box. An author names a
+ * Between two edges meeting the same side of the same box. An author names a
  * side, never a point on it, so this is the tool keeping two attachments apart
  * rather than a distance anyone asked for — small, like `SEPARATION_GAP`, and
  * squeezed further if the side is too short to hold the whole group.
@@ -41,7 +43,7 @@ export const SEPARATION_GAP = GAPS['tight'];
 export const ATTACH_STEP = 16;
 /** Kept clear at each end of a side, so an attachment never sits on a corner. */
 export const ATTACH_MARGIN = 10;
-/** How wide a link's line is drawn. */
+/** How wide an edge's line is drawn. */
 export const LINE_WIDTH = 1.6;
 /**
  * The arrowhead's length, in the `markerUnits="strokeWidth"` the marker is
@@ -55,48 +57,56 @@ export const ARROW_MARKER_WIDTH = 7;
  */
 export const ARROW_LENGTH = ARROW_MARKER_WIDTH * LINE_WIDTH;
 /**
- * Line left showing between a link's label and the box at that end of the
+ * Line left showing between an edge's text and the box at that end of the
  * corridor it crosses.
  *
  * Unlike `SEPARATION_GAP` and `ATTACH_MARGIN` this is not "small on purpose".
  * Those two keep two things from touching, and the least distance that reads as
- * "not touching" is the right one. This one has something to show: a label sits
+ * "not touching" is the right one. This one has something to show: a text sits
  * in a knockout that erases the line behind it, so whatever is left either side
- * is the entire evidence that the label belongs to a link at all. At ten pixels
+ * is the entire evidence that the text belongs to an edge at all. At ten pixels
  * it did not read as a line — the seed diagram in the playground drew as a word
  * with a dash beside it — so it is the length of a run of line, not a margin.
  *
  * Say `gap:` if you want the corridor wider than its contents.
  */
-export const LABEL_CLEARANCE = 20;
+export const TEXT_CLEARANCE = 20;
 /**
- * How much room a link's label takes along one axis.
+ * How much room an edge's text takes along one axis.
  *
- * The knockout rectangle drawn behind a label is the text plus five either side,
+ * The knockout rectangle drawn behind a text is the text plus five either side,
  * so that rectangle, not the glyphs, is what must not overlap anything.
  *
- * Shared by the resolver, which widens a corridor to hold a label, and the
+ * Shared by the resolver, which widens a corridor to hold a text, and the
  * renderer, which spaces the lanes of a channel by it, so the two cannot
- * disagree about how much room a label needs. The two ask different questions of
- * it and both are right: the resolver measures *along* the run, so a link
- * travelling horizontally needs the label's width; the renderer measures *across*
- * the channel, so a link travelling horizontally down one needs its height.
- */
-export function labelExtent(label, appearance, axis, measurer, fontSize, line) {
-    const size = fontSizeFor('link', appearance, fontSize, line);
-    const { width, lines } = measurer.measure(label, size);
+ * disagree about how much room a text needs. The two ask different questions of
+ * it and both are right: the resolver measures *along* the run, so an edge
+ * traveling horizontally needs the text's width; the renderer measures *across*
+ * the channel, so an edge traveling horizontally down one needs its height.
+ */
+export function textExtent(lines, textAttrs, axis, measurer, fontSize, line) {
+    const size = fontSizeFor('edge', textAttrs, fontSize, line);
+    const width = lines.reduce((widest, drawn) => Math.max(widest, measurer.measure(plain(drawn), size).width), 0);
     return axis === 'x' ? width + 10 : lines.length * measurer.lineHeight(size);
 }
 /**
- * An icon is two lines of the label tall, and that ratio is what makes it a
- * *label-sized* ornament rather than a picture with a size of its own. It is
+ * The widest of these lines, which is how wide the block of them is. Shared by
+ * the resolver, which sizes a node to hold its text, and the renderer, which
+ * 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);
+}
+/**
+ * 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
  * read off the reference, where the title lines run 25 pixels baseline to
  * baseline and the drive and machine glyphs are close to 50 tall. Deriving it
  * from the text also means an icon on a `size: small` node shrinks with it,
  * which is what anyone would expect and what a fixed pixel count would not do.
  */
 export const ICON_LINES = 2;
-/** Between the label column and the icon column beside it. */
+/** Between the text column and the icon column beside it. */
 export const ICON_GAP = 10;
 export const DEFAULT_FONT_SIZE = 14;
 /**
@@ -106,7 +116,7 @@ export const DEFAULT_FONT_SIZE = 14;
  * it says nothing about why one piece of text is smaller than another.
  *
  * `small` is sampled rather than chosen. In
- * `examples/reference/arch.png` the box and container labels run 25
+ * `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
  * taken the other way, so the scale is symmetric about the document size.
@@ -117,20 +127,21 @@ export const TEXT_SIZES = {
     large: 25 / 21,
 };
 /**
- * What each kind of text is set at when the file says nothing. A note annotates
- * the diagram rather than being part of it, and at the size of a box label an
- * aside reads as a statement — so `note` starts small and says so by being a
- * note. This is a default and not a ceiling: `size:` overrides it, the same way
- * `fill:` overrides the theme's colour.
+ * What each kind of text is set at when the file says nothing. A node with no
+ * body annotates the diagram rather than being part of it, and at the size of a
+ * box text an aside reads as a statement — so `shape: none` starts small and
+ * says so by having no body. This is a default and not a ceiling: `(size: …)`
+ * in the text's brackets overrides it, the same way `fill:` overrides the
+ * theme's color.
  */
-const DEFAULT_TEXT_SIZE = { note: 'small' };
+const DEFAULT_TEXT_SIZE = { none: 'small' };
 /**
  * The size a piece of text is set at. Shared by the resolver, which reserves
  * the room, and the renderer, which fills it, so the two cannot disagree about
  * how much room there is.
  */
-export function fontSizeFor(kind, appearance, fontSize, line) {
-    const named = appearance['size'] ?? DEFAULT_TEXT_SIZE[kind] ?? 'normal';
+export function fontSizeFor(kind, textAttrs, fontSize, line) {
+    const named = textAttrs['size'] ?? DEFAULT_TEXT_SIZE[kind] ?? 'normal';
     const scale = TEXT_SIZES[named];
     if (scale === undefined) {
         throw new SourceError(`size takes ${Object.keys(TEXT_SIZES).join(', ')}, not "${named}"`, line);
@@ -139,49 +150,53 @@ export function fontSizeFor(kind, appearance, fontSize, line) {
 }
 export const DEFAULT_MARGIN = 40;
 /**
- * Where a container's own label sits. Every container reserves a band for its
- * label and its icon; `at` says which end of the box that band is, and the
- * contents take what is left. `align` says how the text sits across it.
- *
- * The two are independent and neither implies the other. A label at the bottom
- * is an ordinary label that happens to be at the bottom — there is no kind of
- * label being named here and no second thing quietly coming along with the
- * first. An earlier version bundled them as `label: heading | caption`, which
- * read a position as though it were a meaning; a folded corner means "artifact
- * rather than process" and a reader decodes it, while "lower down" means only
- * lower down.
- *
- * A leaf has no band — its label is centred in the box — so neither says
- * anything about one.
+ * Author's word to the SVG's. One spelling of each, per the rule that refuses
+ * synonyms for `node` and `edge`: an alias is a variant a reader has to learn,
+ * and every document and example has to pick one of them anyway.
  */
-export const LABEL_ENDS = ['top', 'bottom'];
-/**
- * Author's word to the SVG's. Both spellings of the middle one are taken: this
- * is a vocabulary an author types from memory, and being right about the
- * arrangement and wrong about a dialect is not a mistake worth an error.
- */
-const LABEL_ALIGNMENTS = {
+const TEXT_ALIGNMENTS = {
     left: 'start',
-    centre: 'middle',
     center: 'middle',
     right: 'end',
 };
 /**
- * Read a label's bracketed modifiers. Shared by the resolver, which offsets the
+ * Read a text's bracketed modifiers. Shared by the resolver, which offsets the
  * contents away from the band, and the renderer, which draws into it, so the two
  * cannot disagree about which end the band is at.
  */
-export function labelStyleFor(label, line) {
-    const at = label['at'];
-    if (at !== undefined && !LABEL_ENDS.includes(at)) {
-        throw new SourceError(`a label's at takes ${LABEL_ENDS.join(' or ')}, not "${at}"`, line);
+export function textStyleFor(attrs, line, fallbackAlign = 'start', fallbackAt = 'top-left') {
+    const written = attrs['at'];
+    if (written !== undefined && !isPosition(written)) {
+        // A bare side word is the one mistake worth naming rather than only
+        // refusing: it was the whole vocabulary until 0.3.0, and the point at the
+        // middle of that side is exactly one word away.
+        const midpoint = `${written}-center`;
+        throw new SourceError(isPosition(midpoint)
+            ? `a text sits at a *point* of the box, and "${written}" names a side — write "${midpoint}" for the point at the middle of it`
+            : `a text's at takes one of ${POSITIONS.join(', ')}, not "${written}"`, line);
     }
-    const align = label['align'];
-    if (align !== undefined && LABEL_ALIGNMENTS[align] === undefined) {
-        throw new SourceError(`a label's align takes left, centre or right, not "${align}"`, line);
+    const at = written ?? fallbackAt;
+    const align = attrs['align'];
+    if (align !== undefined && TEXT_ALIGNMENTS[align] === undefined) {
+        throw new SourceError(`a text's align takes left, center or right, not "${align}"`, line);
     }
+    const parts = at.split('-');
     return {
-        at: at ?? 'top',
-        align: align === undefined ? 'start' : LABEL_ALIGNMENTS[align],
+        at,
+        end: parts.includes('top') ? 'top' : parts.includes('bottom') ? 'bottom' : 'center',
+        side: parts.includes('left') ? 'left' : parts.includes('right') ? 'right' : 'center',
+        align: align === undefined ? fallbackAlign : TEXT_ALIGNMENTS[align],
     };
 }
+/**
+ * Where a leaf's text or badge starts vertically, given which end it sits at.
+ * Shared, because the resolver works out the text's box and the renderer draws
+ * it, and the two must not be able to disagree.
+ */
+export function leafTop(end, y, height, own) {
+    if (end === 'top')
+        return y + PAD;
+    if (end === 'bottom')
+        return y + height - PAD - own;
+    return y + (height - own) / 2;
+}

package/dist/grammar.d.ts

@@ -1,10 +1,10 @@
 /**
  * The language's *lexical* vocabulary, and a scanner that classifies one line of
- * source into coloured spans.
+ * source into colored spans.
  *
  * This is deliberately separate from `parser.ts`, and it is not a second parser.
  * The parser answers "what does this file mean" and refuses anything it cannot
- * answer for; a highlighter has to colour a half-typed line without complaint,
+ * answer for; a highlighter has to color a half-typed line without complaint,
  * so it answers only "what kind of word is this" and never fails. Every rule
  * below is a regex applied to a single line, in priority order, with one bit of
  * carried state (whether anything has been seen on the line yet, and whether the
@@ -23,27 +23,29 @@
  * closes on one, and there are no blocks. That is the property those editor
  * formats need and the reason a `.reladraw` grammar is small in all of them.
  */
-/** What a span of source is, for colouring. */
+/** What a span of source is, for coloring. */
 export type TokenKind = 
 /** `// to the end of the line` */
 'comment'
 /** A quoted string, quotes included. Unterminated ones count, so typing is quiet. */
  | 'string'
-/** The word a statement opens with: `box`, `link`, … */
+/** A markup tag inside a text: `[dim]` and `[/dim]`. */
+ | 'markup'
+/** The word a statement opens with: `node`, `edge`, … */
  | 'keyword'
 /** The name a statement declares, right after its keyword. */
  | 'name'
 /** `->` and `<->`. */
  | 'arrow'
-/** Placement and link vocabulary: `right`, `of`, `level`, `with`, `and`, `between`, … */
+/** Placement and edge vocabulary: `right`, `of`, `level`, `with`, `and`, `between`, … */
  | 'relation'
 /** A `key:` opening an attribute or a bracketed modifier. */
  | 'attribute'
 /** The single word an attribute takes. */
  | 'value'
 /** `#14532d`, wherever it appears. */
- | 'colour'
-/** `(` and `)` around a placement's or a label's modifiers. */
+ | 'color'
+/** `(` and `)` around a placement's or a text's modifiers. */
  | 'bracket'
 /** Everything else: node names being referred to, and whitespace. */
  | 'plain';
@@ -56,14 +58,14 @@ export interface Span {
 /**
  * The words a statement may open with. `parseStatement` in `parser.ts` is the
  * authority — its switch is what actually accepts them — and this list mirrors
- * it. A word missing here is a word that draws in the plain colour, which is a
+ * 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 ["box", "note", "link", "deck", "style", "diagram"];
+export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "deck", "style", "diagram"];
 /**
  * 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
- * colours here without anybody remembering to come back.
+ * colors here without anybody remembering to come back.
  */
 export declare const RELATION_WORDS: string[];
 /**
@@ -80,9 +82,20 @@ export declare const PATTERNS: {
     readonly keyword: `(?:${string})\\b`;
     readonly arrow: "<->|->|<-";
     readonly attribute: "[A-Za-z][A-Za-z0-9_-]*:";
-    readonly colour: "#[0-9A-Fa-f]{3,8}\\b";
+    readonly color: "#[0-9A-Fa-f]{3,8}\\b";
     readonly relation: `(?:${string})\\b`;
     readonly bracket: "[()]";
+    /**
+     * A markup tag, which appears only inside a string. An editor grammar that
+     * scopes patterns should apply this one inside the string scope; the scanner
+     * below does the same thing by splitting a matched string span.
+     *
+     * The escape is `\[`, and this pattern deliberately does not exclude it —
+     * doing so needs a lookbehind, which several grammar formats lack, and a
+     * wrongly-colored escaped bracket is a much smaller wrong than a highlighter
+     * that cannot be ported.
+     */
+    readonly markup: "\\[\\/?[A-Za-z][A-Za-z0-9_-]*\\]";
     readonly word: "(?:[^\\s()\"\\/]|\\/(?!\\/))(?:[^\\s\"\\/]|\\/(?!\\/))*";
     /**
      * The same, inside an open bracket, where `)` closes the group instead of

package/dist/grammar.js

@@ -1,10 +1,10 @@
 /**
  * The language's *lexical* vocabulary, and a scanner that classifies one line of
- * source into coloured spans.
+ * source into colored spans.
  *
  * This is deliberately separate from `parser.ts`, and it is not a second parser.
  * The parser answers "what does this file mean" and refuses anything it cannot
- * answer for; a highlighter has to colour a half-typed line without complaint,
+ * answer for; a highlighter has to color a half-typed line without complaint,
  * so it answers only "what kind of word is this" and never fails. Every rule
  * below is a regex applied to a single line, in priority order, with one bit of
  * carried state (whether anything has been seen on the line yet, and whether the
@@ -23,28 +23,34 @@
  * closes on one, and there are no blocks. That is the property those editor
  * formats need and the reason a `.reladraw` grammar is small in all of them.
  */
-import { DIRECTIONS, EDGES, PASSAGE_AXES } from './ast.js';
+import { DIRECTIONS, POSITIONS, SIDES, PASSAGE_AXES } from './ast.js';
 /**
  * The words a statement may open with. `parseStatement` in `parser.ts` is the
  * authority — its switch is what actually accepts them — and this list mirrors
- * it. A word missing here is a word that draws in the plain colour, which is a
+ * 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 = ['box', 'note', 'link', 'deck', 'style', 'diagram'];
+export const STATEMENT_KEYWORDS = ['node', 'edge', 'deck', 'style', 'diagram'];
 /** Statements whose second word declares a name. `diagram` has none. */
-const DECLARES_NAME = ['box', 'note', 'deck', 'style'];
+const DECLARES_NAME = ['node', 'deck', 'style'];
 /**
  * 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
- * colours here without anybody remembering to come back.
+ * colors here without anybody remembering to come back.
  */
 export const RELATION_WORDS = [
     ...DIRECTIONS,
-    ...EDGES,
+    ...SIDES,
+    ...POSITIONS,
     ...Object.keys(PASSAGE_AXES),
     // The connecting words. `of` is optional after a direction, `and` joins
-    // targets, `between` opens a passage, `level with` is the alignment.
+    // targets, `between` opens a passage, `level with` is the alignment, and
+    // `on ... at ...` is the overlay. Note `of` and `at` are what tell the two
+    // position vocabularies apart: a direction is always followed by `of`, a
+    // named position always preceded by `at`.
     'of',
+    'at',
+    'on',
     'and',
     'level',
     'with',
@@ -72,9 +78,20 @@ export const PATTERNS = {
     // `<->` first, or `<-` would match its opening half and leave a stray `>`.
     arrow: '<->|->|<-',
     attribute: '[A-Za-z][A-Za-z0-9_-]*:',
-    colour: '#[0-9A-Fa-f]{3,8}\\b',
+    color: '#[0-9A-Fa-f]{3,8}\\b',
     relation: `(?:${alternation(RELATION_WORDS)})\\b`,
     bracket: '[()]',
+    /**
+     * A markup tag, which appears only inside a string. An editor grammar that
+     * scopes patterns should apply this one inside the string scope; the scanner
+     * below does the same thing by splitting a matched string span.
+     *
+     * The escape is `\[`, and this pattern deliberately does not exclude it —
+     * doing so needs a lookbehind, which several grammar formats lack, and a
+     * wrongly-colored escaped bracket is a much smaller wrong than a highlighter
+     * that cannot be ported.
+     */
+    markup: '\\[\\/?[A-Za-z][A-Za-z0-9_-]*\\]',
     // Matches what `tokenizeLine` treats as one bare token, and the awkwardness is
     // load-bearing rather than accidental. A `(` counts as punctuation only where
     // a token starts, so `rgb(20,20,20)` is one word — hence the first character
@@ -102,7 +119,7 @@ const RULES = [
     // Before `relation`, because the trailing colon is what tells `left: …` from
     // the `left` of a placement, and after `arrow` so `->` is never a word.
     { kind: 'attribute', re: sticky(PATTERNS.attribute) },
-    { kind: 'colour', re: sticky(PATTERNS.colour) },
+    { kind: 'color', re: sticky(PATTERNS.color) },
     { kind: 'relation', re: sticky(PATTERNS.relation) },
 ];
 const SPACE = sticky('[ \\t]+');
@@ -159,9 +176,9 @@ export function highlightLine(line) {
                     if (space !== null) {
                         push('plain', at + space.length);
                         const name = match(WORD, line, at);
-                        // `style backup  stroke: …` declares a name; `box  fill: red` is a
+                        // `style backup  border: …` declares a name; `node  fill: red` is a
                         // half-typed line whose second word is already an attribute, and
-                        // colouring that as a name would be a lie about what it is.
+                        // coloring that as a name would be a lie about what it is.
                         if (name !== null && !name.endsWith(':'))
                             push('name', at + name.length);
                     }
@@ -194,11 +211,20 @@ export function highlightLine(line) {
             // An attribute's value is whatever single token follows it, whatever it
             // would otherwise have been called: `to: right` is a value, not a
             // direction, and `style: wide` is a style name, not a gap.
-            const kind = expectingValue && rule.kind !== 'string' && rule.kind !== 'colour' && rule.kind !== 'bracket'
+            const kind = expectingValue && rule.kind !== 'string' && rule.kind !== 'color' && rule.kind !== 'bracket'
                 ? 'value'
                 : rule.kind;
             expectingValue = rule.kind === 'attribute';
-            push(kind, at + text.length);
+            // A string is the one span with something inside it: markup naming a
+            // style. The spans still cover the line exactly, which is what a
+            // highlighter drawn behind a textarea needs.
+            if (rule.kind === 'string') {
+                for (const part of splitMarkup(text, at))
+                    push(part.kind, part.end);
+            }
+            else {
+                push(kind, at + text.length);
+            }
             matched = true;
             break;
         }
@@ -209,6 +235,26 @@ export function highlightLine(line) {
     }
     return spans;
 }
+/**
+ * One string span cut into the plain stretches and the markup tags inside it.
+ * An escaped bracket is left to be colored as a tag when it looks like one,
+ * which is the wrong the pattern's doc comment accepts in exchange for being
+ * portable.
+ */
+function splitMarkup(text, from) {
+    const parts = [];
+    const tag = new RegExp(PATTERNS.markup, 'g');
+    let at = 0;
+    for (let found = tag.exec(text); found !== null; found = tag.exec(text)) {
+        if (found.index > at)
+            parts.push({ kind: 'string', end: from + found.index });
+        parts.push({ kind: 'markup', end: from + found.index + found[0].length });
+        at = found.index + found[0].length;
+    }
+    if (at < text.length || parts.length === 0)
+        parts.push({ kind: 'string', end: from + text.length });
+    return parts;
+}
 /** Every line of a source file, classified. Line endings are not included. */
 export function highlight(source) {
     return source.split(/\r?\n/).map(highlightLine);

package/dist/icons.d.ts

@@ -8,7 +8,7 @@
  * the SVG. Inline paths cost a few hundred bytes each and always arrive.
  *
  * A name here says what the thing *is*, never what the picture looks like. The
- * same discipline as `gap: wide` over `gap: 110` and `muted` over a hex value:
+ * same discipline as `muted` over a hex value:
  * the word is the whole interface, so it has to carry meaning rather than
  * geometry, and naming the meaning is what lets the drawing be improved later
  * without every diagram that uses it changing sense.
@@ -19,9 +19,9 @@
  * when a diagram asks for a distinction it cannot otherwise make.
  */
 /**
- * Icons carry three tones rather than colours. `ink` is the drawn line, `shade`
+ * Icons carry three tones rather than colors. `ink` is the drawn line, `shade`
  * the body it encloses, and `void` is the page showing through — the same
- * knockout a link label already uses. Naming tones instead of colours is what
+ * knockout an edge text already uses. Naming tones instead of colors is what
  * lets one glyph sit correctly on a dark theme and a light one.
  */
 export type IconTone = 'ink' | 'shade' | 'void';
@@ -40,47 +40,65 @@ export declare const ICON_STROKE = 1.1;
 export declare const ICONS: Record<string, Icon>;
 export declare const ICON_NAMES: string[];
 /**
- * The icon a node asks for, or nothing. Called by the resolver, which reserves
- * the room, and by the renderer, which fills it, so the two cannot disagree
- * about whether there is an icon at all.
- *
- * An unknown name is refused rather than dropped. That is the same rule
- * `DIAGRAM_KEYS` follows and it is here for the same reason: a misspelt
- * `icon: laptp` that quietly draws nothing is indistinguishable from the tool
- * being broken, and an author will stare at the file looking for the mistake in
- * the wrong place. Since the vocabulary is closed and short, the error can list
- * the whole of it.
- */
-/**
- * The outlines a box can take. `box` is the plain rectangle and needs no word.
+ * The outlines a node's body can take. `rectangle` is the plain one and needs no
+ * word, since it is what a node is when it says nothing.
  *
  * Named for what a node *is*, never for the geometry, which is the same rule the
  * icon names follow: `document` and not `folded-corner`. A shape carrying a
- * conventional meaning is a second channel alongside colour, and a stronger one
+ * conventional meaning is a second channel alongside color, and a stronger one
  * — a fill is whatever the author assigned and has to be learnt from the
  * diagram, while a folded corner has meant "an artifact, not a process" in
  * flowcharts for decades and reads with no legend at all.
+ *
+ * `circle` and `diamond` join these when a diagram asks. The set being short is
+ * a fact about what has been drawn, not about the key.
  */
-export declare const BOX_SHAPES: readonly ["document"];
-export type BoxShape = 'box' | (typeof BOX_SHAPES)[number];
-export interface NodeShape {
-    outline: BoxShape;
-    /**
-     * Set when the node is drawn as a glyph rather than as a box. There is then
-     * no outline, no fill and no padding: the node *is* the picture, and its size
-     * is the picture's. `icon:` decorates a box, this replaces it.
-     */
-    body?: Icon;
-}
+export declare const OUTLINES: readonly ["rectangle", "document"];
+export type Outline = (typeof OUTLINES)[number];
+/** Every value `shape:` accepts, `none` included. */
+export declare const SHAPE_WORDS: readonly ["rectangle", "document", "none"];
 /**
- * What a node is drawn as. Shared by the resolver, which sizes it, and the
- * renderer, which draws it.
+ * What a node is drawn as: an outline, a picture, or nothing at all.
+ *
+ * Two keys name it and each names one part. `shape:` is the outline the node is
+ * drawn with, `none` included; `icon:` is the picture the node is drawn *as*.
+ * Writing both is an error, because a node has one body.
  *
- * The value is either a box outline or the name of a glyph. Those are the two
- * things "what is this drawn as" can answer, and the author has no reason to
- * care which category their answer fell into. The test that separates them is
- * whether the node still sizes itself from its label: a `document` does, a
- * glyph does not.
+ * The test that separates them is whether the node still sizes itself from its
+ * text: a `document` does, a picture does not — its size is the picture's and
+ * its text goes underneath.
+ */
+export type Body = {
+    kind: 'shape';
+    outline: Outline;
+} | {
+    kind: 'icon';
+    icon: Icon;
+} | {
+    kind: 'none';
+};
+/**
+ * Which body a node has, from what it wrote and what its style carried.
+ *
+ * Called once per node while the tree is built, and the answer is kept on the
+ * node — so the resolver, which sizes the body, and the renderer, which draws
+ * it, cannot disagree about what it is.
+ *
+ * A key the node wrote itself overrules the other key coming from a style. That
+ * is the same permissiveness `checkAttrs` already grants a style: a style is a
+ * bundle meant to be shared across kinds, and a key it carries that this node
+ * has overridden is unused rather than wrong. Both keys from one level is a
+ * genuine contradiction and is refused by name.
+ */
+export declare function bodyFor(attrs: Record<string, string>, appearance: Record<string, string>, line: number): Body;
+/**
+ * The icon of that name, or an error listing the set.
+ *
+ * An unknown name is refused rather than dropped. That is the same rule
+ * `DIAGRAM_KEYS` follows and it is here for the same reason: a misspelt
+ * `icon: laptp` that quietly draws nothing is indistinguishable from the tool
+ * being broken, and an author will stare at the file looking for the mistake in
+ * the wrong place. Since the vocabulary is closed and short, the error can list
+ * the whole of it.
  */
-export declare function shapeFor(appearance: Record<string, string>, line: number): NodeShape;
-export declare function iconFor(appearance: Record<string, string>, line: number): Icon | undefined;
+export declare function iconNamed(named: string, line: number): Icon;