reladraw 0.8.0 → 0.9.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

@@ -1,28 +1,26 @@
 # reladraw
 
-A text language for diagrams where **you say where things go**.
+reladraw is a text language for diagrams where you say where things go.
 
-**[Try it in your browser →](https://reladraw.github.io/reladraw/)** — edit the source on the left, watch the layout re-solve on the right. Nothing to install.
+**[Try it in your browser →](https://reladraw.github.io/reladraw/)**
 
-A diagram drawn by hand in draw.io:
+I wanted to be able to create custom, expressive diagrams where I decided how to arrange the diagram, but without the inefficiency of manually drawing in draw.io. For example, this is a diagram drawn in draw.io:
 
-![The reference diagram, drawn by hand](https://raw.githubusercontent.com/reladraw/reladraw/main/examples/reference/arch.png)
+![Hand-drawn reference diagram](https://raw.githubusercontent.com/reladraw/reladraw/main/examples/reference/arch.png)
 
-And the same diagram written down in reladraw and rendered from the text — [`examples/arch.reladraw`](examples/arch.reladraw), 44 statements, no coordinates anywhere in it:
+This is the same diagram, but written in reladraw ([`examples/arch.reladraw`](examples/arch.reladraw)).
 
-![The same diagram, rendered from reladraw source](https://raw.githubusercontent.com/reladraw/reladraw/main/docs/arch-render.png)
+![reference diagram via reladraw](https://raw.githubusercontent.com/reladraw/reladraw/main/docs/arch-render.png)
 
-Every distance in the second picture was worked out from statements like `above-left of cluster.hub` and `between cluster.desktop1 and cluster.laptop1`. Nothing chose the arrangement; the file states it.
+## Why not Mermaid or draw.io?
 
-## The gap
+Mermaid, Graphviz and D2 let you declare boxes and connections, then determine positions for you. If you have a particular picture in mind, these aren't the right tool.
 
-Mermaid, Graphviz and D2 have you declare entities and connections, and then place everything for you. That is a superpower, and for most diagrams it is the right one. It stops being the right one as soon as you have a particular picture in mind and care where things go. Say you are actively building your understanding of a system by diagramming it, and you want some module over to the right with its connections placed just so: the auto-layout languages have no way to say it.
-
-On the other end of the spectrum are the absolute-positioning tools — draw.io, Excalidraw, Figma. They give you total control of placement, at the cost of making every edit to a complex diagram slow hand-work. And it is slow for a human but expensive for an agent, which has to work the picture out from the coordinates before it can decide which ones to change.
+On the other hand, tools like draw.io or Excalidraw allow absolute placement, but that means much more effort, whether for humans clicking and dragging nodes around or agents recalculating coordinates and editing verbose XML source code files.
 
 ![The two ends of the spectrum, with reladraw between them](https://raw.githubusercontent.com/reladraw/reladraw/main/docs/gap.png)
 
-reladraw aims at the middle. Every position is stated relative to something else, and nothing in the file is a coordinate:
+reladraw sits between those two extremes, aiming to have the benefits of a diagram language, like Mermaid, but also having the expressiveness and custom placement that you can get with draw.io. Positions are relative, so you don't have to manually pick coordinates. For example:
 
 ```
 node app "Web app"
@@ -34,41 +32,9 @@ node store "Database"  right of app  level with app
 edge app.api -> store  "queries"  from: right  to: left
 ```
 
-Nothing is nested, so no line depends on another line's position or indentation.
-
-The draft is in [SYNTAX.md](SYNTAX.md), with a worked example in [examples/](examples/).
-
-## Why an agent needs this
-
-The common case is not drawing a diagram, it is changing one. Ask for the auth service to move left and a queue to go behind it. With pixel coordinates, an agent has to rebuild the picture from the numbers before it can work out which numbers to change. With auto-layout there is nothing to read at all, because the arrangement was never written down — it can only reword the source and re-render. With stated placement the arrangement is in the file as sentences, and changing the picture is changing the sentence that says where the thing goes.
-
-Writing has the same shape. An agent emitting Mermaid is guessing at a layout that an algorithm settles later, and its only way to find out is to render and look — a round trip that comes back as a picture rather than as a list of what is wrong.
-
-Intent is confirmable, outcomes are not, and the difference is worth being precise about. An agent can re-read its own file and see that the database is under the API and all four machines hang off the sync hub. It cannot see that two clusters anchored to different things now overlap, that a text overflowed its node, or that an edge crosses four others — those are resolved from the statements rather than stated, so they need the diagnostics in the scope section below.
-
-### Using it with an agent
-
-reladraw is too new to be in any model's training data, so an agent has to be told the language before it can write it. This repository ships an [agent skill](https://agentskills.io) that does exactly that — the syntax, when to reach for the language, and what re-reading its own source can and cannot confirm.
-
-```
-npx skills add reladraw/reladraw -g
-```
-
-That installs it for whichever agent you use — Claude Code, Codex, Cursor, Copilot and others — each into its own skills directory. Drop the `-g` to install it into the current project instead.
-
-To install it for one agent rather than all of them, name it with `-a`:
-
-```
-npx skills add reladraw/reladraw -g -a claude-code
-```
-
-Re-run whichever command you used after a release that changes the syntax. The skill is a copy taken at install time, not a live link, so nothing refreshes it on its own.
-
-It is [plain Markdown](.claude/skills/reladraw/SKILL.md) with the syntax reference beside it, so it is worth reading whatever you use, and copying the directory by hand works just as well.
-
-## Status
+See also [SYNTAX.md](SYNTAX.md) and [examples/](examples/).
 
-Version 0.7.1. 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.
+## Install
 
 ```
 npm install -g reladraw
@@ -82,65 +48,32 @@ npm install && npm run build
 node dist/cli.js examples/arch.reladraw -o out.svg
 ```
 
-Not built yet, roughly in the order they are missed:
+## Using it with an agent
 
-- **The diagnostics report.** The scope section below says what it is for. Today the tool either renders or fails; it will not tell you what is wrong with a picture it drew successfully.
-- **Edge routing around nodes.** An edge can be told which side of a node to leave and arrive on, and which gap to run down on the way. An edge that says none of that is a straight line between two centers, and it will cut through whatever stands in the way.
-- **More pictures.** Icons and shapes are closed sets drawn from path data inside the tool, so a diagram wanting one that is not there has nowhere to go.
+To install a skill to let your agent know how to use reladraw:
 
-The language is not stable. Expect the syntax to change.
-
-## How it works
-
-A gap is a *minimum* distance, never an exact one. Say two things sit side by side, then say a third goes between them, and the first two are pushed apart by exactly what the third needs; delete the third and they close back up. That is the step an author otherwise does by hand — shove things apart to make room, then drag everything back so the diagram is not full of holes — and no number goes stale when a text grows.
-
-So the resolver solves a system rather than walking a chain. Each axis is a set of minimum distances, and the tightest arrangement satisfying all of them is found by longest paths: one answer, no search, no arrangement ever tried and rejected. The engine works out distances; which side of what a thing sits on came from the file.
-
-That is also what makes non-overlap affordable, so it holds for every pair of nodes without anyone writing it down. On its own "these two must not overlap" is a choice among four directions, which is the search this design refuses — but the file has usually settled it already: if your arrangement lets one node travel away from another and offers no way back, that is the only separation it permits. Where the file orders a pair on neither axis, the tool names them rather than guessing; where it orders them on both, the tie breaks toward the axis of least overlap, which is the smallest movement and the one place the tool decides something nobody wrote.
-
-Nothing is nudged. Each round derives the separations the file already implied, adds them as ordinary minimum distances, and solves the whole thing again from scratch — repairing a solved layout in place is the thing being avoided.
-
-## Scope for a first version
-
-- Parser *(done)*
-- Deterministic resolver: minimum distances in, tightest arrangement out *(done)*
-- Static SVG renderer *(done)*
-- A command-line tool: text file in, SVG out *(done)*
-- A placement grammar that can say what a real diagram needs: several placements on one node, one thing between two others, exact side-to-side alignment *(done)*
-- Nodes that do not overlap by default, with the separation direction derived from the stated arrangement *(done)*
-- Minimal node-avoiding edge routing
-- Machine-readable diagnostics from the solved geometry
-
-Diagnostics are a real output rather than a debugging aid. What they cannot do is stand in for the grammar: a check catches only what the language genuinely leaves open, and "these must not overlap" rules arrangements out without naming one, so it can never place anything. Everything the source cannot tell you is computable once the geometry is solved, with no image involved: overlapping nodes, crossed edges, text exceeding its container, anything off-canvas, large dead regions. So the tool reports `hub overlaps laptop1` and `edge auth->db crosses 4 edges`, and the fix is written in the same vocabulary as the source. An agent working this way reads a report about a text file it wrote and edits that text file — no rendering, no vision model, no pixel arithmetic.
-
-A diagnostic never repairs a solved layout in place. That is the line the design holds: a checker allowed to nudge nodes is a layout algorithm with a bad search strategy, fixing one overlap into the next with no view of the whole. Deriving a constraint the file already implied and solving the whole system again is a different thing, and is how non-overlap works. What is left over — anything the source genuinely does not settle — is reported, naming the statement that was broken, and the author edits the source. Open, and it decides how far this goes: may a diagnostic describe a fix in words, or only name the symptom? Describing one means the tool has an opinion about layout, which is the auto-layout instinct coming back in through the side door.
-
-Three design problems decide how much machinery this needs, and the first outranks the other two:
-
-**Saying enough.** The benchmark contains arrangements the grammar cannot express at all, which is why some nodes land in the wrong place no matter how the file is written. So the work is adding statements, not restricting them. Expressiveness is not the danger; the engine *choosing* an arrangement is.
-
-**What the engine is allowed to decide.** Auto-layout is refused, because a picture chosen by an algorithm is not predictable from its source, and that predictability is the entire point. Working out coordinates from an arrangement the author stated is a different thing and is simply the job. The test between them: the engine's freedom may affect distances and never relationships. If a default can change which side of something a node sits on, the language was short a statement and the tool should say so rather than guess.
-
-**Overlap and edge routing.** Relative placement with default spacing collides as soon as two clusters grow toward each other, and nodes are kept apart for exactly that reason. Edges are different: which side of a node a line passes is a relationship, so the tool does not pick a route around an obstacle by itself. You say where a line goes instead — the side it leaves and arrives on, the gap it runs through, the nodes it passes above or below — and the line is drawn curved, square or straight through those points. A line that crosses something it should not is one you have not said enough about yet. Whether the tool should at least point that out, naming the clause that would fix it, is an open question.
+```
+npx skills add reladraw/reladraw -g
+```
 
-## Prior art
+That installs it for every agent you use (Claude Code, Codex, Cursor, Copilot and others), each in its own skills directory. Leave off `-g` to install it into the current project only. To install it for just one agent, name it with `-a`:
 
-Four things sit near this, and each answers a different part of the problem.
+```
+npx skills add reladraw/reladraw -g -a claude-code
+```
 
-**[Archify](https://github.com/tt-a1i/archify).** Built for agents to write: an agent emits typed JSON, a validator checks it against a schema and lints the layout, and it compiles deterministically to a good-looking, self-contained HTML file, with stepped playback and nodes pinned to git-verified source lines. Its positioning is grid or free coordinates, though — auto-arrangement on one side, absolute pixels on the other — and a JSON template says nothing about where the picture will end up, so the loop is still emit, render, look, tweak.
+That gets you a copy of the skill at the time you run it, so you'll need to re-run that command to get the latest skill when there is a new release.
 
-**PIC and [pikchr](https://pikchr.org).** A text diagram format with no layout engine, where placement is stated and deterministic. But it is turtle graphics — a movable cursor that drops shapes and steps along — so a diagram is a sequence of pen movements rather than a set of stated relationships between named things. There is no group that reflows when a member is added.
+## Status
 
-**Graphviz `rank` and `cluster`.** Constraints on an auto-layout engine rather than a replacement for one, so output stays emergent and unpredictable from the source.
+Version 0.9.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.
 
-**Structurizr.** Has real manual layout, but is bound to the C4 model, which makes it a modeling notation with a renderer attached rather than a general placement language.
+The language isn't stable yet, so expect the syntax to change.
 
 ## License
 
-Apache-2.0. This is a reusable primitive where adoption is the value, so restricting commercial use would defeat the purpose. See [LICENSE](LICENSE).
-
-The license covers the code, not the name: it grants no rights to use "reladraw", the project logo, or the project's other marks. Forks are welcome and should carry a different name. See [NOTICE](NOTICE).
+Apache-2.0. See [LICENSE](LICENSE). The license covers the code, not the name. It grants no rights to "reladraw", the project logo or the project's other marks. See [NOTICE](NOTICE).
 
 ## Contributing
 
-Issues are wanted — especially a diagram you tried to write and could not. While the language is changing quickly, an issue is more useful than a pull request; [CONTRIBUTING.md](CONTRIBUTING.md) says why.
+Issues are welcome. Particularly helpful is a diagram you could not represent in reladraw. While the language is still changing quickly, an issue helps more than a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md).

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.7.1
+# Syntax reference — 0.9.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.
 
@@ -116,18 +116,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 +144,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 +395,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
 
@@ -442,6 +442,10 @@ Several such lines over the same row take a lane each, the shorter inside the lo
 
 Sides at right angles can face away too. `from: left  to: top` with the far node to the right leaves heading away from it, so the line steps out of the left, goes up past both nodes, runs along above them and comes straight down into the top. The side named at the far end says which way round: `to: bottom` takes it underneath instead.
 
+When the two nodes are stacked instead — `from: bottom  to: left` into a node directly below — going out past both and coming straight in would pass through the lower node. There the line is one curve, bending round the corner into the side named. If even the curve would cross a node, the line goes round the node on the side it names, as `left of` that node would send it.
+
+Both ends can name the same side. `from: left  to: left` with the far node to the right leaves heading away from it, and has to get round the node behind to reach the far side. It goes over the top, as the lines above do, and down into the gap; in a column, `from: bottom  to: bottom` goes round the right.
+
 Over the top is the rule, not a guess the tool makes each time — it does not look for the shorter way round. To send the line underneath or round the left, say which side of a node it passes: `below resolver`. See "Passing on one side of a node".
 
 #### Several edges between the same two sides
@@ -868,19 +872,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
 
@@ -917,15 +921,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
@@ -1017,7 +1056,21 @@ 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.
 
-**Unreleased**
+**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.
+
+- A fix, no syntax change. Children of a container stack close together, and an edge with no text between two of them used to get only that step, so it drew as an arrowhead with no line behind it. The gap now widens to show a short run of line behind each head, as an edge with text already did for its text. Existing diagrams with such an edge will look different, and correct.
+
+**0.8.0**
 
 - `shape: circle`. A circle is sized to hold its text and is always round. Edges on one of its sides spread round that quarter of the circle, and a corner of it is the point on the circle halfway round. It does not yet take a badge, a deck or a node placed against its own edge. Nothing that already renders changes.
 

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

@@ -59,6 +59,14 @@ export declare const THICKNESS: Record<string, number>;
  * thickness is a size, like a text's, and a size is allowed to take room.
  */
 export declare function arrowLength(thickness: number): number;
+/**
+ * Line left showing behind the head of an edge with no text, so a gap an arrow
+ * crosses is at least this plus its heads. Stacked children sit `CHILD_GAP`
+ * apart, which is less than one head, and an arrow between them drew as a head
+ * with no line. This is what the tightest named gap already leaves behind a
+ * normal head, so any gap an author could have asked for holds it unchanged.
+ */
+export declare const BARE_EDGE_RUN: number;
 /**
  * Line left showing between an edge's text and the box at that end of the
  * corridor it crosses.

package/dist/constants.js

@@ -71,6 +71,14 @@ export const THICKNESS = {
 export function arrowLength(thickness) {
     return ARROW_MARKER_WIDTH * thickness;
 }
+/**
+ * Line left showing behind the head of an edge with no text, so a gap an arrow
+ * crosses is at least this plus its heads. Stacked children sit `CHILD_GAP`
+ * apart, which is less than one head, and an arrow between them drew as a head
+ * with no line. This is what the tightest named gap already leaves behind a
+ * normal head, so any gap an author could have asked for holds it unchanged.
+ */
+export const BARE_EDGE_RUN = GAPS['tight'] - ARROW_LENGTH;
 /**
  * Line left showing between an edge's text and the box at that end of the
  * corridor it crosses.

package/dist/parser.js

@@ -1,7 +1,7 @@
 import { COLOR_KEYS, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, LINE_KEYS, LINE_VALUES, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, 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';
+import { THEME_COLORS, 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 = [];
@@ -142,7 +142,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 +183,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 +298,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 +342,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 +459,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 +841,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 +852,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));
@@ -1560,14 +1564,37 @@ function planLoops(edges, nodes, ends, corridors, routes, measurer, fontSize) {
         const { start, end } = ends.get(edge);
         if (start.side === undefined || end.side === undefined)
             continue;
-        // Sides at right angles, one facing away from the other end.
+        // Sides at right angles, one facing away from the other end. Going out
+        // past both boxes and coming straight in is right when the boxes are side
+        // by side. When the other end lies within the span of the box facing away
+        // — stacked boxes — coming straight in would pass through that box, so
+        // the curve is kept, which has room to bend round the corner; and if even
+        // the curve hits a box, the line goes round the facing-away box on the
+        // side it names.
         if (start.tx * end.tx + start.ty * end.ty === 0) {
+            const away = awayEnd(edge, start, end);
+            if (away && within(faceOf(away.node), away.anchor, away.other)) {
+                if (curveHits(edge, ends.get(edge), nodes)) {
+                    implyRoute(edge, away.node, sidePass(away.anchor.side), nodes, ends, routes, measurer, fontSize);
+                }
+                continue;
+            }
             const inWay = nodes.filter((node) => !(contains(node, edge.from) && contains(node, edge.to)));
             const plan = turnBack(edge, start, end, inWay, routes, measurer, fontSize);
             if (plan)
                 tops.push(plan);
             continue;
         }
+        // Both sides facing the same way, one box behind the other: the line has
+        // to get round that box to reach the far side, which a curve cannot. It
+        // goes over the top, or round the right for a column, as a loop does.
+        if (start.tx === end.tx && start.ty === end.ty) {
+            const away = awayEnd(edge, start, end);
+            if (away && curveHits(edge, ends.get(edge), nodes)) {
+                implyRoute(edge, away.node, start.tx !== 0 ? 'above' : 'right', nodes, ends, routes, measurer, fontSize);
+            }
+            continue;
+        }
         // The two ends point opposite ways along one axis, each away from the other.
         if (start.tx !== -end.tx || start.ty !== -end.ty)
             continue;
@@ -1755,6 +1782,90 @@ function turnBack(edge, start, end, inWay, routes, measurer, fontSize) {
         },
     };
 }
+/**
+ * Whether the single curve an edge would otherwise be drawn as passes through
+ * a box: either of its own, or any other that holds neither end. Measured on
+ * the curve itself, so the answer is the picture's and not a rule about which
+ * sides were named.
+ *
+ * Only passing through counts. Also counting a curve that merely comes close,
+ * or whose text touches a node, was tried (2026-09-27) and sent nearly every
+ * such edge the long way round with square corners, which the user rejected
+ * outright.
+ */
+function curveHits(edge, { start, end, bow }, nodes) {
+    const reach = controlReach(start, end);
+    const lift = 4 / 3;
+    const bx = (bow?.x ?? 0) * lift;
+    const by = (bow?.y ?? 0) * lift;
+    const c1 = { x: start.x + start.tx * reach + bx, y: start.y + start.ty * reach + by };
+    const c2 = { x: end.x + end.tx * reach + bx, y: end.y + end.ty * reach + by };
+    const at = (t) => {
+        const u = 1 - t;
+        return {
+            x: u * u * u * start.x + 3 * u * u * t * c1.x + 3 * u * t * t * c2.x + t * t * t * end.x,
+            y: u * u * u * start.y + 3 * u * u * t * c1.y + 3 * u * t * t * c2.y + t * t * t * end.y,
+        };
+    };
+    // The line starts and ends on its own boxes' sides, so those are shrunk a
+    // pixel to let it touch them there.
+    const boxes = [
+        ...[edge.from, edge.to].map((node) => grow(extentOfBox(faceOf(node)), -1)),
+        ...nodes
+            .filter((node) => !contains(node, edge.from) && !contains(node, edge.to))
+            .map((node) => extentOfBox(faceOf(node))),
+    ];
+    const steps = 32;
+    let previous = start;
+    for (let step = 1; step <= steps; step += 1) {
+        const point = at(step / steps);
+        if (boxes.some((box) => segmentHits(previous, point, box)))
+            return true;
+        previous = point;
+    }
+    return false;
+}
+/**
+ * The end of an edge whose side faces away from the other end, with its node
+ * and the other end's anchor; the start if both do.
+ */
+function awayEnd(edge, start, end) {
+    const facesAway = (from, to) => from.tx * (to.x - from.x) + from.ty * (to.y - from.y) < 0;
+    if (facesAway(start, end))
+        return { node: edge.from, anchor: start, other: end };
+    if (facesAway(end, start))
+        return { node: edge.to, anchor: end, other: start };
+    return undefined;
+}
+/**
+ * Whether a line coming straight in to `other`, across the way `anchor`'s side
+ * faces, would pass through `box` — that is, `other` lies within the box's
+ * span along that way.
+ */
+function within(box, anchor, other) {
+    const run = anchor.tx !== 0 ? 'x' : 'y';
+    return lo(box, run) < other[run] && other[run] < hi(box, run);
+}
+/** The clause that passes a node on the side named. */
+function sidePass(side) {
+    return side === 'top' ? 'above' : side === 'bottom' ? 'below' : side;
+}
+/**
+ * Route an edge as if it carried one clause the author did not write, passing
+ * `node` on that side. If that cannot be drawn, the edge keeps its curve: a
+ * refusal would name a clause that is not in the file, and would refuse a file
+ * earlier versions drew.
+ */
+function implyRoute(edge, node, direction, nodes, ends, routes, measurer, fontSize) {
+    const written = `${direction === 'left' || direction === 'right' ? `${direction} of` : direction} ${node.name}`;
+    try {
+        routes.set(edge, planRoute(edge, [{ direction, nodes: [node], written }], nodes, ends.get(edge), measurer, fontSize));
+    }
+    catch (error) {
+        if (!(error instanceof SourceError))
+            throw error;
+    }
+}
 /** The most a route's corner is rounded by. */
 const ROUTE_RADIUS = 20;
 /**
@@ -2547,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

@@ -1,5 +1,5 @@
 import { ALL_ATTR_KEYS, ATTR_KEYS, PART_SIDES, COLOR_KEYS, COLOR_PARTS, CONTENT_ALIGNMENTS, CONTENT_WIDTHS, LINE_VALUES, describePlacement, nameTarget, } from './ast.js';
-import { CHILD_GAP, DECK_STEP, DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, HEADER_GAP, ICON_GAP, ICON_LINES, TEXT_CLEARANCE, PAD, SEPARATION_GAP, THICKNESS, arrowLength, fontSizeFor, leafTop, textExtent, textStyleFor, widestLine, } from './constants.js';
+import { BARE_EDGE_RUN, CHILD_GAP, DECK_STEP, DEFAULT_FONT_SIZE, DEFAULT_MARGIN, GAPS, HEADER_GAP, ICON_GAP, ICON_LINES, TEXT_CLEARANCE, PAD, SEPARATION_GAP, THICKNESS, arrowLength, fontSizeFor, leafTop, textExtent, textStyleFor, widestLine, } from './constants.js';
 import { fix, reachability, tightest } from './constrain.js';
 import { SourceError } from './errors.js';
 import { bodyFor } from './icons.js';
@@ -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.
  */
@@ -1404,6 +1404,9 @@ function memberOn(target, axis) {
  * away together or not at all (`left right` with `from` first); sides at right
  * angles each may, and either is enough (`left top` with `from` first, where
  * the edge turns back over the top, or with `to` below, where it goes round).
+ * The same side on both is left out on purpose: that edge goes round the box
+ * behind, and its text rides on the stretch over that box and the gap, so the
+ * room made in the gap is what keeps a long text clear of the line's turns.
  */
 function facingAway(fromSide, toSide) {
     // The axis a side is on, and whether it faces away when its own end is first.
@@ -1450,22 +1453,34 @@ function liftTo(node, indexOf, local) {
         height: node.height,
     };
 }
-/** The edges with text whose two ends are different members of this group. */
+/** The edges whose two ends are different members of this group. */
 function corridorsIn(edges, locate, measurer, fontSize) {
     const corridors = [];
     for (const edge of edges) {
-        // An edge with no text asks for nothing: every gap holds an arrowhead. And a
-        // edge told to pass between two named things carries its text in *that*
+        // An edge told to pass between two named things carries its text in *that*
         // corridor rather than in the gap between its own ends, so widening this one
         // would make room where the text never goes.
         // An edge that says which side of something it passes is routed round it,
         // and its text rides on that route for the same reason.
-        if (edge.text === undefined || edge.between || edge.passes)
+        if (edge.between || edge.passes)
             continue;
         const from = locate(edge.from);
         const to = locate(edge.to);
         if (!from || !to || from.index === to.index)
             continue;
+        // With no text, the gap still has to show a run of line behind each head,
+        // or two stacked children with an arrow between them draw as a head alone.
+        if (edge.text === undefined) {
+            const bare = BARE_EDGE_RUN + arrowLength(edge.look.thickness) * (edge.both ? 2 : 1);
+            corridors.push({
+                edge,
+                from,
+                to,
+                need: { x: bare, y: bare },
+                away: facingAway(edge.attrs['from'], edge.attrs['to']),
+            });
+            continue;
+        }
         // The clearance is doubled because the text is drawn at the *midpoint* of
         // the line, so the room it needs is symmetric about that point whatever sits
         // at either end. The arrowhead is charged on both sides for the same reason:

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.0",
+  "version": "0.9.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {
@@ -34,6 +34,7 @@
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
+    "preversion": "./dev.sh check-version \"$npm_new_version\"",
     "dev": "tsc --watch",
     "example": "npm run build && node dist/cli.js examples/arch.reladraw -o examples/out/arch.svg"
   },