reladraw 0.14.4 → 0.15.1

package/README.md

@@ -82,7 +82,7 @@ That gets you a copy of the skill at the time you run it, so you'll need to re-r
 
 ## Status
 
-Version 0.14.4. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG, and an element that does the same inside a web page.
+Version 0.15.1. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG, and an element that does the same inside a web page.
 
 The language isn't stable yet, so expect the syntax to change.
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.14.4
+# Syntax reference — 0.15.1
 
 What the language accepts. The parser, resolver and SVG renderer implement all of it; the sections at the end record what is defective, unchecked or undecided.
 
@@ -212,7 +212,7 @@ A circle is an ordinary node in every other way, and the file means the same thi
 
 A name says what the thing *is*, never what the picture looks like: naming the meaning is what lets the drawing be improved later without every diagram that uses it changing sense. `document`, not `folded-corner`. The one place that rule stops is a picture with no single meaning — the cube stands for a container in one diagram, a VM in another, a service in a third — which is why it is called `cube` and not `instance`. An unrecognized name is an error listing the whole set, rather than a node that quietly draws nothing.
 
-The icon set is small on purpose, and it is not the trade a drawing tool makes. There you pick a shape out of a visual palette and hundreds are browsable; here you type the word from memory, which caps the useful vocabulary at what fits in a head. Adding your own is not possible yet — see "Not built yet".
+The icon set is small on purpose, and it is not the trade a drawing tool makes. There you pick a shape out of a visual palette and hundreds are browsable; here you type the word from memory, which caps the useful vocabulary at what fits in a head. A picture outside it is one you declare yourself — see [Your own icons](#your-own-icons).
 
 `cubes` draws three whatever the number, because it is the symbol for "several" and not a count. Where the number matters — where one of them is the end of an arrow — they are separate nodes, each with `icon: cube`.
 
@@ -220,7 +220,7 @@ A node drawn as a picture is an ordinary node in every other way. It takes place
 
 **A picture with no text of its own shows none.** Everywhere else a node with no text is labelled with its name, because `node a` and `node b right of a` mean the two boxes to read "a" and "b". A picture usually *is* the statement, so the default flips: `node svc icon: cube` draws the cube and no caption, and a row of five of them does not come out reading a, b, c, d, e. Write the text if you want one.
 
-Icons are drawn from path data inside the tool, never from a font or a linked file. The output is a standalone SVG and has to stay one — an icon font renders as blank boxes on a machine that does not have it, and a linked image has to travel beside the file.
+The built-in icons are drawn from path data inside the tool, never from a font or a linked file. The output is a standalone SVG and has to stay one — an icon font renders as blank boxes on a machine that does not have it, and a linked image has to travel beside the file.
 
 ### Badges
 
@@ -258,6 +258,36 @@ style store  fill: #142814  border: #486544  badge: database
 node records "Records"  style: store
 ```
 
+### Your own icons
+
+`icon <name>` declares a picture of your own, and from then on `icon: <name>` and `badge: <name>` use it exactly as they would a built-in one. The picture is SVG, pasted between `"""` marks or read from a file:
+
+```
+icon crate """
+<svg viewBox="0 0 24 24">
+  <path d="M3 7 L12 3 L21 7 L21 17 L12 21 L3 17 Z" fill="none" stroke="currentColor"/>
+</svg>
+"""
+
+icon rack "./rack.svg"
+
+node store "Warehouse"  badge: crate
+node servers  icon: rack  right of store
+```
+
+Between `"""` marks everything is taken as written, double quotes and line breaks included, so an SVG can be pasted in unchanged. The opening `"""` may start the next line rather than end the `icon` line. A `"""` string is accepted only in an `icon` declaration for now.
+
+A file is found relative to the diagram's own file. Only the command-line tool can read one; in the playground or a web page, paste the SVG instead.
+
+- **It keeps its own colors.** A pasted drawing looks the same on every theme. What it leaves to `currentColor` takes the theme's icon color, which is how a one-color icon follows the theme.
+- **It is fitted to the icon's square,** in proportion and centered, by its `viewBox`. With no `viewBox`, its `width` and `height` stand in; with neither it is refused, since nothing says how big the drawing is.
+- **Its ids and class names are renamed** on the way in, so two icons that both call a gradient `a` don't pick up each other's.
+- **Script is refused:** a `<script>` element or an `on…` attribute.
+
+An icon of your own with a built-in's name replaces the built-in throughout the diagram, so `icon disk "./my-disk.svg"` redraws every disk. Declaring one name twice is an error.
+
+The drawing is written into the output, so the SVG stays standalone however the icon was supplied.
+
 ## Placement
 
 A *placement* says one thing about where a node goes. A node carries as many as it needs.
@@ -1066,8 +1096,6 @@ Designed, decided, and absent from the code. Written down so the next version ha
 
 **Nothing keeps an edge clear of a node on its own.** Non-overlap applies to nodes only. A line may still cut across a node it has nothing to do with, and an edge text may still land on top of one. `between` and `below <node>` are how you say where a line goes when that matters, and nothing checks the ones where you have not said. A check belongs on the diagnostics list, but finding a route by itself does not — see "What the language refuses".
 
-**An icon outside the built-in seven.** The set is closed, and a diagram wanting a picture that is not in it has nowhere to go. The two shapes this could take are a declaration in the file, `icon <name> "<path data>"` beside `style`, and `icon: ./thing.svg` inlined by the tool at render time. Either keeps the output standalone, which is the constraint any answer has to meet.
-
 **A named channel cannot make room for itself.** Lines through a `between` gap too narrow for them crowd together silently, in exactly the way attachments on a too-short side do. An edge with text *does* now open the gap between its own two ends — see "A text makes room for itself" — and it does so by the measure-then-constrain route that region alignments already use, which is the route this wants too. What is missing is the harder case: several edges sharing a channel between two nodes neither of them is an end of, where the room needed is the whole stack of lanes rather than one text.
 
 ## Known to be wrong
@@ -1112,6 +1140,18 @@ That one was found by testing the lexer, not by rendering — and it could not h
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal below is refused by name with the replacement quoted, rather than dropped in silence — an older file stops with an error saying what to write instead.
 
+**0.15.1**
+
+No syntax changes, and no file that worked is refused. No example diagram draws differently.
+
+- A fix: many copies of one line slowed down sharply past fifty-five. With fifty-six or more copies of `edge a -> b  from: left  to: right`, the ends on each side sat under half a pixel apart, and every copy was then routed on its own instead of being drawn as a copy, so sixty took five and a half seconds. They now draw as copies however close their ends sit, and sixty take under a second.
+
+**0.15.0**
+
+No file that worked is refused. No example diagram draws differently.
+
+- Icons of your own. `icon crate """<svg …>…</svg>"""` declares one from pasted SVG, or `icon crate "./crate.svg"` from a file, and `icon: crate` and `badge: crate` then use it like a built-in. One with a built-in's name replaces it. See [Your own icons](#your-own-icons).
+
 **0.14.4**
 
 No syntax changes, and no file that worked is refused. No example diagram draws differently.

package/dist/ast.d.ts

@@ -442,7 +442,23 @@ export interface StyleStmt {
     attrs: Attrs;
     line: number;
 }
-export type Stmt = NodeStmt | EdgeStmt | StyleStmt | DiagramStmt | DefaultStmt;
+/**
+ * `icon <name> <picture>`: a picture of the author's own, used by name wherever
+ * a built-in one could be. `source` is as written — the SVG itself, or the path
+ * of a file holding it.
+ */
+export interface IconStmt {
+    kind: 'icon';
+    name: string;
+    source: string;
+    /**
+     * True when `source` is the SVG itself: written between `"""` marks, or
+     * starting with `<`. Otherwise it names a file.
+     */
+    pasted: boolean;
+    line: number;
+}
+export type Stmt = NodeStmt | EdgeStmt | StyleStmt | DiagramStmt | DefaultStmt | IconStmt;
 export interface Document {
     statements: Stmt[];
 }

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { SourceError } from './errors.js';
@@ -63,7 +64,12 @@ async function main(argv) {
     const source = await readFile(input, 'utf8');
     let svg;
     try {
-        svg = compile(source, theme === undefined ? {} : { theme: THEMES[theme] });
+        svg = compile(source, {
+            ...(theme === undefined ? {} : { theme: THEMES[theme] }),
+            // An icon's file is found from the diagram, not from wherever the tool
+            // happens to be run.
+            readIconFile: (path) => readFileSync(resolvePath(dirname(input), path), 'utf8'),
+        });
     }
     catch (error) {
         if (error instanceof SourceError) {

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"];
+export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default", "icon"];
 /**
  * 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
@@ -74,7 +74,7 @@ export declare const RELATION_WORDS: string[];
 export declare const PATTERNS: {
     readonly comment: "\\/\\/.*";
     readonly string: "\"(?:\\\\.|[^\"\\\\])*\"?";
-    readonly keyword: `(?:${string})\\b`;
+    readonly keyword: `(?:${string})\\b(?!:)`;
     readonly arrow: `${string}?-{1,2}${string}?(?=[ \\t]|$)`;
     readonly attribute: "[A-Za-z][A-Za-z0-9_-]*:";
     readonly color: "#[0-9A-Fa-f]{3,8}\\b";

package/dist/grammar.js

@@ -33,9 +33,9 @@ import { DIRECTIONS, MARKS, POSITIONS, SIDES, PASSAGE_AXES } from './ast.js';
  * 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'];
+export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default', 'icon'];
 /** Statements whose second word declares a name. `diagram` has none. */
-const DECLARES_NAME = ['node', 'style'];
+const DECLARES_NAME = ['node', 'style', 'icon'];
 /**
  * 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
@@ -80,7 +80,9 @@ export const PATTERNS = {
     // it is being typed, and a highlighter that waits for the quote repaints the
     // rest of the file on every keystroke.
     string: '"(?:\\\\.|[^"\\\\])*"?',
-    keyword: `(?:${alternation(STATEMENT_KEYWORDS)})\\b`,
+    // Not before a colon: `icon` is a keyword and `icon:` an attribute, and an
+    // indented line may open with the attribute.
+    keyword: `(?:${alternation(STATEMENT_KEYWORDS)})\\b(?!:)`,
     // A mark, one or two dashes, a mark — `->`, `o--odiamond`, `[dot]-`. It must
     // end the token, so a hyphenated name stays a word. A mark written apart in
     // brackets, `[dot] -- [arrow]`, colors as plain words either side of `--`.

package/dist/icons.d.ts

@@ -30,11 +30,25 @@ export interface IconPath {
     fill?: IconTone;
     stroke?: IconTone;
 }
-export interface Icon {
+/** A built-in picture, drawn in the theme's tones. */
+export interface DrawnIcon {
     /** Side of the square the paths are drawn on. Scaled to the drawn size. */
     readonly grid: number;
     readonly paths: readonly IconPath[];
 }
+/**
+ * A picture the author supplied as SVG, written into the output as a nested
+ * `<svg>` fitted to the icon's square. It keeps its own colors: a pasted
+ * drawing is drawn as it was drawn, on every theme. What it leaves to
+ * `currentColor` takes the theme's icon line color, which is how a
+ * one-color icon set follows the theme anyway.
+ */
+export interface PastedIcon {
+    /** The root element's attributes, less the ones the placement sets. */
+    readonly attrs: string;
+    readonly inner: string;
+}
+export type Icon = DrawnIcon | PastedIcon;
 /** Line width on the 24-unit grid, scaled with everything else. */
 export declare const ICON_STROKE = 1.1;
 export declare const ICONS: Record<string, Icon>;
@@ -93,7 +107,7 @@ export type Body = {
  * 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;
+export declare function bodyFor(attrs: Record<string, string>, appearance: Record<string, string>, line: number, declared?: ReadonlyMap<string, Icon>): Body;
 /**
  * The icon of that name, or an error listing the set.
  *
@@ -101,7 +115,20 @@ export declare function bodyFor(attrs: Record<string, string>, appearance: Recor
  * `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 wrong place. The vocabulary is short enough for the error to list all of
+ * it, the file's own icons included.
+ *
+ * An icon the file declares wins over a built-in of the same name, so an author
+ * who dislikes the drawing of `disk` can replace it everywhere at once.
+ */
+export declare function iconNamed(named: string, line: number, declared?: ReadonlyMap<string, Icon>): Icon;
+/**
+ * Read an author's SVG into an icon. `name` makes the drawing's own ids and
+ * class names unique, so two pasted icons that both call a gradient `a` do not
+ * paint with each other's.
+ *
+ * Refused, each by name: text with no `<svg>` in it, a drawing with no way to
+ * tell its size, and anything that runs script, which a diagram has no use for
+ * and a browser showing the diagram might execute.
  */
-export declare function iconNamed(named: string, line: number): Icon;
+export declare function pastedIcon(source: string, name: string, line: number): PastedIcon;

package/dist/icons.js

@@ -149,7 +149,7 @@ const PLAIN = { kind: 'shape', outline: 'rectangle' };
  * has overridden is unused rather than wrong. Both keys from one level is a
  * genuine contradiction and is refused by name.
  */
-export function bodyFor(attrs, appearance, line) {
+export function bodyFor(attrs, appearance, line, declared = new Map()) {
     const wroteShape = attrs['shape'] !== undefined;
     const wroteIcon = attrs['icon'] !== undefined;
     let shape = wroteIcon && !wroteShape ? undefined : appearance['shape'];
@@ -159,7 +159,7 @@ export function bodyFor(attrs, appearance, line) {
             'body — `shape:` is the outline it is drawn with, `icon:` is the picture it is drawn as', line);
     }
     if (icon !== undefined)
-        return { kind: 'icon', icon: iconNamed(icon, line) };
+        return { kind: 'icon', icon: iconNamed(icon, line, declared) };
     if (shape === undefined)
         return PLAIN;
     if (shape === 'none')
@@ -194,14 +194,101 @@ function refuse(message, line) {
  * `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 wrong place. The vocabulary is short enough for the error to list all of
+ * it, the file's own icons included.
+ *
+ * An icon the file declares wins over a built-in of the same name, so an author
+ * who dislikes the drawing of `disk` can replace it everywhere at once.
  */
-export function iconNamed(named, line) {
-    const icon = ICONS[named];
+export function iconNamed(named, line, declared = new Map()) {
+    const icon = declared.get(named) ?? ICONS[named];
     if (icon === undefined) {
         const was = named === 'instance' ? ' — the cube was called `instance` until 0.3.0' : '';
-        throw new SourceError(`there is no icon called "${named}". The icons are ${ICON_NAMES.join(', ')}${was}`, line);
+        const all = [...new Set([...ICON_NAMES, ...declared.keys()])];
+        throw new SourceError(`there is no icon called "${named}". The icons are ${all.join(', ')}${was}`, line);
     }
     return icon;
 }
+/**
+ * Read an author's SVG into an icon. `name` makes the drawing's own ids and
+ * class names unique, so two pasted icons that both call a gradient `a` do not
+ * paint with each other's.
+ *
+ * Refused, each by name: text with no `<svg>` in it, a drawing with no way to
+ * tell its size, and anything that runs script, which a diagram has no use for
+ * and a browser showing the diagram might execute.
+ */
+export function pastedIcon(source, name, line) {
+    const start = source.search(/<svg[\s>/]/);
+    if (start === -1) {
+        throw new SourceError(`icon "${name}" is not an SVG — it should contain an <svg> element`, line);
+    }
+    if (/<script[\s>]/i.test(source) || /\son[a-z]+\s*=/i.test(source)) {
+        throw new SourceError(`icon "${name}" contains script, which a diagram has no use for and a browser showing it ` +
+            'might run — remove the <script> element or the on… attribute', line);
+    }
+    const open = /^<svg((?:\s+[^\s=>/]+(?:\s*=\s*(?:"[^"]*"|'[^']*'))?)*)\s*(\/?)>/.exec(source.slice(start));
+    if (open === null) {
+        throw new SourceError(`icon "${name}" has an <svg> tag that does not close — it needs its >`, line);
+    }
+    const bodyStart = start + open[0].length;
+    const end = source.lastIndexOf('</svg>');
+    if (open[2] !== '/' && end < bodyStart) {
+        throw new SourceError(`icon "${name}" has no </svg> to end it`, line);
+    }
+    let inner = open[2] === '/' ? '' : source.slice(bodyStart, end);
+    const attrs = new Map();
+    for (const [, key, value] of open[1].matchAll(/([^\s=]+)(?:\s*=\s*("[^"]*"|'[^']*'))?/g)) {
+        attrs.set(key, value ?? '""');
+    }
+    // The placement sets where the drawing goes and how big it is, and a nested
+    // <svg> needs no namespace of its own.
+    const width = attrs.get('width');
+    const height = attrs.get('height');
+    for (const key of [...attrs.keys()]) {
+        if (['x', 'y', 'width', 'height', 'version'].includes(key) || key === 'xmlns' || key.startsWith('xmlns:')) {
+            attrs.delete(key);
+        }
+    }
+    if (!attrs.has('viewBox')) {
+        const number = (value) => Number(value?.slice(1, -1).replace(/px$/, ''));
+        const w = number(width);
+        const h = number(height);
+        if (!(w > 0 && h > 0)) {
+            throw new SourceError(`icon "${name}" has no viewBox and no width and height to take one from, so there is no ` +
+                'telling how big its drawing is — add viewBox="0 0 <width> <height>"', line);
+        }
+        attrs.set('viewBox', `"0 0 ${w} ${h}"`);
+    }
+    // The output declares no xlink namespace, and SVG 2 reads a plain `href`.
+    inner = inner.replace(/\sxlink:href=/g, ' href=');
+    const prefix = `rd-${name.replace(/[^A-Za-z0-9_-]/g, '_')}-`;
+    const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // An id is renamed where it is defined and where it is referred to, which is
+    // `url(#…)` or `href="#…"` — never a bare `#…`, which may be a color.
+    for (const [, , double, single] of inner.matchAll(/\sid\s*=\s*("([^"]*)"|'([^']*)')/g)) {
+        const id = double ?? single;
+        const pattern = escape(id);
+        inner = inner
+            .replace(new RegExp(`(\\sid\\s*=\\s*["'])${pattern}(["'])`, 'g'), `$1${prefix}${id}$2`)
+            .replace(new RegExp(`(url\\(\\s*['"]?#)${pattern}(?=['"]?\\s*\\))`, 'g'), `$1${prefix}${id}`)
+            .replace(new RegExp(`(\\shref\\s*=\\s*["']#)${pattern}(?=["'])`, 'g'), `$1${prefix}${id}`);
+    }
+    // A class is renamed on the elements that wear it and in the drawing's own
+    // <style> blocks, since a stylesheet in an SVG applies to the whole document.
+    const classes = new Set();
+    for (const [, , double, single] of inner.matchAll(/\sclass\s*=\s*("([^"]*)"|'([^']*)')/g)) {
+        for (const each of (double ?? single).split(/\s+/))
+            if (each !== '')
+                classes.add(each);
+    }
+    inner = inner.replace(/(\sclass\s*=\s*["'])([^"']*)/g, (_, key, value) => key + value.replace(/[^\s]+/g, (each) => prefix + each));
+    inner = inner.replace(/(<style[^>]*>)([\s\S]*?)(<\/style>)/g, (_, open, css, close) => {
+        for (const each of classes) {
+            css = css.replace(new RegExp(`\\.${escape(each)}(?![\\w-])`, 'g'), `.${prefix}${each}`);
+        }
+        return open + css + close;
+    });
+    const written = [...attrs].map(([key, value]) => `${key}=${value}`).join(' ');
+    return { attrs: written, inner: inner.trim() };
+}

package/dist/lexer.d.ts

@@ -1,7 +1,17 @@
+import { SourceError } from './errors.js';
 export interface Token {
     text: string;
     /** True when the token came from a quoted string, so `foo:` inside it is literal. */
     quoted: boolean;
+    /** True when the string was written between `"""` marks. */
+    triple?: boolean;
+}
+/**
+ * A `"""` string still open at the end of the text given. `parse` catches this
+ * one, adds the next line and tries again, which is how a string runs over
+ * several lines without the lexer having to know about lines.
+ */
+export declare class OpenString extends SourceError {
 }
 /**
  * Split one line into tokens. Whitespace separates; double quotes group, with
@@ -21,6 +31,9 @@ export interface Token {
  * `depth` is how many brackets are still open from the lines before, when a
  * statement continues onto this one.
  *
+ * `line` may hold line breaks, but only inside a `"""` string: `parse` joins
+ * the lines such a string spans before handing them over.
+ *
  * Returns an empty array for a blank or comment-only line.
  */
 export declare function tokenizeLine(line: string, lineNumber: number, depth?: number): Token[];

package/dist/lexer.js

@@ -1,4 +1,11 @@
 import { SourceError } from './errors.js';
+/**
+ * A `"""` string still open at the end of the text given. `parse` catches this
+ * one, adds the next line and tries again, which is how a string runs over
+ * several lines without the lexer having to know about lines.
+ */
+export class OpenString extends SourceError {
+}
 /**
  * Split one line into tokens. Whitespace separates; double quotes group, with
  * `\"` and `\\` as the only escapes. A `//` outside quotes starts a comment and
@@ -17,6 +24,9 @@ import { SourceError } from './errors.js';
  * `depth` is how many brackets are still open from the lines before, when a
  * statement continues onto this one.
  *
+ * `line` may hold line breaks, but only inside a `"""` string: `parse` joins
+ * the lines such a string spans before handing them over.
+ *
  * Returns an empty array for a blank or comment-only line.
  */
 export function tokenizeLine(line, lineNumber, depth = 0) {
@@ -42,6 +52,17 @@ export function tokenizeLine(line, lineNumber, depth = 0) {
             i += 1;
             continue;
         }
+        // Between `"""` marks everything is taken as written, quotes and line breaks
+        // included, with no escapes. That is what makes an SVG pasteable: it is full
+        // of double quotes and never has three in a row.
+        if (line.startsWith('"""', i)) {
+            const end = line.indexOf('"""', i + 3);
+            if (end === -1)
+                throw new OpenString('this """ string is never closed — end it with """', lineNumber);
+            tokens.push({ text: line.slice(i + 3, end), quoted: true, triple: true });
+            i = end + 3;
+            continue;
+        }
         if (ch === '"') {
             let text = '';
             i += 1;

package/dist/parser.d.ts

@@ -10,6 +10,10 @@ import { SourceError } from './errors.js';
  * it. An indented line with nothing open above it is refused rather than read
  * as a statement of its own: it is a stray indent or a deleted first line, and
  * both are worth hearing about.
+ *
+ * A `"""` string is the one thing that crosses these rules: the lines it spans
+ * are its own, blank or not, and a line opening with one continues the
+ * statement above without being indented.
  */
 export declare function parse(source: string): Document;
 /**

package/dist/parser.js

@@ -1,7 +1,7 @@
 import { COLOR_KEYS, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, LINE_KEYS, LINE_VALUES, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { SourceError } from './errors.js';
 import { STATEMENT_KEYWORDS } from './grammar.js';
-import { isAttrKey, tokenizeLine } from './lexer.js';
+import { isAttrKey, OpenString, tokenizeLine } from './lexer.js';
 import { THEME_COLORS, THEME_NAMES, THEMES } from './themes.js';
 /**
  * Parse a whole source file. A statement starts on an unindented line and runs
@@ -13,6 +13,10 @@ import { THEME_COLORS, THEME_NAMES, THEMES } from './themes.js';
  * it. An indented line with nothing open above it is refused rather than read
  * as a statement of its own: it is a stray indent or a deleted first line, and
  * both are worth hearing about.
+ *
+ * A `"""` string is the one thing that crosses these rules: the lines it spans
+ * are its own, blank or not, and a line opening with one continues the
+ * statement above without being indented.
  */
 export function parse(source) {
     const statements = [];
@@ -27,26 +31,53 @@ export function parse(source) {
         open = null;
         depth = 0;
     };
-    source.split(/\r?\n/).forEach((line, index) => {
+    const lines = source.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
         const lineNumber = index + 1;
+        let line = lines[index];
         if (line.trim() === '') {
             close();
-            return;
+            continue;
         }
+        // A line opening with `"""` continues the statement above without being
+        // indented, because nothing else could start with one: no statement begins
+        // with a string, so `icon rack` on one line and the SVG from the next is
+        // unambiguous. The exception is that narrow on purpose — a statement that
+        // could carry on through any line would turn a forgotten word into an error
+        // about some other line.
         const indented = line[0] === ' ' || line[0] === '\t';
-        if (!indented)
+        const continues = indented || line.startsWith('"""');
+        if (!continues)
             close();
-        const tokens = tokenizeLine(line, lineNumber, depth);
+        // A `"""` string may run on over the lines after it, blank ones included,
+        // and every line it covers belongs to it rather than to the statement
+        // structure above.
+        let tokens;
+        for (;;) {
+            try {
+                tokens = tokenizeLine(line, lineNumber, depth);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof OpenString) || index + 1 >= lines.length)
+                    throw error;
+                index += 1;
+                line += '\n' + lines[index];
+            }
+        }
         if (tokens.length === 0)
-            return;
-        if (!indented) {
+            continue;
+        if (!continues) {
             open = { tokens, line: lineNumber };
         }
         else {
             const first = tokens[0];
             if (!open) {
-                throw new SourceError('this line is indented, which continues the statement above, but there is none to ' +
-                    'continue — remove the indentation to start a new statement', lineNumber);
+                throw new SourceError(indented
+                    ? 'this line is indented, which continues the statement above, but there is none to ' +
+                        'continue — remove the indentation to start a new statement'
+                    : 'a """ string at the start of a line belongs to the statement above, but there is ' +
+                        'none — write it after the words it goes with, such as `icon rack`', lineNumber);
             }
             if (!first.quoted && STATEMENT_KEYWORDS.includes(first.text)) {
                 throw new SourceError(`\`${first.text}\` cannot continue the statement above — an indented line continues ` +
@@ -62,7 +93,7 @@ export function parse(source) {
             else if (token.text === ')')
                 depth -= 1;
         }
-    });
+    }
     close();
     return { statements };
 }
@@ -108,7 +139,16 @@ function parseStatement(tokens, line) {
     if (!keyword || keyword.quoted) {
         throw new SourceError('a statement must begin with a keyword', 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 — ' +
+            'use ordinary quotes here', line);
+    }
     switch (keyword.text) {
+        case 'icon':
+            return parseIcon(tokens, line);
         case 'node':
             return parseNode(tokens, line);
         case 'edge':
@@ -712,6 +752,22 @@ function parseStyle(head, line) {
     }
     return { kind: 'style', name, attrs, line };
 }
+/**
+ * `icon <name> "<svg>…</svg>"`, or `icon <name> ./file.svg`. What the picture
+ * is — pasted markup or a file to read — is worked out when the diagram is
+ * resolved, since only the caller knows whether files can be read at all.
+ */
+function parseIcon(head, line) {
+    const name = requireName(head[1], 'icon', line);
+    const picture = head[2];
+    if (picture === undefined || isAttrKey(picture)) {
+        throw new SourceError(`icon "${name}" needs its picture: the SVG itself between """ marks, or the name of an .svg file`, line);
+    }
+    if (head.length > 3) {
+        throw new SourceError(`icon "${name}" takes one picture and nothing else — "${head[3].text}" is left over`, line);
+    }
+    return { kind: 'icon', name, source: picture.text, pasted: picture.triple === true || picture.text.trim().startsWith('<'), line };
+}
 /**
  * `diagram <attributes>` — no name, because a file holds one diagram. Unknown
  * keys are refused rather than ignored: a misspelt diagram-wide setting that

package/dist/render.js

@@ -335,6 +335,17 @@ function outlineDetail(shape, x, y, w, h) {
 }
 /** One icon, scaled from its own grid onto a square of `side` at `x, y`. */
 function drawIcon(icon, x, y, side, theme) {
+    if ('inner' in icon) {
+        // Its own viewBox fits it to the square, centered and in proportion.
+        // `color` is set only when the drawing does not set it, so `currentColor`
+        // means the theme's icon line unless the author said otherwise.
+        const color = /(^|\s)color=/.test(icon.attrs) ? '' : ` color="${theme.iconInk}"`;
+        return [
+            `  <svg x="${round(x)}" y="${round(y)}" width="${round(side)}" height="${round(side)}"${color} ${icon.attrs}>`,
+            icon.inner,
+            '  </svg>',
+        ].join('\n');
+    }
     const scale = side / icon.grid;
     const color = (tone) => tone === 'ink' ? theme.iconInk : tone === 'shade' ? theme.iconShade : theme.background;
     const paths = icon.paths.map((path) => {
@@ -1877,7 +1888,10 @@ function planWays(edges, nodes, ends, corridors, measurer, fontSize) {
         const normal = heading.map((one) => ({ x: -one.y, y: one.x }));
         const along = (from, to, axis) => (to.x - from.x) * axis.x + (to.y - from.y) * axis.y;
         const shift = along(base[0], start, normal[0]);
-        if (Math.abs(shift) < 0.5 || Math.abs(along(base[0], start, heading[0])) > 0.5)
+        // Any shift will do, however small: where more lines leave a side than it
+        // has room for, their ends sit under half a pixel apart, and refusing those
+        // sent fifty-six copies to the search and took seconds.
+        if (Math.abs(shift) < 1e-6 || Math.abs(along(base[0], start, heading[0])) > 0.5)
             return undefined;
         if (Math.abs(along(base[count], end, normal[count - 1]) - shift) > 0.5 || Math.abs(along(base[count], end, heading[count - 1])) > 0.5) {
             return undefined;

package/dist/resolve.d.ts

@@ -6,6 +6,12 @@ export interface ResolveOptions {
     fontSize?: number;
     /** Blank space kept around the whole diagram. */
     margin?: number;
+    /**
+     * Read the file an `icon` declaration names, as text. The command-line tool
+     * supplies it, reading relative to the diagram's own file; without it, as in
+     * a browser, an icon has to be pasted in rather than named by file.
+     */
+    readIconFile?: (path: string) => string;
 }
 /**
  * Turn a parsed document into solved geometry.

package/dist/resolve.js

@@ -2,7 +2,7 @@ import { ALL_ATTR_KEYS, ATTR_KEYS, MARKS, PART_SIDES, COLOR_KEYS, COLOR_PARTS, C
 import { BARE_EDGE_RUN, CHILD_GAP, DECK_STEP, DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, HEADER_GAP, ICON_GAP, ICON_LINES, TEXT_CLEARANCE, PAD, SEPARATION_GAP, THICKNESS, arrowLength, fontSizeFor, leafTop, textExtent, textStyleFor, widestLine, } from './constants.js';
 import { fix, reachability, tightest } from './constrain.js';
 import { SourceError } from './errors.js';
-import { bodyFor } from './icons.js';
+import { bodyFor, pastedIcon } from './icons.js';
 import { monospaceMeasurer } from './measure.js';
 import { markupStyles, parseMarkup, plain, splitRuns, wrapLine } from './text.js';
 /**
@@ -24,7 +24,8 @@ export function resolve(doc, options = {}) {
     const styles = collectStyles(doc.statements);
     checkStyleKeys(doc.statements);
     const defaults = collectDefaults(doc.statements, styles);
-    const { nodes, byName, roots } = buildTree(doc.statements, styles, defaults);
+    const icons = collectIcons(doc.statements, options.readIconFile);
+    const { nodes, byName, roots } = buildTree(doc.statements, styles, defaults, icons);
     // Edges are resolved to nodes before anything is sized, because a labeled
     // edge claims room in the gap it crosses and so has to be in hand while the
     // gaps are being worked out. Nothing here reads geometry.
@@ -59,6 +60,33 @@ function collectStyles(statements) {
     }
     return styles;
 }
+/** The file's own icons, by name, each pasted in or read from its file. */
+function collectIcons(statements, readIconFile) {
+    const icons = new Map();
+    for (const stmt of statements) {
+        if (stmt.kind !== 'icon')
+            continue;
+        if (icons.has(stmt.name)) {
+            throw new SourceError(`icon "${stmt.name}" is declared twice`, stmt.line);
+        }
+        let svg = stmt.source.trim();
+        if (!stmt.pasted) {
+            if (readIconFile === undefined) {
+                throw new SourceError(`icon "${stmt.name}" names a file, "${svg}", and files can be read only by the ` +
+                    'command-line tool — paste the SVG itself between """ marks instead', stmt.line);
+            }
+            try {
+                svg = readIconFile(svg);
+            }
+            catch (error) {
+                const why = error instanceof Error ? error.message : String(error);
+                throw new SourceError(`icon "${stmt.name}" could not read "${svg}": ${why}`, stmt.line);
+            }
+        }
+        icons.set(stmt.name, pastedIcon(svg, stmt.name, stmt.line));
+    }
+    return icons;
+}
 /**
  * Each kind's default, with any style it names already folded in beneath its
  * own words, so a default arrives at a node as one flat bundle. The same kind
@@ -105,7 +133,7 @@ function collectDiagram(statements) {
     }
     return found ?? {};
 }
-function buildTree(statements, styles, defaults) {
+function buildTree(statements, styles, defaults, icons) {
     const nodes = [];
     const byName = new Map();
     const roots = [];
@@ -140,7 +168,7 @@ function buildTree(statements, styles, defaults) {
         // Weakest first: every node's default, then the leaf's or the container's,
         // then the node's own styles and words over both.
         const appearance = over(over(defaults.get('node') ?? {}, defaults.get(parents.has(stmt.name) ? 'container' : 'leaf') ?? {}), appearanceOf(stmt.attrs, styles, stmt.line));
-        const body = bodyFor(stmt.attrs, appearance, stmt.line);
+        const body = bodyFor(stmt.attrs, appearance, stmt.line, icons);
         const kind = KIND_OF_BODY[body.kind];
         // A node with no text of its own is labelled with its name, because the
         // first lines anybody types are `node a` and `node b right of a` and they
@@ -208,7 +236,7 @@ function buildTree(statements, styles, defaults) {
         // the other kinds refuse the word in `checkAttrs`, and a style's is unused.
         const named = appearance['badge'];
         if (named !== undefined && body.kind === 'shape') {
-            const badge = badgeChild(node, named);
+            const badge = badgeChild(node, named, icons);
             badges.set(badge.name, node.name);
             node.children.push(badge);
             nodes.push(badge);
@@ -218,13 +246,13 @@ function buildTree(statements, styles, defaults) {
     return { nodes, byName, roots };
 }
 /** The child `badge:` writes out, as `buildTree` describes. */
-function badgeChild(parent, named) {
+function badgeChild(parent, named, icons) {
     const icon = { icon: named };
     const size = parent.textAttrs['size'];
     return {
         name: `${parent.name}.badge`,
         kind: 'icon',
-        body: bodyFor(icon, icon, parent.line),
+        body: bodyFor(icon, icon, parent.line, icons),
         text: '',
         lines: linesFor('', {}, `"${parent.name}.badge"`, parent.line),
         children: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.14.4",
+  "version": "0.15.1",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {