reladraw 0.8.1 → 0.10.0

package/NOTICE

@@ -31,6 +31,8 @@ Nord            Copyright (c) 2016-present Sven Greb
                 https://github.com/nordtheme/nord
 Dracula         Copyright (c) 2023 Dracula Theme
                 https://github.com/dracula/dracula-theme
+Vesper          Copyright (c) 2023 Rauno Freiberg
+                https://github.com/raunofreiberg/vesper
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -66,7 +66,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.8.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.
+Version 0.10.0. 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.
 
 The language isn't stable yet, so expect the syntax to change.
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.8.1
+# Syntax reference — 0.10.0
 
 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.
 
@@ -6,9 +6,19 @@ The worked example is `examples/arch.reladraw`, transcribed from the reference r
 
 ## Shape of the file
 
-One statement per line. No multi-line statements, no line continuations, no blocks.
+A statement starts at the beginning of a line. A long one may continue onto the lines after it by indenting them:
 
-Blank lines and `//` comments are ignored. A comment runs to the end of the line and may trail a statement, so `node a "Docker"  // the one that matters` is fine. Indentation is ignored entirely — a formatter may add it for readability, and stale indentation cannot change what a file means.
+```
+node desktop1 "Desktop 1 / Linux"
+  above-left of hub  gap: tight
+  badge: desktop  style: synced
+```
+
+A line that starts with whitespace continues the statement above it, and a blank line or the next unindented line ends it. How much whitespace makes no difference — one space and a tab mean the same — so nothing can depend on indentation you cannot see. A bracket may stay open across lines, as in `line: (color: red,` with `pattern: dashed)` on the next. There are no blocks: indentation continues a statement, and never puts one thing inside another.
+
+An indented line with no statement to continue — at the top of the file, or after a blank line or an unindented comment — is an error rather than a statement of its own, and so is an indented line starting with a statement keyword such as `node`. Both are almost always a stray indent, and both say to remove it.
+
+Blank lines and `//` comments are ignored. A comment runs to the end of the line and may trail a statement, so `node a "Docker"  // the one that matters` is fine. An indented comment line sits inside the statement it follows; an unindented one ends it.
 
 A lone `/` is an ordinary character rather than the start of a comment, and `#` is ordinary too — it opens a hex color. Comments were spelled `#` in an earlier version and moved to `//` so that `fill: #14532d` could be written the way every other tool writes a color.
 
@@ -116,18 +126,18 @@ They are bracketed onto the text rather than written among the node's attributes
 An edge's text takes the same brackets, less `at`: a node's text sits somewhere in a box and an edge's rides at the middle of its line, so there is no position to name.
 
 ```
-edge a -> b  "rclone" (color: muted, size: small)
+edge a -> b  "rclone" (color: theme-muted, size: small)
 ```
 
 A **style** has no text of its own for a bracket to hang off, so it hangs the bracket off a key instead:
 
 ```
-style aside  text: (size: small, color: muted)
+style aside  text: (size: small, color: theme-muted)
 ```
 
 Bundling a text's properties into a style is how they come to mean something: `style aside` applied to several nodes says those are the same kind of remark, which `(size: small)` written out at each of them does not.
 
-`color` takes a color written as the viewer will receive it — `#8b8b8b`, or any CSS color — or the one reserved word `muted`, which means the theme's secondary text color and so survives a change of theme.
+`color` takes a color written as the viewer will receive it — `#8b8b8b`, or any CSS color — or a theme color such as `theme-muted`, the theme's secondary text color, which survives a change of theme. See "Theme colors".
 
 `size: small | normal | large` sets how big the text is set, and so does a plain number of pixels, `size: 22`. The names are the default and the preferred form: they follow the document's size if it is ever set differently, where `22` stays 22. A number says nothing about *why* one text is bigger than another, so bundle it into a style that does. `14px` is refused, since the number is already in pixels, and so is zero or less. Every kind of text has a default and `size` overrides it, exactly as `fill:` overrides the theme's color; only `shape: none` defaults to anything but `normal`, and it defaults to `small`.
 
@@ -144,7 +154,7 @@ Where the node is exactly the size of what it holds — which is most leaves, si
 A word or a stretch of a text can borrow the look of a style:
 
 ```
-style dim  text: (color: muted)
+style dim  text: (color: theme-muted)
 
 node pc.files "shared folder / [dim]synced[/dim]"
 ```
@@ -395,7 +405,7 @@ edge <from> <-> <to> ["<text>"] [between <a> and <b> [vertically|horizontally]]
 
 Endpoints may be nested (`desktop1.files`). An edge never says where a node goes and routing is the renderer's problem, with one exception: an edge with text claims room in the gap it crosses, which is the next section.
 
-An edge's text breaks on ` / ` exactly as a node's does, and the block centers on the point the text would otherwise have occupied, so ``"run `deploy` / shell command"`` stacks its two lines around the midpoint of the line rather than running off along it. An edge's text takes the same brackets a node's does, less `at`, so `(wrap: 20)` folds it and `(color: muted)` quiets it.
+An edge's text breaks on ` / ` exactly as a node's does, and the block centers on the point the text would otherwise have occupied, so ``"run `deploy` / shell command"`` stacks its two lines around the midpoint of the line rather than running off along it. An edge's text takes the same brackets a node's does, less `at`, so `(wrap: 20)` folds it and `(color: theme-muted)` quiets it.
 
 ### A text makes room for itself
 
@@ -872,19 +882,19 @@ A color is never written in quotes, and a quoted one is refused. There is nothin
 
 There is no list of color words the tool knows. An earlier version had one, and it was wrong in the way such lists always are: `dark-green` existed only because somebody added it to a map in the renderer, and the next color a diagram wanted would have needed a code change to say. Writing the color directly removes both the list and the reason to grow it. `green` still works, because it is a CSS color, not because this tool has heard of it.
 
-A style carrying `text: (color: muted)` is what a marked-up word borrows from, which is how a node carries a name with a quieter qualifier under it:
+A style carrying `text: (color: theme-muted)` is what a marked-up word borrows from, which is how a node carries a name with a quieter qualifier under it:
 
 ```
 style synced  fill: #142814  border: #486544
-style dim     text: (color: muted)
+style dim     text: (color: theme-muted)
 node pc.files "shared folder / [dim]synced[/dim]"  style: synced
 ```
 
 **Removed: `subtext`.** It colored every text line after the first, which is a positional slice: the rule lived in a style elsewhere in the file and was applied by counting, so a reader of `"shared folder / synced"` could not see that the second line was quiet. The mark says what is quiet where it is quiet, and reaches a word in the middle of a line, which the slice never could. An older file carrying it gets an error naming the mark to write instead.
 
-`badge`, `icon` and `shape` belong in a style for the same reason a color does: they say what kind of thing this is, and a kind wants to look alike everywhere it appears. `style artifact  fill: #460000  shape: document` puts the folded corner on every dump in the diagram, and the use site stays one word.
+`badge`, `icon` and `shape` belong in a style for the same reason a color does: they say what kind of thing this is, and a kind wants to look alike everywhere it appears. `style artifact  fill: theme-secondary-subtle  shape: document` puts the folded corner on every dump in the diagram, and the use site stays one word.
 
-`muted` is the one reserved word left, and it earns the exception: it means the theme's secondary text color rather than a fixed one, so a quiet line stays readable when the theme changes. Writing `#8b8b8b` instead would pin it to one theme. Say nothing and every line of a text reads alike, which is what most texts want — `Computer 1 / Ubuntu` is two lines of one name, not a name and a qualifier, and the distinction is the author's to make rather than the renderer's to guess.
+`theme-muted` means the theme's secondary text color rather than a fixed one, so a quiet line stays readable when the theme changes. Writing `#8b8b8b` instead would pin it to one theme. Say nothing and every line of a text reads alike, which is what most texts want — `Computer 1 / Ubuntu` is two lines of one name, not a name and a qualifier, and the distinction is the author's to make rather than the renderer's to guess.
 
 ## The diagram itself
 
@@ -921,15 +931,50 @@ diagram  theme: solarized-dark
 | `catppuccin-mocha`, `catppuccin-latte` | [Catppuccin](https://catppuccin.com) |
 | `nord` | [Nord](https://www.nordtheme.com) |
 | `dracula` | [Dracula](https://draculatheme.com) |
+| `vesper` | [Vesper](https://github.com/raunofreiberg/vesper) |
 | `high-contrast-dark`, `high-contrast-light` | no fills to lean on, every line at full strength |
 | `print` | a white page, black lines and no fills, for paper |
 
 The borrowed palettes were made for code, where a color marks a keyword or a string. A diagram needs a page, a box, a border, text and a line, so each theme is its scheme read as a diagram rather than a copy of it. Their licenses are in `NOTICE`.
 
-A theme only ever supplies a color, so changing it never moves anything. A color you write yourself — `fill: #14532d`, or a style's — stays that color under every theme, which means a hand-picked color can clash with a theme it was not chosen against. `muted` is the one word that follows the theme.
+A theme only ever supplies a color, so changing it never moves anything. A color you write yourself — `fill: #14532d`, or a style's — stays that color under every theme, which means a hand-picked color can clash with a theme it was not chosen against. To color something and have it follow the theme, name a theme color instead.
 
 An unknown name is an error that lists the themes.
 
+### Theme colors
+
+Every theme defines the same set of colors, and any attribute that takes a color takes their names. All of them begin `theme-`, so a color that follows the theme says so, and no CSS color name is taken: `red` is still CSS red.
+
+The theme's own color for each part — what a box or a line gets when the file says nothing:
+
+| color | is |
+|---|---|
+| `theme-page` | the page |
+| `theme-text` | text |
+| `theme-muted` | quieter, secondary text |
+| `theme-fill` | a box's fill |
+| `theme-border` | a box's outline |
+| `theme-line` | a line |
+
+And its two accents, each at two strengths, with the text that reads on it:
+
+| color | is |
+|---|---|
+| `theme-primary` | the theme's signature color — Dracula's purple, Solarized's blue |
+| `theme-primary-subtle` | the same mixed toward the page: dark on a dark theme, pale on a light one |
+| `theme-on-primary` | text that reads on a solid `theme-primary` |
+| `theme-secondary`, `theme-secondary-subtle`, `theme-on-secondary` | the same for its second color |
+
+```
+style synced  fill: theme-primary-subtle  border: theme-primary
+style live    fill: theme-primary
+style dim     text: (color: theme-muted)
+```
+
+A subtle fill is how a box is set apart: its text is the theme's ordinary text, and it reads in every theme. A solid fill is a badge. A box with a theme fill and no text color of its own gets text that reads on that fill, so `style live` above needs no `text:` — its text is `theme-on-primary`. A hand-picked fill gets no such help; its text is the theme's, as before.
+
+A `theme-` name the theme does not define is refused with the list above.
+
 The command line can render a file in another theme without editing it — `reladraw arch.reladraw --theme light` — and the flag wins over the file's `theme:`. That is how one source becomes a light and a dark image for a README that shows whichever matches the reader's settings. The file's own `background:` and `text:` still win over the flag's theme, as a hand-written color wins over any theme.
 
 ### Defaults
@@ -1021,6 +1066,19 @@ 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.10.0**
+
+- A statement may continue onto the lines after it by indenting them. See "Shape of the file". An error in such a statement names the line the mistake is on.
+- **Breaking:** indentation used to be ignored, so an indented `node` line was a statement of its own. It now continues the statement above and is refused, with a message saying to remove the indentation.
+
+**0.9.0**
+
+- Theme colors: `theme-page`, `theme-text`, `theme-muted`, `theme-fill`, `theme-border` and `theme-line` name the theme's own color for each part, and `theme-primary` and `theme-secondary`, with `-subtle` and `theme-on-` forms, name its two accents. Any attribute that takes a color takes them, and they follow the theme when it changes, so a diagram colored with them reads in light and dark themes alike. See "Theme colors".
+- A box with a theme fill and no text color of its own gets text that reads on that fill.
+- **Breaking:** `muted` is now `theme-muted`. `color: muted` is refused with the new name.
+- The examples use theme colors where they used to hand-pick colors for a dark page, so they read in every theme.
+- A fourteenth theme, `vesper`, from [Vesper](https://github.com/raunofreiberg/vesper).
+
 **0.8.1**
 
 - A fix, no syntax change. An edge naming a side at both ends could be drawn through one of its own nodes in two cases. With the nodes stacked and the sides at right angles, such as `from: bottom  to: left`, the line went down past the lower node and came back up through it; it is now one curve round the corner. With both ends naming the same side, such as `from: left  to: left`, the line ran straight through the node behind; it now goes over the top of that node, or round the right in a column. Existing diagrams with such an edge will look different, and correct.

package/dist/ast.d.ts

@@ -225,7 +225,7 @@ export declare function describeAxis(axis: Axis): string;
 /** `key: value` pairs trailing a statement. Values are always strings here. */
 export type Attrs = Record<string, string>;
 /**
- * What a text's brackets may say: `"Docker" (at: bottom-center, color: muted)`.
+ * What a text's brackets may say: `"Docker" (at: bottom-center, color: theme-muted)`.
  *
  * They are bracketed onto the text rather than written among the node's
  * attributes for the same reason a gap is bracketed onto its placement — they
@@ -234,7 +234,7 @@ export type Attrs = Record<string, string>;
  * `shape`, `icon`, `fill`, `border`, `gap`, `overlap`, `style`.
  *
  * In a style, which has no string for a bracket to hang off, the bracket hangs
- * off the key instead: `style synced  text: (color: muted)`.
+ * off the key instead: `style synced  text: (color: theme-muted)`.
  *
  * `at` and `align` are independent and neither implies the other. `at` is where
  * the block of text sits in the node — one of the nine named positions — and

package/dist/ast.js

@@ -206,7 +206,7 @@ export function describeAxis(axis) {
     return axis === 'y' ? 'vertically' : 'horizontally';
 }
 /**
- * What a text's brackets may say: `"Docker" (at: bottom-center, color: muted)`.
+ * What a text's brackets may say: `"Docker" (at: bottom-center, color: theme-muted)`.
  *
  * They are bracketed onto the text rather than written among the node's
  * attributes for the same reason a gap is bracketed onto its placement — they
@@ -215,7 +215,7 @@ export function describeAxis(axis) {
  * `shape`, `icon`, `fill`, `border`, `gap`, `overlap`, `style`.
  *
  * In a style, which has no string for a bracket to hang off, the bracket hangs
- * off the key instead: `style synced  text: (color: muted)`.
+ * off the key instead: `style synced  text: (color: theme-muted)`.
  *
  * `at` and `align` are independent and neither implies the other. `at` is where
  * the block of text sits in the node — one of the nine named positions — and

package/dist/grammar.d.ts

@@ -19,9 +19,12 @@
  * The scanner is the JavaScript consumer of the same spec, and the playground is
  * its only caller.
  *
- * Nothing in the language spans lines: `//` runs to the end of one, a string
- * 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.
+ * No token spans lines: `//` runs to the end of one, a string closes on one,
+ * and there are no blocks. A statement may continue onto indented lines, but
+ * each of those is colored by the same rules, and a word that is a keyword at
+ * the start of one is refused by the parser anyway. 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 coloring. */
 export type TokenKind = 

package/dist/grammar.js

@@ -19,9 +19,12 @@
  * The scanner is the JavaScript consumer of the same spec, and the playground is
  * its only caller.
  *
- * Nothing in the language spans lines: `//` runs to the end of one, a string
- * 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.
+ * No token spans lines: `//` runs to the end of one, a string closes on one,
+ * and there are no blocks. A statement may continue onto indented lines, but
+ * each of those is colored by the same rules, and a word that is a keyword at
+ * the start of one is refused by the parser anyway. That is the property those
+ * editor formats need and the reason a `.reladraw` grammar is small in all of
+ * them.
  */
 import { DIRECTIONS, POSITIONS, SIDES, PASSAGE_AXES } from './ast.js';
 /**

package/dist/index.d.ts

@@ -10,5 +10,9 @@ export { render, type RenderOptions } from './render.js';
 export { DARK_THEME, DEFAULT_THEME, THEMES, THEME_NAMES, type Theme } from './themes.js';
 import { type RenderOptions } from './render.js';
 import { type ResolveOptions } from './resolve.js';
-/** Source text in, SVG out. The whole pipeline in one call. */
+/**
+ * Source text in, SVG out. The whole pipeline in one call. An error in a
+ * statement written over several lines names the line at fault, not the one
+ * the statement starts on; see `blame`.
+ */
 export declare function compile(source: string, options?: ResolveOptions & RenderOptions): string;

package/dist/index.js

@@ -8,10 +8,21 @@ export { parse } from './parser.js';
 export { resolve } from './resolve.js';
 export { render } from './render.js';
 export { DARK_THEME, DEFAULT_THEME, THEMES, THEME_NAMES } from './themes.js';
-import { parse } from './parser.js';
+import { SourceError } from './errors.js';
+import { blame, parse } from './parser.js';
 import { render } from './render.js';
 import { resolve } from './resolve.js';
-/** Source text in, SVG out. The whole pipeline in one call. */
+/**
+ * Source text in, SVG out. The whole pipeline in one call. An error in a
+ * statement written over several lines names the line at fault, not the one
+ * the statement starts on; see `blame`.
+ */
 export function compile(source, options = {}) {
-    return render(resolve(parse(source), options), options);
+    const run = (text) => render(resolve(parse(text), options), options);
+    try {
+        return run(source);
+    }
+    catch (error) {
+        throw error instanceof SourceError ? blame(source, error, run) : error;
+    }
 }

package/dist/lexer.d.ts

@@ -18,8 +18,11 @@ export interface Token {
  * opening bracket counts only where a token starts, and a closing one only
  * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
  *
+ * `depth` is how many brackets are still open from the lines before, when a
+ * statement continues onto this one.
+ *
  * Returns an empty array for a blank or comment-only line.
  */
-export declare function tokenizeLine(line: string, lineNumber: number): Token[];
+export declare function tokenizeLine(line: string, lineNumber: number, depth?: number): Token[];
 /** A bare token ending in `:` opens the attribute section of a statement. */
 export declare function isAttrKey(token: Token): boolean;

package/dist/lexer.js

@@ -14,12 +14,14 @@ import { SourceError } from './errors.js';
  * opening bracket counts only where a token starts, and a closing one only
  * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
  *
+ * `depth` is how many brackets are still open from the lines before, when a
+ * statement continues onto this one.
+ *
  * Returns an empty array for a blank or comment-only line.
  */
-export function tokenizeLine(line, lineNumber) {
+export function tokenizeLine(line, lineNumber, depth = 0) {
     const tokens = [];
     let i = 0;
-    let depth = 0;
     while (i < line.length) {
         const ch = line[i];
         if (ch === ' ' || ch === '\t') {

package/dist/parser.d.ts

@@ -1,3 +1,28 @@
 import type { Document } from './ast.js';
-/** Parse a whole source file. One statement per line; blanks and comments drop out. */
+import { SourceError } from './errors.js';
+/**
+ * Parse a whole source file. A statement starts on an unindented line and runs
+ * on through any line that starts with whitespace; a blank line or the next
+ * unindented one ends it. How much whitespace never matters, only whether
+ * there is any, so two lines that look alike cannot mean different things.
+ *
+ * An indented comment stays inside the statement and an unindented one ends
+ * 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.
+ */
 export declare function parse(source: string): Document;
+/**
+ * Find the line at fault for an error reported on the first line of a
+ * continued statement. Everything after the parser reports a statement by the
+ * line it starts on, which for a continued one is often not where the mistake
+ * is, so this asks which line brings the error in: `run` is tried on the
+ * source with the statement cut after each of its lines in turn, and the first
+ * cut that fails with the same message names the line. A cut that fails
+ * differently — a bracket not yet closed, a placement not yet written — is not
+ * the culprit and is passed over. Lines keep their numbers, because what is cut
+ * is blanked rather than removed.
+ *
+ * This costs a few extra runs, and only when there is an error to report.
+ */
+export declare function blame(source: string, error: SourceError, run: (source: string) => unknown): SourceError;

package/dist/parser.js

@@ -1,19 +1,108 @@
 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, 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 { THEME_NAMES, THEMES } from './themes.js';
-/** Parse a whole source file. One statement per line; blanks and comments drop out. */
+import { THEME_COLORS, THEME_NAMES, THEMES } from './themes.js';
+/**
+ * Parse a whole source file. A statement starts on an unindented line and runs
+ * on through any line that starts with whitespace; a blank line or the next
+ * unindented one ends it. How much whitespace never matters, only whether
+ * there is any, so two lines that look alike cannot mean different things.
+ *
+ * An indented comment stays inside the statement and an unindented one ends
+ * 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.
+ */
 export function parse(source) {
     const statements = [];
+    /** The statement being gathered, and the line it starts on. */
+    let open = null;
+    // Brackets may close on a later line, and the lexer only reads `)` as a
+    // bracket while one is open, so the depth is carried from line to line.
+    let depth = 0;
+    const close = () => {
+        if (open)
+            statements.push(parseStatement(open.tokens, open.line));
+        open = null;
+        depth = 0;
+    };
     source.split(/\r?\n/).forEach((line, index) => {
         const lineNumber = index + 1;
-        const tokens = tokenizeLine(line, lineNumber);
+        if (line.trim() === '') {
+            close();
+            return;
+        }
+        const indented = line[0] === ' ' || line[0] === '\t';
+        if (!indented)
+            close();
+        const tokens = tokenizeLine(line, lineNumber, depth);
         if (tokens.length === 0)
             return;
-        statements.push(parseStatement(tokens, lineNumber));
+        if (!indented) {
+            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);
+            }
+            if (!first.quoted && STATEMENT_KEYWORDS.includes(first.text)) {
+                throw new SourceError(`\`${first.text}\` cannot continue the statement above — an indented line continues ` +
+                    `the one before it, so remove the indentation to start a new statement`, lineNumber);
+            }
+            open.tokens.push(...tokens);
+        }
+        for (const token of tokens) {
+            if (token.quoted)
+                continue;
+            if (token.text === '(')
+                depth += 1;
+            else if (token.text === ')')
+                depth -= 1;
+        }
     });
+    close();
     return { statements };
 }
+/**
+ * Find the line at fault for an error reported on the first line of a
+ * continued statement. Everything after the parser reports a statement by the
+ * line it starts on, which for a continued one is often not where the mistake
+ * is, so this asks which line brings the error in: `run` is tried on the
+ * source with the statement cut after each of its lines in turn, and the first
+ * cut that fails with the same message names the line. A cut that fails
+ * differently — a bracket not yet closed, a placement not yet written — is not
+ * the culprit and is passed over. Lines keep their numbers, because what is cut
+ * is blanked rather than removed.
+ *
+ * This costs a few extra runs, and only when there is an error to report.
+ */
+export function blame(source, error, run) {
+    const lines = source.split(/\r?\n/);
+    const start = error.line - 1;
+    const first = lines[start];
+    if (first === undefined || first.trim() === '' || first[0] === ' ' || first[0] === '\t')
+        return error;
+    let end = start;
+    while (end + 1 < lines.length && lines[end + 1].trim() !== '' && /^[ \t]/.test(lines[end + 1]))
+        end += 1;
+    if (end === start)
+        return error;
+    for (let last = start; last < end; last++) {
+        const cut = lines.map((line, index) => (index > last && index <= end ? '' : line)).join('\n');
+        try {
+            run(cut);
+        }
+        catch (partial) {
+            if (partial instanceof SourceError && partial.message === error.message) {
+                return last === start ? error : new SourceError(error.message, last + 1);
+            }
+        }
+    }
+    return new SourceError(error.message, end + 1);
+}
 function parseStatement(tokens, line) {
     const keyword = tokens[0];
     if (!keyword || keyword.quoted) {
@@ -142,7 +231,7 @@ const BRACKET_KEYS = {
 };
 /** How each bracketed key's error quotes itself back, and what it is about. */
 const BRACKET_ABOUT = {
-    text: { kind: 'a text', example: 'color: muted' },
+    text: { kind: 'a text', example: 'color: theme-muted' },
     contents: { kind: 'a `contents:` bracket', example: 'widths: match' },
     line: { kind: 'a line', example: 'path: square' },
 };
@@ -183,7 +272,7 @@ function readAttr(tokens, at, attrs, line, subject) {
     const key = keyToken.text.slice(0, -1);
     const bracketKeys = BRACKET_KEYS[key];
     if (bracketKeys !== undefined && follows(tokens, at + 1, '(')) {
-        // `text: (color: muted)` — the whole bracket belongs to one part, and it is
+        // `text: (color: theme-muted)` — the whole bracket belongs to one part, and it is
         // stored under dotted keys so that a style merges into a node exactly the
         // way every other attribute does.
         const read = readBracket(tokens, at + 1, bracketKeys, {
@@ -298,7 +387,7 @@ function readAttr(tokens, at, attrs, line, subject) {
         // applied by counting, so a reader of the text could not see it. Markup
         // says what is quiet where it is quiet, and reaches a word in the middle of
         // a line, which the slice never could.
-        throw new SourceError('`subtext:` has been replaced by markup in the text — write `style dim  text: (color: muted)` ' +
+        throw new SourceError('`subtext:` has been replaced by markup in the text — write `style dim  text: (color: theme-muted)` ' +
             'and mark the quiet words as `"Dropbox / [dim]synced[/dim]"`', line);
     }
     if (key === 'text') {
@@ -342,6 +431,8 @@ function readAttr(tokens, at, attrs, line, subject) {
         }
         throw new SourceError(`"${key}" takes a color and a quoted value is text — drop the quotes if ${valueToken.text} is a color`, line);
     }
+    if (COLOR_KEYS.includes(key))
+        checkColorWord(valueToken.text, subject, line);
     setOnce(attrs, key, valueToken.text, subject, line);
     return at + 2;
 }
@@ -457,7 +548,7 @@ function parseEdge(head, line) {
         subject,
         what: 'the text',
         kind: "an edge's text",
-        example: 'color: muted',
+        example: 'color: theme-muted',
         line,
     });
     at = bracket.next;
@@ -839,6 +930,8 @@ function readBracket(tokens, start, keys, about) {
         // the comma are the same statement.
         const value = valueToken.text;
         const clean = value.endsWith(',') && value.length > 1 ? value.slice(0, -1) : value;
+        if (key === 'color')
+            checkColorWord(clean, about.subject, about.line);
         const had = values[key];
         if (had !== undefined) {
             throw new SourceError(`${about.subject}: "${key}" is written twice in the brackets after ${about.what} (${had}, ${clean}) — keep one`, about.line);
@@ -848,6 +941,20 @@ function readBracket(tokens, start, keys, about) {
     }
     return { values, next: i + 1 };
 }
+/**
+ * A color is any CSS color, which cannot be checked, or a `theme-` word, which
+ * can. So a `theme-` word the theme does not define is refused rather than
+ * handed to the viewer as a color that draws nothing, and `muted`, the one
+ * theme word from before the prefix, is refused with its new name.
+ */
+function checkColorWord(value, subject, line) {
+    if (value === 'muted') {
+        throw new SourceError(`${subject}: \`muted\` is now \`theme-muted\` — every color that follows the theme begins \`theme-\``, line);
+    }
+    if (value.startsWith('theme-') && !THEME_COLORS.includes(value)) {
+        throw new SourceError(`${subject}: there is no theme color "${value}" — the theme colors are ${THEME_COLORS.join(', ')}`, line);
+    }
+}
 function follows(tokens, at, word) {
     const token = tokens[at];
     return token !== undefined && !token.quoted && token.text === word;

package/dist/render.js

@@ -3,7 +3,7 @@ import { describeAxis } from './ast.js';
 import { SourceError } from './errors.js';
 import { ICON_STROKE } from './icons.js';
 import { monospaceMeasurer } from './measure.js';
-import { DARK_THEME, THEMES } from './themes.js';
+import { DARK_THEME, THEMES, textOnFill, themeColor } from './themes.js';
 import { plain } from './text.js';
 const CORNER = 8;
 /** Turn solved geometry into a standalone SVG document. */
@@ -17,10 +17,12 @@ export function render(layout, options = {}) {
     // everything downstream sees one theme.
     const named = layout.diagram['theme'];
     const base = options.theme ?? (named === undefined ? undefined : THEMES[named]) ?? DARK_THEME;
+    const page = layout.diagram['background'];
+    const words = layout.diagram['text.color'];
     const theme = {
         ...base,
-        ...(layout.diagram['background'] !== undefined && { background: layout.diagram['background'] }),
-        ...(layout.diagram['text.color'] !== undefined && { text: layout.diagram['text.color'] }),
+        ...(page !== undefined && { background: themeColor(page, base) }),
+        ...(words !== undefined && { text: themeColor(words, base) }),
     };
     const body = [];
     for (const root of layout.roots) {
@@ -73,7 +75,7 @@ export function render(layout, options = {}) {
         width: Math.ceil(ink.maxX) - Math.floor(ink.minX),
         height: Math.ceil(ink.maxY) - Math.floor(ink.minY),
     };
-    const arrowColors = new Set(layout.edges.map((edge) => lineOf(edge.appearance, theme.edge)));
+    const arrowColors = new Set(layout.edges.map((edge) => lineOf(edge.appearance, theme, theme.edge)));
     return [
         `<svg xmlns="http://www.w3.org/2000/svg" width="${canvas.width}" height="${canvas.height}" viewBox="${canvas.x} ${canvas.y} ${canvas.width} ${canvas.height}" font-family=${quote(measurer.fontFamily)} font-size="${fontSize}px">`,
         '  <defs>',
@@ -183,11 +185,13 @@ function nodeSvg(node, theme, measurer, fontSize, markup, url) {
     // including a lone badge beside its text. Every rule that tried to tell a
     // badge from contents was a guess; this one is visible in the source.
     const container = node.children.length > 0;
-    const border = borderOf(node.appearance, container ? theme.containerStroke : theme.boxStroke);
-    const fill = fillOf(node.appearance, container ? theme.containerFill : theme.boxFill);
+    const border = borderOf(node.appearance, theme, container ? theme.containerStroke : theme.boxStroke);
+    const fill = fillOf(node.appearance, theme, container ? theme.containerFill : theme.boxFill);
     // A box is the one kind with two inkable parts, which is why its text needs
-    // a word of its own — `border:` cannot stand in for it.
-    const text = textColorOf(node.textAttrs, theme, theme.text);
+    // a word of its own — `border:` cannot stand in for it. Left unsaid on a
+    // theme fill, it is whatever reads on that fill: `fill: theme-primary` alone
+    // makes a badge whose text is legible in every theme.
+    const text = textColorOf(node.textAttrs, theme, textOnFill(node.appearance['fill'] ?? '', theme) ?? theme.text);
     // Deck copies sit behind the front face, furthest back drawn first.
     for (let depth = node.deckTexts.length; depth >= 1; depth -= 1) {
         const x = face.x - depth * DECK_STEP;
@@ -296,7 +300,7 @@ function drawIcon(icon, x, y, side, theme) {
 }
 function drawEdge(edge, ends, corridor, route, nodes, theme, measurer, fontSize, markup) {
     const { start, end } = ends;
-    const color = lineOf(edge.appearance, theme.edge);
+    const color = lineOf(edge.appearance, theme, theme.edge);
     const stroke = strokeOf(color, edge.look);
     const markerEnd = ` marker-end="url(#${markerId(color)})"`;
     const markerStart = edge.both ? ` marker-start="url(#${markerId(color)}-back)"` : '';
@@ -409,7 +413,7 @@ function drawEdge(edge, ends, corridor, route, nodes, theme, measurer, fontSize,
         parts.push(sized(textBlock(lines, midX - width / 2, top, textHeight, size, { x: 0, y: 0, width, height }, {
             // A colored edge carries its meaning into its text; an uncolored
             // one leaves the words to read as ordinary text.
-            color: textColorOf(edge.textAttrs, theme, lineOf(edge.appearance, theme.text)),
+            color: textColorOf(edge.textAttrs, theme, lineOf(edge.appearance, theme, theme.text)),
             align: 'middle',
             ink: (run, own) => runInk(run, own, markup, theme),
         }), size, fontSize));
@@ -2654,37 +2658,37 @@ function textBlock(lines, x, y, lineHeight, fontSize, box, style) {
 function runInk(run, own, markup, theme) {
     if (run.style === undefined)
         return own;
-    return namedColor(markup[run.style], theme);
+    return themeColor(markup[run.style], theme);
 }
 /**
- * A text's own color. `muted` is the one reserved word: it defers to the theme,
- * so a quiet line stays readable when the theme changes. Anything else is a
- * color, the same as `fill:` and `border:` take.
+ * A text's own color, the same words `fill:` and `border:` take — so
+ * `theme-muted` is a quiet line that stays readable when the theme changes.
  */
 function textColorOf(textAttrs, theme, fallback) {
     const value = textAttrs['color'];
-    return value === undefined ? fallback : namedColor(value, theme);
-}
-function namedColor(value, theme) {
-    return value === 'muted' ? theme.mutedText : value;
+    return value === undefined ? fallback : themeColor(value, theme);
 }
 /**
  * A color is written as the viewer will receive it — `#14532d`, or any CSS
- * color. The renderer keeps no list of color words of its own, so a diagram
- * is never limited to the ones somebody remembered to add here.
+ * color — or as one of the `theme-` words, which the theme answers. The
+ * renderer keeps no list of color words of its own, so a diagram is never
+ * limited to the ones somebody remembered to add here.
  *
  * Each names the part it colors, so each reads exactly one key. The word these
  * replaced, `stroke:`, named no part and meant a different one on every kind,
  * which is why a box's text could not be colored at all until `text:`.
  */
-function borderOf(appearance, fallback) {
-    return appearance['border'] ?? fallback;
+function borderOf(appearance, theme, fallback) {
+    const value = appearance['border'];
+    return value === undefined ? fallback : themeColor(value, theme);
 }
-function lineOf(appearance, fallback) {
-    return appearance['line'] ?? fallback;
+function lineOf(appearance, theme, fallback) {
+    const value = appearance['line'];
+    return value === undefined ? fallback : themeColor(value, theme);
 }
-function fillOf(appearance, fallback) {
-    return appearance['fill'] ?? fallback;
+function fillOf(appearance, theme, fallback) {
+    const value = appearance['fill'];
+    return value === undefined ? fallback : themeColor(value, theme);
 }
 function round(value) {
     return Math.round(value * 100) / 100;

package/dist/resolve.js

@@ -391,7 +391,7 @@ function checkStyleKeys(statements) {
 }
 /**
  * The attribute a key belongs to. A bracketed value arrives under dotted keys —
- * `text: (color: muted)` is stored as `text.color` — so that a style merges into
+ * `text: (color: theme-muted)` is stored as `text.color` — so that a style merges into
  * a node exactly the way every other attribute does; every check above asks
  * about the part, which is the half before the dot.
  */

package/dist/themes.d.ts

@@ -28,7 +28,33 @@ export interface Theme {
     iconInk: string;
     /** The body an icon's lines enclose. */
     iconShade: string;
+    /** The theme's signature color, which `theme-primary` names. */
+    primary: Accent;
+    /** Its second color, which `theme-secondary` names. */
+    secondary: Accent;
 }
+/**
+ * An accent at the two strengths a file can ask for, and the text that reads
+ * on it. `subtle` is the accent mixed toward the page — dark on a dark theme,
+ * pale on a light one — so `fill: theme-primary-subtle` is a box set apart in
+ * every theme, and its text is the theme's ordinary text.
+ */
+export interface Accent {
+    color: string;
+    subtle: string;
+    /** Text on a solid fill of `color`: `theme-on-primary`. */
+    on: string;
+}
+export declare const THEME_COLORS: readonly string[];
+/** A color as written, with a `theme-` word replaced by the theme's value. */
+export declare function themeColor(value: string, theme: Theme): string;
+/**
+ * The text a box gets when its fill is a theme color and its text says
+ * nothing: the accent's own `on` color for a solid accent, and otherwise
+ * whichever of the theme's text and page colors stands further from the fill.
+ * A hand-picked fill is left alone — the theme has no say over it.
+ */
+export declare function textOnFill(fill: string, theme: Theme): string | undefined;
 /**
  * Sampled out of `examples/reference/arch.png` rather than invented,
  * so the benchmark render and the drawing it is measured against differ by

package/dist/themes.js

@@ -1,3 +1,74 @@
+/** How much of an accent survives in its subtle form; the rest is the page. */
+const SUBTLE = 0.25;
+function accent(color, page, on, subtle = mix(color, page, SUBTLE)) {
+    return { color, subtle, on };
+}
+/** `amount` of `color` over `page`, both `#rrggbb`. */
+function mix(color, page, amount) {
+    const channel = (hex, at) => parseInt(hex.slice(at, at + 2), 16);
+    let out = '#';
+    for (const at of [1, 3, 5]) {
+        const value = Math.round(channel(page, at) + (channel(color, at) - channel(page, at)) * amount);
+        out += value.toString(16).padStart(2, '0');
+    }
+    return out;
+}
+/**
+ * Every color a file may name from the theme, and what it is in a given one.
+ * The first six are the theme's own defaults for each part — what a line or a
+ * box gets when the file says nothing — and the rest are its two accents. All
+ * begin `theme-`, so a word that follows the theme says so, and no CSS color
+ * name is taken.
+ */
+const THEME_COLOR_OF = {
+    'theme-page': (t) => t.background,
+    'theme-text': (t) => t.text,
+    'theme-muted': (t) => t.mutedText,
+    'theme-fill': (t) => t.boxFill,
+    'theme-border': (t) => t.boxStroke,
+    'theme-line': (t) => t.edge,
+    'theme-primary': (t) => t.primary.color,
+    'theme-primary-subtle': (t) => t.primary.subtle,
+    'theme-on-primary': (t) => t.primary.on,
+    'theme-secondary': (t) => t.secondary.color,
+    'theme-secondary-subtle': (t) => t.secondary.subtle,
+    'theme-on-secondary': (t) => t.secondary.on,
+};
+export const THEME_COLORS = Object.keys(THEME_COLOR_OF);
+/** A color as written, with a `theme-` word replaced by the theme's value. */
+export function themeColor(value, theme) {
+    const of = THEME_COLOR_OF[value];
+    return of === undefined ? value : of(theme);
+}
+/**
+ * The text a box gets when its fill is a theme color and its text says
+ * nothing: the accent's own `on` color for a solid accent, and otherwise
+ * whichever of the theme's text and page colors stands further from the fill.
+ * A hand-picked fill is left alone — the theme has no say over it.
+ */
+export function textOnFill(fill, theme) {
+    if (fill === 'theme-primary')
+        return theme.primary.on;
+    if (fill === 'theme-secondary')
+        return theme.secondary.on;
+    if (THEME_COLOR_OF[fill] === undefined)
+        return undefined;
+    // `diagram background:` and `text:` may be any CSS color, which cannot be
+    // measured here, so an overruled theme keeps its ordinary text.
+    const measured = [themeColor(fill, theme), theme.text, theme.background];
+    if (!measured.every((color) => /^#[0-9a-f]{6}$/i.test(color)))
+        return theme.text;
+    const under = luminance(themeColor(fill, theme));
+    const apart = (color) => Math.abs(luminance(color) - under);
+    return apart(theme.text) >= apart(theme.background) ? theme.text : theme.background;
+}
+function luminance(hex) {
+    const [r, g, b] = [1, 3, 5].map((at) => {
+        const c = parseInt(hex.slice(at, at + 2), 16) / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
 /**
  * Sampled out of `examples/reference/arch.png` rather than invented,
  * so the benchmark render and the drawing it is measured against differ by
@@ -20,6 +91,11 @@ export const DARK_THEME = {
     // should read as part of the diagram's palette, not as clip art dropped in.
     iconInk: '#8d8d8e',
     iconShade: '#3e3d58',
+    // The reference's two colored boxes: `synced` is the green, `dump` the red.
+    // Their fills are sampled rather than mixed, so the benchmark written in
+    // theme colors renders exactly as it did in hex.
+    primary: accent('#486544', '#111111', '#d9d9d9', '#142814'),
+    secondary: accent('#8f3a3a', '#111111', '#d9d9d9', '#460000'),
 };
 /** The dark theme's counterpart: the same roles, on a white page. */
 const LIGHT_THEME = {
@@ -33,6 +109,8 @@ const LIGHT_THEME = {
     edge: '#7c83a0',
     iconInk: '#57606a',
     iconShade: '#d6d9e6',
+    primary: accent('#3a7d44', '#ffffff', '#ffffff'),
+    secondary: accent('#b3423a', '#ffffff', '#ffffff'),
 };
 /**
  * Every theme a file may name, in the order they are offered. Pairs sit
@@ -53,6 +131,8 @@ export const THEMES = {
         edge: '#268bd2',
         iconInk: '#839496',
         iconShade: '#0f4a58',
+        primary: accent('#268bd2', '#002b36', '#fdf6e3'),
+        secondary: accent('#cb4b16', '#002b36', '#fdf6e3'),
     },
     // base3 page, base2 leaves, the same blue.
     'solarized-light': {
@@ -66,6 +146,8 @@ export const THEMES = {
         edge: '#268bd2',
         iconInk: '#657b83',
         iconShade: '#e0d9c3',
+        primary: accent('#268bd2', '#fdf6e3', '#fdf6e3'),
+        secondary: accent('#cb4b16', '#fdf6e3', '#fdf6e3'),
     },
     // Gruvbox, Pavel Pertsev. bg0 page, bg1 leaves, the warm yellow for lines.
     'gruvbox-dark': {
@@ -79,6 +161,8 @@ export const THEMES = {
         edge: '#d79921',
         iconInk: '#a89984',
         iconShade: '#504945',
+        primary: accent('#fe8019', '#282828', '#282828'),
+        secondary: accent('#8ec07c', '#282828', '#282828'),
     },
     'gruvbox-light': {
         background: '#fbf1c7',
@@ -91,6 +175,8 @@ export const THEMES = {
         edge: '#b57614',
         iconInk: '#7c6f64',
         iconShade: '#d5c4a1',
+        primary: accent('#af3a03', '#fbf1c7', '#fbf1c7'),
+        secondary: accent('#427b58', '#fbf1c7', '#fbf1c7'),
     },
     // Catppuccin. Mocha's base page and surface leaves, blue lines.
     'catppuccin-mocha': {
@@ -104,6 +190,8 @@ export const THEMES = {
         edge: '#89b4fa',
         iconInk: '#a6adc8',
         iconShade: '#45475a',
+        primary: accent('#cba6f7', '#1e1e2e', '#1e1e2e'),
+        secondary: accent('#fab387', '#1e1e2e', '#1e1e2e'),
     },
     // Latte's base page and crust leaves, lavender lines.
     'catppuccin-latte': {
@@ -117,6 +205,8 @@ export const THEMES = {
         edge: '#7287fd',
         iconInk: '#6c6f85',
         iconShade: '#ccd0da',
+        primary: accent('#8839ef', '#eff1f5', '#eff1f5'),
+        secondary: accent('#fe640b', '#eff1f5', '#eff1f5'),
     },
     // Nord, Sven Greb. Polar Night page and leaves, Frost lines.
     nord: {
@@ -130,6 +220,8 @@ export const THEMES = {
         edge: '#81a1c1',
         iconInk: '#aeb7c6',
         iconShade: '#434c5e',
+        primary: accent('#88c0d0', '#2e3440', '#2e3440'),
+        secondary: accent('#d08770', '#2e3440', '#2e3440'),
     },
     // Dracula, the free palette. Current-line leaves, comment borders, purple lines.
     dracula: {
@@ -143,6 +235,24 @@ export const THEMES = {
         edge: '#bd93f9',
         iconInk: '#b6b9cc',
         iconShade: '#565a70',
+        primary: accent('#bd93f9', '#282a36', '#282a36'),
+        secondary: accent('#ff79c6', '#282a36', '#282a36'),
+    },
+    // Vesper, Rauno Freiberg. Near-black page, its input surface for leaves, and
+    // the peach it spends on everything that matters for lines; mint second.
+    vesper: {
+        background: '#101010',
+        boxFill: '#1c1c1c',
+        boxStroke: '#505050',
+        containerFill: '#161616',
+        containerStroke: '#232323',
+        text: '#ffffff',
+        mutedText: '#a0a0a0',
+        edge: '#ffc799',
+        iconInk: '#a0a0a0',
+        iconShade: '#282828',
+        primary: accent('#ffc799', '#101010', '#101010'),
+        secondary: accent('#99ffe4', '#101010', '#101010'),
     },
     // For low vision and projectors: no fills to lean on, every line at full
     // strength, and a container told apart by a gray outline alone.
@@ -157,6 +267,8 @@ export const THEMES = {
         edge: '#ffffff',
         iconInk: '#ffffff',
         iconShade: '#3a3a3a',
+        primary: accent('#ffd400', '#000000', '#000000'),
+        secondary: accent('#00e5ff', '#000000', '#000000'),
     },
     'high-contrast-light': {
         background: '#ffffff',
@@ -169,6 +281,8 @@ export const THEMES = {
         edge: '#000000',
         iconInk: '#000000',
         iconShade: '#d0d0d0',
+        primary: accent('#0033cc', '#ffffff', '#ffffff'),
+        secondary: accent('#b00000', '#ffffff', '#ffffff'),
     },
     // For paper: no fill anywhere an ink cartridge would notice, black lines,
     // gray only where the dark theme is quiet.
@@ -183,6 +297,9 @@ export const THEMES = {
         edge: '#333333',
         iconInk: '#000000',
         iconShade: '#ffffff',
+        // Grays, and pale ones for fills: a box set apart without spending color.
+        primary: accent('#333333', '#ffffff', '#ffffff', '#e6e6e6'),
+        secondary: accent('#777777', '#ffffff', '#ffffff', '#f2f2f2'),
     },
 };
 /** The theme a file gets when it names none. */

package/package.json

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