reladraw 0.3.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.3.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.3.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.
 
@@ -129,7 +129,7 @@ Bundling a text's properties into a style is how they come to mean something: `s
 
 `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.
 
-`size: small | normal | large` sets how big the text is set. The sizes are named for the reason gaps are named: a number would be typography by coordinate, stale the moment the document is set at another size, and silent about *why* one piece of text is smaller than another. 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`.
+`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`.
 
 `wrap: <n>` folds the text at word boundaries every `n` characters, on top of whatever ` / ` already breaks. It is how you make a block of text narrow and tall so it can sit snugly beside something, rather than wide and short so it cannot. The number is a count of characters and not a distance: it says how much fits on a line and nothing about where anything sits.
 
@@ -602,10 +602,12 @@ Nothing bounds bare text the way a border bounds a node, so a sentence-length on
 ## Decks
 
 ```
-deck <name> "<text>" ["<text>" ...]
+node drive "Drive 1"  deck: "Drive 2" "Drive 3"
 ```
 
-Draws the named container with offset copies behind it, one per text, to say "there are several of these and they are the same." Only the front copy shows its contents.
+`deck:` draws offset copies behind a box, one per text, back to front, to say "there are several of these and they are the same." Only the front copy shows its contents. It goes on a box only; a picture or a `shape: none` node has no outline to repeat, and refuses it. A style may carry it.
+
+**Changed after 0.3.0.** This was a statement of its own, `deck drive "Drive 2" "Drive 3"`, which created nothing and only said more about a node declared elsewhere. The statement is now an error that quotes the attribute to write instead.
 
 ## Attributes
 
@@ -613,11 +615,12 @@ Every attribute, and what takes one. The kinds here are what a node's **body** i
 
 | attribute | `shape:` | `icon:` | `shape: none` | edge | says |
 |---|---|---|---|---|---|
-| `style` | ✓ | ✓ | ✓ | ✓ | the named bundle to take appearance from |
+| `style` | ✓ | ✓ | ✓ | ✓ | the named bundles to take appearance from, one or a list |
 | `gap` | ✓ | ✓ | ✓ | | the default distance to whatever it is placed against |
 | `overlap` | ✓ | ✓ | ✓ | | `allow`, to opt out of non-overlap |
 | `contents` | ✓ | | | | how the children are sized and where the block of them sits, in brackets |
 | `badge` | ✓ | | | | the picture beside the text |
+| `deck` | ✓ | | | | offset copies behind the box, one quoted text each |
 | `shape` | ✓ | | ✓ | | the outline the node is drawn with, `none` included |
 | `icon` | | ✓ | | | the picture the node is drawn as |
 | `from` `to` | | | | ✓ | which side the line leaves and arrives on |
@@ -627,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:
 
@@ -637,6 +640,8 @@ The `diagram` statement has a vocabulary of its own — `background`, and so far
 
 Some of the gaps in the table are worth saying out loud, because none of them looks like a mistake while you are writing it. A picture and a bodiless node take no `fill:` or `border:` — there is no outline for either to reach. Neither takes `contents:` either, which says how a node's children sit, and neither may have any. `shape:` and `icon:` each appear only on the kind they make, and writing both is an error naming both. An edge takes no `gap:` or `overlap:` — those say where a node sits, and an edge is not placed, it joins two things that are.
 
+**A key is written once per statement.** `fill: red  fill: blue` is an error that quotes both values and asks you to keep one: two words on one line are equally explicit, so nothing says which was meant, and keeping either would drop the other in silence. It is almost always an edit that forgot to delete the old value. The same holds inside brackets — `(size: small, size: large)`, a placement's `(gap: wide, gap: tight)` — for `style:` written twice, and for a `style` statement that repeats one of its own keys. Two `text: (…)` brackets in one style are fine as long as they say different things. A node overriding its style is not a repeat; see "Styles".
+
 **Changed 2026-09-09.** Until then a node or edge attribute the tool did not recognize was parsed, stored and never read: `wibble: red` on a node drew nothing and said nothing. This was the last place in the language where a key could silently do nothing, and the rule everywhere else — an unknown `diagram` key, an unknown placement modifier, a color naming a part the kind has not got — has always been that a key which silently does nothing looks like the tool being broken rather than like a typo. A file that rendered with a stray word in it will now stop with an error naming it.
 
 ## Destinations
@@ -673,6 +678,23 @@ node server.mirror "shared folder / mirror"  style: backup
 
 The appearance attributes are `fill`, `border`, `line`, `text`, `badge`, `icon` and `shape`. The first three each take a color written as the viewer will receive it — `#142814`, or any CSS color, or `none`; `text` takes the bracket described under "The text and its brackets".
 
+**What a statement says itself beats what its style says**, wherever `style:` sits on the line. Here the server's border is red, not orange:
+
+```
+style backup  border: #d2904e
+node server "Server"  border: red  style: backup
+```
+
+Whoever wrote `border: red` on the node meant it for that node, so it is an override rather than a contradiction, and nothing is refused. The rest of the style still applies.
+
+**A thing may take several styles**, listed the way a placement lists its targets — commas and `and` both separate:
+
+```
+node pump "Pump 3"  style: equipment, critical and alarm
+```
+
+They apply in the order written, and a later style wins where two set the same key; the statement's own words still win over all of them. Each style in the list is checked on its own, so one that gives the thing nothing is refused even when its neighbors do not. A style named twice in one list is refused, and so is `style:` written twice on one statement — the list is the way to say several.
+
 ### A color names the part it colors
 
 A color attribute says which part of a thing it colors, and a part exists only on the kinds that have one:
@@ -740,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)
+```
+
+Three 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)
 ```
 
-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.
+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
 
-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".
+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
 
@@ -810,6 +886,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.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.
+- A text's `size` takes a plain number of pixels beside `small`, `normal` and `large`: `(size: 22)`.
+- **Breaking:** `deck` is an attribute of the node, not a statement. `deck drive "Drive 2" "Drive 3"` is written `deck: "Drive 2" "Drive 3"` on `node drive`, and the old statement is an error that quotes that line back. It is refused on a picture and on a `shape: none` node, where the statement used to draw nothing.
+- **Breaking:** a key written twice on one statement is an error that quotes both values — `fill: red  fill: blue`, `style:` twice, or the same property twice inside one set of brackets. In 0.3.0 one of the two was dropped in silence. A node's own word overriding its style's is unaffected.
+- `style:` takes a list, `style: equipment, critical and alarm`, applied in order with a later style winning where two set the same key.
 **0.3.0** — the vocabulary, reworked in one breaking version so there is one migration rather than five.
 
 - `box` is `node` and `link` is `edge`. The string on either is its *text*; "label" is not a word the language has.

package/dist/ast.d.ts

@@ -272,14 +272,6 @@ export interface EdgeStmt {
     attrs: Attrs;
     line: number;
 }
-export interface DeckStmt {
-    kind: 'deck';
-    /** The container to draw with offset copies behind it. */
-    name: string;
-    /** One text per copy, back to front as written. */
-    texts: string[];
-    line: number;
-}
 /**
  * `diagram background: #111111` — settings that belong to the drawing as a
  * whole rather than to anything in it. It has no name because there is only
@@ -290,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
@@ -373,7 +395,7 @@ export interface StyleStmt {
     attrs: Attrs;
     line: number;
 }
-export type Stmt = NodeStmt | EdgeStmt | DeckStmt | 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
@@ -290,7 +312,7 @@ export const COLOR_PARTS = {
  *   an edge is not placed — it joins two things that are.
  */
 export const ATTR_KEYS = {
-    shape: ['style', 'gap', 'overlap', 'contents', 'badge', 'shape', 'fill', 'border', 'text', 'url'],
+    shape: ['style', 'gap', 'overlap', 'contents', 'badge', 'deck', 'shape', 'fill', 'border', 'text', 'url'],
     icon: ['style', 'gap', 'overlap', 'icon', 'text', 'url'],
     none: ['style', 'gap', 'overlap', 'shape', 'text', 'url'],
     edge: ['style', 'from', 'to', 'line', 'text', 'url'],

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/constants.d.ts

@@ -98,10 +98,10 @@ export declare const ICON_LINES = 2;
 export declare const ICON_GAP = 10;
 export declare const DEFAULT_FONT_SIZE = 14;
 /**
- * The named text sizes, each a multiple of the document's own size. Named
- * rather than numeric for the reason gaps are: a number here is typography by
- * coordinate. It goes stale the moment the document is set at another size, and
- * it says nothing about why one piece of text is smaller than another.
+ * The named text sizes, each a multiple of the document's own size. A plain
+ * number of pixels is accepted too, as it is for a gap: nothing else in the
+ * diagram moving can make it wrong. The names stay the default because they
+ * follow the document's size when that is retuned, and a number does not.
  *
  * `small` is sampled rather than chosen. In
  * `examples/reference/arch.png` the box and container texts run 25

package/dist/constants.js

@@ -110,10 +110,10 @@ export const ICON_LINES = 2;
 export const ICON_GAP = 10;
 export const DEFAULT_FONT_SIZE = 14;
 /**
- * The named text sizes, each a multiple of the document's own size. Named
- * rather than numeric for the reason gaps are: a number here is typography by
- * coordinate. It goes stale the moment the document is set at another size, and
- * it says nothing about why one piece of text is smaller than another.
+ * The named text sizes, each a multiple of the document's own size. A plain
+ * number of pixels is accepted too, as it is for a gap: nothing else in the
+ * diagram moving can make it wrong. The names stay the default because they
+ * follow the document's size when that is retuned, and a number does not.
  *
  * `small` is sampled rather than chosen. In
  * `examples/reference/arch.png` the box and container texts run 25
@@ -143,10 +143,17 @@ const DEFAULT_TEXT_SIZE = { none: 'small' };
 export function fontSizeFor(kind, textAttrs, fontSize, line) {
     const named = textAttrs['size'] ?? DEFAULT_TEXT_SIZE[kind] ?? 'normal';
     const scale = TEXT_SIZES[named];
-    if (scale === undefined) {
-        throw new SourceError(`size takes ${Object.keys(TEXT_SIZES).join(', ')}, not "${named}"`, line);
-    }
-    return Math.round(fontSize * scale);
+    if (scale !== undefined)
+        return Math.round(fontSize * scale);
+    if (/^\d+(\.\d+)?$/.test(named) && Number(named) > 0)
+        return Number(named);
+    const unit = named.match(/^(\d+(?:\.\d+)?)px$/);
+    const hint = unit
+        ? `; write "size: ${unit[1]}", a size's number is already in pixels`
+        : named.startsWith('-') || /^0+(\.0+)?$/.test(named)
+            ? '; a text size has to be more than zero'
+            : '';
+    throw new SourceError(`size takes ${Object.keys(TEXT_SIZES).join(', ')} or a number of pixels, not "${named}"${hint}`, line);
 }
 export const DEFAULT_MARGIN = 40;
 /**

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", "deck", "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,9 +30,9 @@ 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', 'deck', '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', 'deck', 'style'];
+const DECLARES_NAME = ['node', 'style'];
 /**
  * Every word that says something about where a thing goes. Assembled from the
  * lists the parser itself reads, so a direction or a passage axis added there

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/model.d.ts

@@ -57,9 +57,10 @@ export interface LayoutNode {
     /**
      * Whether things stack beside this node's text — below it, or above it when
      * the text is at the bottom. That is what a title band *is*, so it is what
-     * decides a container's look and its text's defaults, rather than whether
-     * the node has children: a node whose only child sits beside its text or in
-     * a corner has nothing stacked below the text, and draws as a leaf.
+     * decides its text's defaults, rather than whether the node has children: a
+     * node whose only child sits beside its text or in a corner has nothing
+     * stacked below the text, and its text sits as a leaf's does. Its *colors*
+     * follow having children, not this.
      */
     banded: boolean;
     /**