reladraw 0.4.0 → 0.5.0

package/NOTICE

@@ -12,3 +12,40 @@ any other trade names, trademarks, service marks, or product names of the
 project, except as required for reasonable and customary use in describing the
 origin of the work (see section 6 of the License). Forks and derived works are
 welcome and must be distributed under a different name.
+
+---
+
+Color palettes
+
+Several of reladraw's themes (src/themes.ts) are adapted from the color
+palettes below. Each is distributed under the MIT License, whose text follows
+the list of copyright notices and applies to each of them.
+
+Solarized       Copyright (c) 2011 Ethan Schoonover
+                https://github.com/altercation/solarized
+Gruvbox         Copyright (c) 2018 Pavel Pertsev
+                https://github.com/morhetz/gruvbox
+Catppuccin      Copyright (c) 2021 Catppuccin
+                https://github.com/catppuccin/catppuccin
+Nord            Copyright (c) 2016-present Sven Greb
+                https://github.com/nordtheme/nord
+Dracula         Copyright (c) 2023 Dracula Theme
+                https://github.com/dracula/dracula-theme
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -68,7 +68,7 @@ It is [plain Markdown](.claude/skills/reladraw/SKILL.md) with the syntax referen
 
 ## Status
 
-Version 0.4.0. Early, but it runs: a parser, resolver and SVG renderer in TypeScript with no runtime dependencies, and a command-line tool that takes a text file and writes a standalone SVG. The comparison at the top of this page is that pipeline run on [`examples/arch.reladraw`](examples/arch.reladraw). What is still visibly off there is typography, not placement.
+Version 0.5.0. Early, but it runs: a parser, resolver and SVG renderer in TypeScript with no runtime dependencies, and a command-line tool that takes a text file and writes a standalone SVG. The comparison at the top of this page is that pipeline run on [`examples/arch.reladraw`](examples/arch.reladraw). What is still visibly off there is typography, not placement.
 
 ```
 npm install -g reladraw

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.4.0
+# Syntax reference — 0.5.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.
 
@@ -630,7 +630,7 @@ Every attribute, and what takes one. The kinds here are what a node's **body** i
 | `line` | | | | ✓ | color |
 | `url` | ✓ | ✓ | ✓ | ✓ | a destination to open when the thing is clicked |
 
-The `diagram` statement has a vocabulary of its own — `background`, and so far nothing else — which is checked the same way. Writing `background:` on a node is an error that points at `fill:`.
+The `diagram` statement has a vocabulary of its own — `theme`, `background` and `text` — which is checked the same way. Writing `background:` on a node is an error that points at `fill:`, and `theme:` on one points at `diagram theme:`. A `default` takes a narrower list for each kind; see "Defaults".
 
 **A word this table does not give the kind is an error.** The two ways of being wrong get different answers, because they have different remedies. A word that is an attribute nowhere is a misspelling, and the error lists what the kind does take. A word that is an attribute *somewhere else* is usually a real statement written on the wrong half of the diagram, so the error says where it belongs:
 
@@ -762,12 +762,66 @@ diagram <attributes>
 Settings that belong to the drawing as a whole rather than to anything in it. There is no name, because a file holds one diagram, and a second `diagram` statement is an error rather than a second opinion.
 
 ```
-diagram  background: #111111
+diagram  theme: nord  background: #1e2229  text: (color: #e0e0e0)
 ```
 
-One attribute so far. `background` takes a color the same way `fill` does, and it colors the page behind everything, including the strip an edge text knocks out of whatever it crosses. Say nothing and the theme's own background stands.
+Three attributes:
 
-An unknown key is refused by name — `diagram has no "backround" — it takes background` — rather than quietly ignored, the same as every other attribute. See "Attributes".
+- `theme` names the theme that supplies every color the file does not state. See "Themes" below.
+- `background` takes a color the same way `fill` does, and it colors the page behind everything, including the strip an edge text knocks out of whatever it crosses. Say nothing and the theme's own background stands.
+- `text: (color: …)` sets the color of every text, on nodes and edges alike. It takes a color and nothing else; a text size is about one kind of text and belongs on a `default`.
+
+An unknown key is refused by name — `diagram has no "backround" — it takes theme, background, text` — rather than quietly ignored, the same as every other attribute. See "Attributes".
+
+### Themes
+
+```
+diagram  theme: solarized-dark
+```
+
+| theme | |
+|---|---|
+| `dark` | the default: the palette of the benchmark drawing |
+| `light` | the same roles on a white page |
+| `solarized-dark`, `solarized-light` | [Solarized](https://ethanschoonover.com/solarized/) |
+| `gruvbox-dark`, `gruvbox-light` | [Gruvbox](https://github.com/morhetz/gruvbox) |
+| `catppuccin-mocha`, `catppuccin-latte` | [Catppuccin](https://catppuccin.com) |
+| `nord` | [Nord](https://www.nordtheme.com) |
+| `dracula` | [Dracula](https://draculatheme.com) |
+| `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.
+
+An unknown name is an error that lists the themes.
+
+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
+
+```
+default node       border: #4a8a5c
+default leaf       fill: #2e5d3a
+default container  fill: #1a2620  border: #2a3a30
+default edge       line: #7a8a99  text: (color: #9aa5b1, size: small)
+```
+
+A default is a style that every thing of one kind wears without naming it. `node` covers every node; `leaf` a node with no children, and `container` a node with some — the same "has children" the theme's quieter backdrop colors follow, so setting a leaf's fill leaves containers looking like containers. `edge` covers every edge.
+
+The more specific word wins, all the way down:
+
+1. the theme
+2. `diagram`
+3. `default node`
+4. `default leaf` or `default container`, or `default edge`
+5. the thing's styles, a later one winning where two set the same key
+6. what the thing's own line says
+
+A default takes the words a style does, and may name a style of its own with `style:`, which it lays beneath its own words. Unlike a style, it is strict about kind: it names the kind it is for, so a word that kind has no use for can only be a mistake. `default edge  fill: red` is refused and points at `line:`. `badge:` is refused on `default leaf` and `default node`, since a badge is a child and would make every leaf a container, and `icon:` is a leaf's alone, since a picture cannot hold children. A `url:` belongs to one thing, never to a kind.
+
+Each kind is written at most once. `default leaf` twice is an error naming both lines, and `default leaf node` is refused with `default leaf` — a leaf is already a node.
 
 ## What the language refuses
 
@@ -832,6 +886,12 @@ 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.5.0**
+
+- Named themes: `diagram theme: nord`, one of thirteen, and `--theme` on the command line to render a file in another without editing it. The playground has a theme picker, which writes the `theme:` line into the source.
+- `diagram text: (color: …)` sets every text's color at once.
+- `default node | leaf | container | edge` sets what every thing of that kind looks like unless it says otherwise.
+
 **0.4.0**
 
 - A node with any children takes the theme's container colors, however the children are placed. A node with a `badge:` or a single child in a corner now draws as a container too; in 0.3.0 only a node with a title band did. Its text still sits where it did. Say `fill:` and `border:` to keep one looking like a leaf.

package/dist/ast.d.ts

@@ -282,8 +282,38 @@ export interface DiagramStmt {
     attrs: Attrs;
     line: number;
 }
-/** The attributes a `diagram` statement understands. */
-export declare const DIAGRAM_KEYS: readonly ["background"];
+/**
+ * The attributes a `diagram` statement understands. `text` takes a bracket,
+ * `text: (color: …)`, and sets the text color of everything at once — the
+ * theme has one text color, shared by nodes and edges, and this is that.
+ */
+export declare const DIAGRAM_KEYS: readonly ["theme", "background", "text"];
+/**
+ * `default leaf  fill: #2e5d3a` — a style that applies to every thing of one
+ * kind without being named. The more specific wins: `node` covers every node,
+ * `leaf` and `container` beat it for the nodes they cover, and a thing's own
+ * styles and words beat any default.
+ */
+export interface DefaultStmt {
+    kind: 'default';
+    target: DefaultTarget;
+    attrs: Attrs;
+    line: number;
+}
+export declare const DEFAULT_TARGETS: readonly ["node", "leaf", "container", "edge"];
+export type DefaultTarget = (typeof DEFAULT_TARGETS)[number];
+/**
+ * What each default may say. A default carries a style's vocabulary, less the
+ * words that would contradict the kind it is written for:
+ *
+ * - A default names its kind, so it is strict where a style is permissive —
+ *   `default edge  fill:` can only be a mistake.
+ * - `badge:` gives a box a child, which makes it a container, so every leaf
+ *   given one by `default leaf` or `default node` would stop being a leaf.
+ * - `icon:` draws a picture, and a picture cannot hold children, so it is a
+ *   leaf's word and not a container's or every node's.
+ */
+export declare const DEFAULT_KEYS: Record<DefaultTarget, readonly string[]>;
 /**
  * The attributes whose value is a color rather than text. A color is written
  * as the viewer will receive it and the renderer keeps no list of color words
@@ -365,7 +395,7 @@ export interface StyleStmt {
     attrs: Attrs;
     line: number;
 }
-export type Stmt = NodeStmt | EdgeStmt | StyleStmt | DiagramStmt;
+export type Stmt = NodeStmt | EdgeStmt | StyleStmt | DiagramStmt | DefaultStmt;
 export interface Document {
     statements: Stmt[];
 }

package/dist/ast.js

@@ -222,8 +222,30 @@ export function describeAxis(axis) {
  * `align` is how its lines range against each other once it is there.
  */
 export const TEXT_KEYS = ['color', 'size', 'wrap', 'align', 'at'];
-/** The attributes a `diagram` statement understands. */
-export const DIAGRAM_KEYS = ['background'];
+/**
+ * The attributes a `diagram` statement understands. `text` takes a bracket,
+ * `text: (color: …)`, and sets the text color of everything at once — the
+ * theme has one text color, shared by nodes and edges, and this is that.
+ */
+export const DIAGRAM_KEYS = ['theme', 'background', 'text'];
+export const DEFAULT_TARGETS = ['node', 'leaf', 'container', 'edge'];
+/**
+ * What each default may say. A default carries a style's vocabulary, less the
+ * words that would contradict the kind it is written for:
+ *
+ * - A default names its kind, so it is strict where a style is permissive —
+ *   `default edge  fill:` can only be a mistake.
+ * - `badge:` gives a box a child, which makes it a container, so every leaf
+ *   given one by `default leaf` or `default node` would stop being a leaf.
+ * - `icon:` draws a picture, and a picture cannot hold children, so it is a
+ *   leaf's word and not a container's or every node's.
+ */
+export const DEFAULT_KEYS = {
+    node: ['style', 'shape', 'fill', 'border', 'text'],
+    leaf: ['style', 'shape', 'icon', 'fill', 'border', 'text'],
+    container: ['style', 'shape', 'badge', 'fill', 'border', 'text'],
+    edge: ['style', 'line', 'text'],
+};
 /**
  * The attributes whose value is a color rather than text. A color is written
  * as the viewer will receive it and the renderer keeps no list of color words

package/dist/cli.js

@@ -3,12 +3,15 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { SourceError } from './errors.js';
 import { compile } from './index.js';
+import { THEME_NAMES, THEMES } from './themes.js';
 const USAGE = `reladraw — render a diagram from stated placement
 
-  reladraw <input.reladraw> [-o <output.svg>]
+  reladraw <input.reladraw> [-o <output.svg>] [--theme <name>]
 
   -o, --out   where to write the SVG. Defaults to the input path with
               its extension replaced by .svg. Use - for standard output.
+  --theme     render in this theme, whatever the file's \`diagram theme:\`
+              says. One of ${THEME_NAMES.join(', ')}.
   -h, --help  print this.
 `;
 async function main(argv) {
@@ -18,6 +21,7 @@ async function main(argv) {
     }
     let input;
     let out;
+    let theme;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === '-o' || arg === '--out') {
@@ -28,6 +32,18 @@ async function main(argv) {
             }
             i += 1;
         }
+        else if (arg === '--theme') {
+            theme = argv[i + 1];
+            if (theme === undefined) {
+                process.stderr.write(`reladraw: --theme needs a name: ${THEME_NAMES.join(', ')}\n`);
+                return 1;
+            }
+            if (THEMES[theme] === undefined) {
+                process.stderr.write(`reladraw: there is no theme called "${theme}" — the themes are ${THEME_NAMES.join(', ')}\n`);
+                return 1;
+            }
+            i += 1;
+        }
         else if (arg.startsWith('-') && arg !== '-') {
             process.stderr.write(`reladraw: unknown option ${arg}\n`);
             return 1;
@@ -47,7 +63,7 @@ async function main(argv) {
     const source = await readFile(input, 'utf8');
     let svg;
     try {
-        svg = compile(source);
+        svg = compile(source, theme === undefined ? {} : { theme: THEMES[theme] });
     }
     catch (error) {
         if (error instanceof SourceError) {

package/dist/grammar.d.ts

@@ -61,7 +61,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"];
+export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "diagram", "default"];
 /**
  * Every word that says something about where a thing goes. Assembled from the
  * lists the parser itself reads, so a direction or a passage axis added there

package/dist/grammar.js

@@ -30,7 +30,7 @@ import { DIRECTIONS, 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'];
+export const STATEMENT_KEYWORDS = ['node', 'edge', 'style', 'diagram', 'default'];
 /** Statements whose second word declares a name. `diagram` has none. */
 const DECLARES_NAME = ['node', 'style'];
 /**

package/dist/index.d.ts

@@ -6,7 +6,8 @@ export * from './measure.js';
 export * from './model.js';
 export { parse } from './parser.js';
 export { resolve, type ResolveOptions } from './resolve.js';
-export { render, DARK_THEME, type RenderOptions, type Theme } from './render.js';
+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. */

package/dist/index.js

@@ -6,7 +6,8 @@ export * from './measure.js';
 export * from './model.js';
 export { parse } from './parser.js';
 export { resolve } from './resolve.js';
-export { render, DARK_THEME } from './render.js';
+export { render } from './render.js';
+export { DARK_THEME, DEFAULT_THEME, THEMES, THEME_NAMES } from './themes.js';
 import { parse } from './parser.js';
 import { render } from './render.js';
 import { resolve } from './resolve.js';

package/dist/parser.js

@@ -1,6 +1,7 @@
-import { COLOR_KEYS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
+import { COLOR_KEYS, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { SourceError } from './errors.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. */
 export function parse(source) {
     const statements = [];
@@ -27,6 +28,8 @@ function parseStatement(tokens, line) {
             return parseStyle(tokens, line);
         case 'diagram':
             return parseDiagram(tokens, line);
+        case 'default':
+            return parseDefault(tokens, line);
         default:
             throw new SourceError(substitution(keyword.text, tokens), line);
     }
@@ -502,12 +505,80 @@ function parseDiagram(head, line) {
         throw new SourceError('diagram sets nothing', line);
     }
     for (const key of Object.keys(attrs)) {
+        if (key.startsWith('text.')) {
+            // The theme has one text color, shared by everything, and that is all
+            // the diagram's text sets. A size or a wrap is about one kind of text.
+            if (key !== 'text.color') {
+                const inner = key.slice('text.'.length);
+                throw new SourceError(`diagram text: sets only a color — \`${inner}\` is about one kind of text, so write ` +
+                    `\`text: (${inner}: ${attrs[key]})\` on a \`default node\` or \`default edge\``, line);
+            }
+            continue;
+        }
         if (!DIAGRAM_KEYS.includes(key)) {
             throw new SourceError(`diagram has no "${key}" — it takes ${DIAGRAM_KEYS.join(', ')}`, line);
         }
     }
+    if (attrs['text'] !== undefined) {
+        throw new SourceError('diagram text: takes a bracket — `text: (color: #e0e0e0)`', line);
+    }
+    const theme = attrs['theme'];
+    if (theme !== undefined && THEMES[theme] === undefined) {
+        throw new SourceError(`there is no theme called "${theme}" — the themes are ${THEME_NAMES.join(', ')}`, line);
+    }
     return { kind: 'diagram', attrs, line };
 }
+/**
+ * `default <node | leaf | container | edge> <attributes>` — a style every thing
+ * of that kind wears without naming it. It is strict about kind where a style
+ * is permissive, because it names the kind it is for: a word that kind has no
+ * use for can only be a mistake.
+ */
+function parseDefault(head, line) {
+    const target = head[1];
+    if (!target || target.quoted || !DEFAULT_TARGETS.includes(target.text)) {
+        throw new SourceError(`default needs the kind it is for — ${DEFAULT_TARGETS.join(', ')}` +
+            (target && !isAttrKey(target) ? `, not "${target.text}"` : ''), line);
+    }
+    const kind = target.text;
+    const subject = `default ${kind}`;
+    // `default leaf node` reads naturally and says nothing `default leaf` does not.
+    const extra = head[2];
+    if (extra && !extra.quoted && !isAttrKey(extra) && extra.text === 'node' && kind !== 'node') {
+        throw new SourceError(`write \`default ${kind}\` — a ${kind} is already a node`, line);
+    }
+    const attrs = attrsOnly(head, 2, line, subject);
+    if (Object.keys(attrs).length === 0) {
+        throw new SourceError(`${subject} sets nothing`, line);
+    }
+    const allowed = DEFAULT_KEYS[kind];
+    for (const key of new Set(Object.keys(attrs).map((k) => k.split('.')[0]))) {
+        if (allowed.includes(key))
+            continue;
+        throw new SourceError(`${subject} has ${key}:, ${defaultRefusal(kind, key)}`, line);
+    }
+    return { kind: 'default', target: kind, attrs, line };
+}
+/** Why a default cannot carry a word, and what to write instead. */
+function defaultRefusal(kind, key) {
+    const takes = `it takes ${DEFAULT_KEYS[kind].map((k) => `${k}:`).join(', ')}`;
+    if (key === 'url')
+        return `and a destination belongs to one thing rather than to every one of a kind`;
+    if (key === 'badge') {
+        return 'and a badge is a child, so every leaf given one would become a container. ' +
+            'Put the badge in a style, or write `default container  badge:`';
+    }
+    if (key === 'icon') {
+        return 'and a picture cannot hold children, so an icon is a leaf\'s word — write `default leaf  icon:`';
+    }
+    if (kind === 'edge' && (key === 'fill' || key === 'border')) {
+        return `which an edge does not have — an edge is colored by line: and text: (color: …)`;
+    }
+    if (kind !== 'edge' && key === 'line') {
+        return `which is an edge's — a node is colored by fill:, border: and text: (color: …)`;
+    }
+    return `which a default does not set — ${takes}`;
+}
 function requireName(token, keyword, line) {
     if (!token || token.quoted) {
         throw new SourceError(`${keyword} needs a name`, line);

package/dist/render.d.ts

@@ -1,31 +1,10 @@
 import { type Measurer } from './measure.js';
 import type { Layout } from './model.js';
+import { type Theme } from './themes.js';
 export interface RenderOptions {
     measurer?: Measurer;
     fontSize?: number;
     theme?: Theme;
 }
-export interface Theme {
-    background: string;
-    boxFill: string;
-    boxStroke: string;
-    containerFill: string;
-    /** A container is a region rather than a thing, so its outline is quieter. */
-    containerStroke: string;
-    text: string;
-    mutedText: string;
-    edge: string;
-    /** An icon's drawn line. */
-    iconInk: string;
-    /** The body an icon's lines enclose. */
-    iconShade: string;
-}
-/**
- * Sampled out of `examples/reference/arch.png` rather than invented,
- * so the benchmark render and the drawing it is measured against differ by
- * geometry and typography alone. A container is a shade off the page and barely
- * outlined; a leaf is the navy that carries the diagram's weight.
- */
-export declare const DARK_THEME: Theme;
 /** Turn solved geometry into a standalone SVG document. */
 export declare function render(layout: Layout, options?: RenderOptions): string;

package/dist/render.js

@@ -3,40 +3,25 @@ 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 { plain } from './text.js';
-/**
- * Sampled out of `examples/reference/arch.png` rather than invented,
- * so the benchmark render and the drawing it is measured against differ by
- * geometry and typography alone. A container is a shade off the page and barely
- * outlined; a leaf is the navy that carries the diagram's weight.
- */
-export const DARK_THEME = {
-    background: '#111111',
-    boxFill: '#191728',
-    boxStroke: '#4f5367',
-    containerFill: '#191920',
-    containerStroke: '#25242f',
-    text: '#d9d9d9',
-    mutedText: '#8b8b8b',
-    edge: '#5c5c7c',
-    // Both sampled off the reference's machine glyphs. Note that the reference
-    // gives each icon its own hue — the drive is gray, the laptop periwinkle, the
-    // workstation violet — which is a drawing tool's per-shape default and not a
-    // system. One pair for the whole set is the deliberate difference: an icon
-    // should read as part of the diagram's palette, not as clip art dropped in.
-    iconInk: '#8d8d8e',
-    iconShade: '#3e3d58',
-};
 const CORNER = 8;
 /** Turn solved geometry into a standalone SVG document. */
 export function render(layout, options = {}) {
     const measurer = options.measurer ?? monospaceMeasurer();
     const fontSize = options.fontSize ?? DEFAULT_FONT_SIZE;
-    // `diagram background:` is the author overruling the theme for this one
-    // drawing, so it is folded in here and everything downstream sees one theme.
-    const base = options.theme ?? DARK_THEME;
-    const stated = layout.diagram['background'];
-    const theme = stated === undefined ? base : { ...base, background: stated };
+    // A theme passed in — the command line's `--theme` — beats the one the file
+    // names, so one source renders in either. `diagram background:` and `text:`
+    // are the author overruling a color of whichever theme that is, and a color
+    // written by hand wins over any theme, so they are folded in afterwards and
+    // everything downstream sees one theme.
+    const named = layout.diagram['theme'];
+    const base = options.theme ?? (named === undefined ? undefined : THEMES[named]) ?? DARK_THEME;
+    const theme = {
+        ...base,
+        ...(layout.diagram['background'] !== undefined && { background: layout.diagram['background'] }),
+        ...(layout.diagram['text.color'] !== undefined && { text: layout.diagram['text.color'] }),
+    };
     const body = [];
     for (const root of layout.roots) {
         body.push(drawNode(root, theme, measurer, fontSize, layout.markup));

package/dist/resolve.js

@@ -23,11 +23,12 @@ export function resolve(doc, options = {}) {
     const margin = options.margin ?? DEFAULT_MARGIN;
     const styles = collectStyles(doc.statements);
     checkStyleKeys(doc.statements);
-    const { nodes, byName, roots } = buildTree(doc.statements, styles);
+    const defaults = collectDefaults(doc.statements, styles);
+    const { nodes, byName, roots } = buildTree(doc.statements, styles, defaults);
     // 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.
-    const edges = buildEdges(doc.statements, byName, styles);
+    const edges = buildEdges(doc.statements, byName, styles, defaults);
     const local = new Map();
     for (const root of roots)
         sizeNode(root, edges, measurer, fontSize, local);
@@ -58,6 +59,40 @@ function collectStyles(statements) {
     }
     return styles;
 }
+/**
+ * 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
+ * written twice is refused, as a second `diagram` is: nothing says which was
+ * meant.
+ */
+function collectDefaults(statements, styles) {
+    const defaults = new Map();
+    const seen = new Map();
+    for (const stmt of statements) {
+        if (stmt.kind !== 'default')
+            continue;
+        const earlier = seen.get(stmt.target);
+        if (earlier !== undefined) {
+            throw new SourceError(`default ${stmt.target} is written twice, here and on line ${earlier} — keep one`, stmt.line);
+        }
+        seen.set(stmt.target, stmt.line);
+        const { style: _named, ...flat } = appearanceOf(stmt.attrs, styles, stmt.line);
+        defaults.set(stmt.target, flat);
+    }
+    return defaults;
+}
+/**
+ * One bundle laid over a weaker one, key by key — except the body, which is
+ * one thing said by either of two words. A default's `shape: cylinder` under
+ * a style's `icon: disk` is not a node with two bodies; the style said what
+ * this node is drawn as, and that settles it.
+ */
+function over(base, top) {
+    if (top['shape'] === undefined && top['icon'] === undefined)
+        return { ...base, ...top };
+    const { shape: _shape, icon: _icon, ...rest } = base;
+    return { ...rest, ...top };
+}
 /** A file holds one diagram, so a second `diagram` statement is a mistake. */
 function collectDiagram(statements) {
     let found;
@@ -70,12 +105,27 @@ function collectDiagram(statements) {
     }
     return found ?? {};
 }
-function buildTree(statements, styles) {
+function buildTree(statements, styles, defaults) {
     const nodes = [];
     const byName = new Map();
     const roots = [];
     /** Each badge child's name, and the node whose `badge:` it was written out from. */
     const badges = new Map();
+    // Which nodes will hold children has to be known before any node is built,
+    // because it decides which default a node wears, and its children are
+    // declared after it. A child is a dotted name, or a badge the node's own
+    // line or styles give it; a default cannot give a leaf a badge, so what
+    // the defaults say cannot change the answer.
+    const parents = new Set();
+    for (const stmt of statements) {
+        if (stmt.kind !== 'node')
+            continue;
+        const cut = stmt.name.lastIndexOf('.');
+        if (cut !== -1)
+            parents.add(stmt.name.slice(0, cut));
+        if (appearanceOf(stmt.attrs, styles, stmt.line)['badge'] !== undefined)
+            parents.add(stmt.name);
+    }
     for (const stmt of statements) {
         if (stmt.kind !== 'node')
             continue;
@@ -87,7 +137,9 @@ function buildTree(statements, styles) {
             }
             throw new SourceError(`"${stmt.name}" is declared twice`, stmt.line);
         }
-        const appearance = appearanceOf(stmt.attrs, styles, stmt.line);
+        // 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 kind = KIND_OF_BODY[body.kind];
         // A node with no text of its own is labelled with its name, because the
@@ -275,6 +327,11 @@ function checkAttrs(kind, name, attrs, line) {
             const parts = COLOR_PARTS[kind].map((part) => `\`${part}\``).join(', ');
             throw new SourceError(`"${name}" is ${article(KIND_WORD[kind])} and has ${wrote}. ${capital(article(KIND_WORD[kind]))} is ${KIND_PARTS[kind]}, so it has no ${key} — it takes ${parts}`, line);
         }
+        // A word only the whole drawing takes, such as a theme.
+        if (belongTo(key).length === 0) {
+            throw new SourceError(`"${name}" is ${article(KIND_WORD[kind])} and has ${wrote}. \`${key}:\` is said about the ` +
+                `whole drawing — write \`diagram ${key}: ${shown}\``, line);
+        }
         // Anything else names no part, so what the kind is made of explains
         // nothing. What does explain it is where the word *does* belong, which is
         // also the more useful thing to be told: the author has usually written a
@@ -373,7 +430,7 @@ function appearanceOf(attrs, styles, line) {
     }
     return { ...merged, ...attrs };
 }
-function buildEdges(statements, byName, styles) {
+function buildEdges(statements, byName, styles, defaults) {
     const edges = [];
     for (const stmt of statements) {
         if (stmt.kind !== 'edge')
@@ -400,7 +457,7 @@ function buildEdges(statements, byName, styles) {
             }),
             ...(stmt.between.axis !== undefined ? { axis: stmt.between.axis } : {}),
         };
-        const appearance = appearanceOf(stmt.attrs, styles, stmt.line);
+        const appearance = { ...defaults.get('edge'), ...appearanceOf(stmt.attrs, styles, stmt.line) };
         const what = `${stmt.from} -> ${stmt.to}`;
         checkAttrs('edge', what, stmt.attrs, stmt.line);
         checkStyleUse('edge', what, stmt.attrs, styles, stmt.line);

package/dist/themes.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The named themes a file chooses with `diagram theme: <name>`, and the one it
+ * gets when it says nothing.
+ *
+ * A theme supplies every color the file does not state. It never supplies a
+ * size or a distance, so switching themes cannot move anything — geometry may
+ * not depend on appearance.
+ *
+ * Most of the palettes are borrowed from editor color schemes, all of them MIT
+ * licensed and credited in NOTICE. Those palettes were made for code, where a
+ * color marks a keyword or a string; a diagram needs a page, two box fills, a
+ * border, text and a line. So each is the scheme read as a diagram rather than
+ * a transfer of it: the page is the scheme's background, a leaf is its raised
+ * surface, a container sits between the two, and the lines take one of its
+ * accents.
+ */
+export interface Theme {
+    background: string;
+    boxFill: string;
+    boxStroke: string;
+    containerFill: string;
+    /** A container is a region rather than a thing, so its outline is quieter. */
+    containerStroke: string;
+    text: string;
+    mutedText: string;
+    edge: string;
+    /** An icon's drawn line. */
+    iconInk: string;
+    /** The body an icon's lines enclose. */
+    iconShade: string;
+}
+/**
+ * Sampled out of `examples/reference/arch.png` rather than invented,
+ * so the benchmark render and the drawing it is measured against differ by
+ * geometry and typography alone. A container is a shade off the page and barely
+ * outlined; a leaf is the navy that carries the diagram's weight.
+ */
+export declare const DARK_THEME: Theme;
+/**
+ * Every theme a file may name, in the order they are offered. Pairs sit
+ * together, dark first, and the two that have no light half follow them.
+ */
+export declare const THEMES: Readonly<Record<string, Theme>>;
+/** The theme a file gets when it names none. */
+export declare const DEFAULT_THEME = "dark";
+export declare const THEME_NAMES: readonly string[];

package/dist/themes.js

@@ -0,0 +1,190 @@
+/**
+ * Sampled out of `examples/reference/arch.png` rather than invented,
+ * so the benchmark render and the drawing it is measured against differ by
+ * geometry and typography alone. A container is a shade off the page and barely
+ * outlined; a leaf is the navy that carries the diagram's weight.
+ */
+export const DARK_THEME = {
+    background: '#111111',
+    boxFill: '#191728',
+    boxStroke: '#4f5367',
+    containerFill: '#191920',
+    containerStroke: '#25242f',
+    text: '#d9d9d9',
+    mutedText: '#8b8b8b',
+    edge: '#5c5c7c',
+    // Both sampled off the reference's machine glyphs. Note that the reference
+    // gives each icon its own hue — the drive is gray, the laptop periwinkle, the
+    // workstation violet — which is a drawing tool's per-shape default and not a
+    // system. One pair for the whole set is the deliberate difference: an icon
+    // should read as part of the diagram's palette, not as clip art dropped in.
+    iconInk: '#8d8d8e',
+    iconShade: '#3e3d58',
+};
+/** The dark theme's counterpart: the same roles, on a white page. */
+const LIGHT_THEME = {
+    background: '#ffffff',
+    boxFill: '#eef0f7',
+    boxStroke: '#8a90a8',
+    containerFill: '#f6f7fa',
+    containerStroke: '#dcdfe7',
+    text: '#1f2328',
+    mutedText: '#6e7781',
+    edge: '#7c83a0',
+    iconInk: '#57606a',
+    iconShade: '#d6d9e6',
+};
+/**
+ * Every theme a file may name, in the order they are offered. Pairs sit
+ * together, dark first, and the two that have no light half follow them.
+ */
+export const THEMES = {
+    dark: DARK_THEME,
+    light: LIGHT_THEME,
+    // Solarized, Ethan Schoonover. base03 page, base02 leaves, blue lines.
+    'solarized-dark': {
+        background: '#002b36',
+        boxFill: '#073642',
+        boxStroke: '#586e75',
+        containerFill: '#03313c',
+        containerStroke: '#0b3f4c',
+        text: '#93a1a1',
+        mutedText: '#657b83',
+        edge: '#268bd2',
+        iconInk: '#839496',
+        iconShade: '#0f4a58',
+    },
+    // base3 page, base2 leaves, the same blue.
+    'solarized-light': {
+        background: '#fdf6e3',
+        boxFill: '#eee8d5',
+        boxStroke: '#93a1a1',
+        containerFill: '#f6efdc',
+        containerStroke: '#e3dcc7',
+        text: '#586e75',
+        mutedText: '#93a1a1',
+        edge: '#268bd2',
+        iconInk: '#657b83',
+        iconShade: '#e0d9c3',
+    },
+    // Gruvbox, Pavel Pertsev. bg0 page, bg1 leaves, the warm yellow for lines.
+    'gruvbox-dark': {
+        background: '#282828',
+        boxFill: '#3c3836',
+        boxStroke: '#665c54',
+        containerFill: '#32302f',
+        containerStroke: '#3c3836',
+        text: '#ebdbb2',
+        mutedText: '#a89984',
+        edge: '#d79921',
+        iconInk: '#a89984',
+        iconShade: '#504945',
+    },
+    'gruvbox-light': {
+        background: '#fbf1c7',
+        boxFill: '#ebdbb2',
+        boxStroke: '#bdae93',
+        containerFill: '#f2e5bc',
+        containerStroke: '#e5d4a7',
+        text: '#3c3836',
+        mutedText: '#7c6f64',
+        edge: '#b57614',
+        iconInk: '#7c6f64',
+        iconShade: '#d5c4a1',
+    },
+    // Catppuccin. Mocha's base page and surface leaves, blue lines.
+    'catppuccin-mocha': {
+        background: '#1e1e2e',
+        boxFill: '#313244',
+        boxStroke: '#6c7086',
+        containerFill: '#25253a',
+        containerStroke: '#313244',
+        text: '#cdd6f4',
+        mutedText: '#9399b2',
+        edge: '#89b4fa',
+        iconInk: '#a6adc8',
+        iconShade: '#45475a',
+    },
+    // Latte's base page and crust leaves, lavender lines.
+    'catppuccin-latte': {
+        background: '#eff1f5',
+        boxFill: '#dce0e8',
+        boxStroke: '#9ca0b0',
+        containerFill: '#e6e9ef',
+        containerStroke: '#ccd0da',
+        text: '#4c4f69',
+        mutedText: '#7c7f93',
+        edge: '#7287fd',
+        iconInk: '#6c6f85',
+        iconShade: '#ccd0da',
+    },
+    // Nord, Sven Greb. Polar Night page and leaves, Frost lines.
+    nord: {
+        background: '#2e3440',
+        boxFill: '#3b4252',
+        boxStroke: '#4c566a',
+        containerFill: '#333a47',
+        containerStroke: '#3b4252',
+        text: '#d8dee9',
+        mutedText: '#7b88a1',
+        edge: '#81a1c1',
+        iconInk: '#aeb7c6',
+        iconShade: '#434c5e',
+    },
+    // Dracula, the free palette. Current-line leaves, comment borders, purple lines.
+    dracula: {
+        background: '#282a36',
+        boxFill: '#44475a',
+        boxStroke: '#6272a4',
+        containerFill: '#21222c',
+        containerStroke: '#343746',
+        text: '#f8f8f2',
+        mutedText: '#6272a4',
+        edge: '#bd93f9',
+        iconInk: '#b6b9cc',
+        iconShade: '#565a70',
+    },
+    // 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.
+    'high-contrast-dark': {
+        background: '#000000',
+        boxFill: '#000000',
+        boxStroke: '#ffffff',
+        containerFill: '#000000',
+        containerStroke: '#9a9a9a',
+        text: '#ffffff',
+        mutedText: '#c8c8c8',
+        edge: '#ffffff',
+        iconInk: '#ffffff',
+        iconShade: '#3a3a3a',
+    },
+    'high-contrast-light': {
+        background: '#ffffff',
+        boxFill: '#ffffff',
+        boxStroke: '#000000',
+        containerFill: '#ffffff',
+        containerStroke: '#6a6a6a',
+        text: '#000000',
+        mutedText: '#3d3d3d',
+        edge: '#000000',
+        iconInk: '#000000',
+        iconShade: '#d0d0d0',
+    },
+    // For paper: no fill anywhere an ink cartridge would notice, black lines,
+    // gray only where the dark theme is quiet.
+    print: {
+        background: '#ffffff',
+        boxFill: '#ffffff',
+        boxStroke: '#000000',
+        containerFill: '#ffffff',
+        containerStroke: '#8c8c8c',
+        text: '#000000',
+        mutedText: '#666666',
+        edge: '#333333',
+        iconInk: '#000000',
+        iconShade: '#ffffff',
+    },
+};
+/** The theme a file gets when it names none. */
+export const DEFAULT_THEME = 'dark';
+export const THEME_NAMES = Object.keys(THEMES);

package/package.json

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