reladraw 0.12.0 → 0.14.0

package/README.md

@@ -82,7 +82,7 @@ That gets you a copy of the skill at the time you run it, so you'll need to re-r
 
 ## Status
 
-Version 0.12.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, and an element that does the same inside a web page.
+Version 0.14.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, and an element that does the same inside a web page.
 
 The language isn't stable yet, so expect the syntax to change.
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.12.0
+# Syntax reference — 0.14.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.
 
@@ -396,12 +396,55 @@ Separation leaves a tight gap, deliberately small — enough to read as two node
 ## Edges
 
 ```
-edge <from> -> <to> ["<text>"] [between <a> and <b> [vertically|horizontally]] [attributes]
-edge <to> <- <from> ["<text>"] [between <a> and <b> [vertically|horizontally]] [attributes]
-edge <from> <-> <to> ["<text>"] [between <a> and <b> [vertically|horizontally]] [attributes]
+edge <from> <arrow> <to> ["<text>"] [between <a> and <b> [vertically|horizontally]] [attributes]
 ```
 
-`a <- b` is exactly `b -> a` — same arrow, same picture. What changes is which name you write first, and that is worth having: the first name reads as the subject of the line, and plenty of edges are about the thing the arrow points at rather than the thing it leaves. `from:` and `to:` follow the arrow, not the writing order, so they still name the tail and the head.
+```
+edge a -> b       // an arrow at b
+edge a <- b       // an arrow at a
+edge a <-> b      // one at each end
+edge a -- b       // a plain line
+```
+
+`a <- b` draws the same picture as `b -> a`. What changes is which name you write first, and that is worth having: the first name reads as the subject of the line, and plenty of edges are about the thing the arrow points at rather than the thing it leaves. **`from:` and `to:` follow the writing order**, never the arrow: `from:` is always the first name's side and `to:` the second's, whichever way the arrow points.
+
+### What is drawn at each end
+
+The arrow is a mark, a line, a mark. The line is `-` or `--`, the two meaning the same, and either mark may be left off. A mark is a word, or a glyph that stands for one:
+
+| mark | draws | glyph |
+|---|---|---|
+| `arrow` | a filled arrowhead | `>` at the right end, `<` at the left |
+| `oarrow` | an outlined arrowhead | `\|>` at the right end, `<\|` at the left |
+| `dot` | a filled circle | `*` |
+| `odot` | an outlined circle | `o` |
+| `diamond` | a filled diamond | |
+| `odiamond` | an outlined diamond | |
+| `bar` | a stroke across the line | `\|` |
+| `none` | nothing | |
+
+The `o` in front means outlined, for every shape. A glyph that points is spelled the way it points, which is why `<->` reads as it does. So these are all the same arrow, and you write whichever reads best to you:
+
+```
+edge a o--> b
+edge a odot--arrow b
+edge a (odot)--(arrow) b
+edge a [odot] -- [arrow] b
+```
+
+A mark touches the dashes or is in brackets. `edge a -- dot b` is an error, because it reads just as well as a plain line to a node named `dot`.
+
+**Marks as attributes.** `from-mark:` and `to-mark:` say the same thing, one end at a time, and they are how a style carries marks:
+
+```
+style inherits  to-mark: oarrow
+edge dog -- animal  style: inherits
+edge cat -- animal  style: inherits
+```
+
+**An end with nothing written is left open, not empty.** `dog -- animal` is plain until something says otherwise, and here the style does. `none` is the word for "nothing at this end, whatever the style says": `edge a none--> b`, or `from-mark: none`.
+
+**A mark written in the arrow is final.** The edge's own `to-mark:` may repeat it but not contradict it — `edge a --> b  to-mark: dot` is an error, since both halves are on one line and one of them would be dead text. A style fills only the ends the arrow leaves open: a style giving every end a `bar`, applied to `a --> b`, draws a bar at `a` and still the arrow at `b`.
 
 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.
 
@@ -439,7 +482,7 @@ The space it leaves is deliberately small, and shrinks further if the side is to
 
 #### Going round boxes
 
-A line never passes through a box. It takes the shortest way between its ends that goes through none, leaving a named side heading straight out and arriving at one heading straight in, with as few turns as that length allows. When the direct line is clear, that is the line you get. When it is not, the line goes round whatever is in the way. A line you have steered with `between` or `below <node>` keeps to what you said instead.
+A line never passes through a box. It takes the shortest way between its ends that goes through none, leaving a named side heading straight out and arriving at one heading straight in, with as few turns as that length allows. When the direct line is clear, that is the line you get. When it is not, the line goes round whatever is in the way. A line you have steered with `between` or `below <node>` finds its way the same way, keeping to what you said as well.
 
 ```
 node parser "Parser"
@@ -452,9 +495,9 @@ That line leaves Parser heading left and has to arrive at Renderer from the righ
 
 The same rule covers every other case: sides at right angles where one faces away from the other end, two ends naming the same side with one node behind the other, a node back to itself, and a line with no side named that has a box between its ends. Each goes the shortest way round. An end with no side named leaves or arrives by whichever of its box's sides makes the way shortest.
 
-Several lines along the same stretch take a lane each, side by side, instead of drawing on top of one another. The text rides on the line's longest straight piece that it does not land on a box from, and never changes which way the line goes.
+Several lines along the same stretch take a lane each, side by side, instead of drawing on top of one another, nested so that none crosses another where it need not. Where one of them carries its text on that stretch, the others keep clear of the text as well as the line. The text rides on the line's longest straight piece that it does not land on a box from, and never changes which way the line goes.
 
-A curved line and a square one take the same way; the curved one sweeps its turns. At an arrowhead, the line always finishes straight, so the head points square into the side.
+A curved line and a square one take the same way. The square one turns at corners. The curved one sweeps through them, each sweep as wide as the room around it allows without coming near a box or another line, and a line stepping sideways and carrying on the way it was going is one S. Where the room is tight a sweep comes close to a rounded corner; where there is room it flows. At an arrowhead or any other mark, the line always finishes straight, so the mark points square into the side.
 
 When there is no way at all — the side you named is flush against another box — the file is refused with the reason: `edge a -> b: cannot leave a's right side, b is against it`.
 
@@ -507,7 +550,7 @@ The bow is the shortfall, not a style — nothing bends until the side is full,
 edge dumps.db1 -> hub  "rclone"  between desktop1 and laptop1  from: right  to: left
 ```
 
-It says nothing about the rest of the line. The clause binds only the stretch where the line is actually passing that pair — where it enters the span the two of them occupy, it is in the gap between them, and before and after it goes wherever its ends take it. The line is drawn as a curve into the gap, a straight run along it, and a curve out to its far end.
+It says nothing about the rest of the line. The clause binds only the stretch where the line is actually passing that pair — where it enters the span the two of them occupy, it is in the gap between them, and before and after it goes wherever its ends take it. The line takes the shortest way into the gap that goes round every box and keeps its distance from them, runs straight along it, and takes the shortest way out to its far end, as any line does (see "Going round boxes"). Its text rides in the gap.
 
 Which gap is meant is usually derived, not stated. One of the two is above the other, or one is left of the other, and whichever it is says which axis the gap binds — so a channel between something above and something below constrains height, and one between something left and something right constrains width, and in neither case does the file mention an axis at all.
 
@@ -521,7 +564,7 @@ edge c -> d  "threaded"  between a and b vertically
 
 Leave it out on a diagonal pair and the error asks for it, in your own node names. Write it where it was not needed and it is checked rather than quietly dropped, so a pair that is only apart vertically will tell you that `horizontally` is wrong. A pair that touches or overlaps has no gap at all, whatever you write, and naming a pair the edge never actually passes is an error too.
 
-Several edges may share one channel, and they take a lane each. As with attachments on a side, which edge gets which lane is derived from where their ends sit, so lines through a channel come out in the order their ends are in and do not cross. The lanes are spaced by what is actually running along them: a text's depth where an edge with text runs, an arrow's width where none does.
+Several edges may share one channel, and they take a lane each, found as every line's lane is (see "Going round boxes"): side by side, arranged so they do not cross where they need not. The lanes are spaced by what is actually running along them: clear of a text where an edge with text runs, an arrow's width apart where none does.
 
 A named channel does not widen. It is measured off the layout you described, so if you name a gap too narrow for the lines you put through it they crowd together rather than pushing the two nodes apart. That is the difference between this and a text making room for itself, above: there, the corridor is the gap between the edge's own two ends, and opening it moves them apart exactly as anything else put between them would. Here the pair is named by an edge merely passing through, and nothing yet lets an edge bid into a gap it is only a visitor in. It is the remaining half and it is not built.
 
@@ -546,7 +589,7 @@ node b "B"  below a
 edge a -> b  from: top  to: bottom  left of a  right of b
 ```
 
-That line leaves the top of A, goes round A's left, crosses over in the gap between the two, passes B on the right, and turns up into B's bottom. The line is drawn as straight stretches joined by rounded corners, each stretch as close to the two ends as its clauses allow, and pushed further out, the way its clause already points, by any node sitting on it.
+That line leaves the top of A, goes round A's left, crosses over in the gap between the two, passes B on the right, and turns up into B's bottom. It finds its way as any line does (see "Going round boxes"): each clause closes off one side of its node — `below resolver` everything above Resolver, within Resolver's width — and the line takes the shortest way that keeps out of those as well as out of every box. Lines told the same things take a lane each rather than one path between them.
 
 One clause may name several nodes, and it is not shorthand for several clauses. `below a and b` is below the box bounding both, so it covers the stretch between them too:
 
@@ -563,15 +606,15 @@ One edge may pass some nodes above or below and others left or right. Passing ab
 
 ```
 node a "A"
-node m "M"  right of a
-node n "N"  below m  right of m
-node b "B"  below n  right of n
-edge a -> b  below m  left of n
+node n "N"  below a
+node m "M"  below n
+node b "B"  right of m  (gap: 80)
+edge a -> b  left of n  above m
 ```
 
-That line leaves the bottom of A, runs across just under M, turns down on N's left, and runs across into B. The clauses read as before: `left of n` binds only where the line is level with N, so the last stretch passing under N is not held to it.
+With no clauses that line would run straight from A to B. `left of n` sends it down N's left, and `above m` brings it across between N and M into B, rather than round under M. The clauses read as before: `left of n` binds only where the line is level with N, so the stretch running across below N is not held to it.
 
-A side named at an end says which way the line goes first: `from: right` starts it across, `from: bottom` starts it down. With no side named at either end it goes across first, then down.
+A side named at an end says which way the line goes first: `from: right` starts it across, `from: bottom` starts it down. With no side named, the line takes whichever way keeps the clauses with the fewest turns, and a straight line that already keeps them stays straight.
 
 Clauses of one kind may sit on different legs. Here the line goes over P on the way out, down past N, and under M on the way in, turning twice:
 
@@ -591,11 +634,11 @@ Refused, each by name:
 - **Clauses that cannot all hold** at one point, as above.
 - **A crossing with no room.** Two clauses on opposite sides need a gap between their nodes to cross over in. Placed flush — `gap: 0` — there is none, and the error says to give the placement a gap or drop a clause. The gap is never opened for the line: you wrote how far apart those two are.
 - **A node the line never passes.** `below z` on a line that never goes by Z says nothing.
-- **Both kinds where no way of turning keeps them all.** The error names the clauses, or the one reason if every way fails for the same one.
+- **No way keeps them all.** Where the clauses and the boxes between them leave no way through, the error names every clause.
 - **`between` with a side.** An edge passing between two things already has a side of each.
 - **A part of a node, or a gap.** A line passes a whole box, and passes it as close as reads clearly.
 
-An end with no side named leaves from the side facing where the line is going.
+An end with no side named leaves by whichever side makes the way shortest.
 
 ### How the line is drawn
 
@@ -769,6 +812,7 @@ Every attribute, and what takes one. The kinds here are what a node's **body** i
 | `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 |
+| `from-mark` `to-mark` | | | | ✓ | what is drawn at each end — see "What is drawn at each end" |
 | `fill` | ✓ | | | | color — see "A color names the part it colors" |
 | `border` | ✓ | | | | color |
 | `text` | ✓ | ✓ | ✓ | ✓ | the text's properties, in brackets — a style's form of what a node or an edge writes after its own words |
@@ -849,7 +893,7 @@ A color attribute says which part of a thing it colors, and a part exists only o
 | `fill` | the area inside the outline | a node |
 | `border` | the outline | a node |
 | `text: (color: …)` | the text | every node, and an edge |
-| `line` | the drawn line and its arrowheads | an edge |
+| `line` | the drawn line and the marks at its ends | an edge |
 
 A word written on a kind that has no such part is refused by name, and the error lists the parts that kind does have — `border:` on a node with no body is a mistake, not something to ignore, for the same reason an unknown `diagram` key is.
 
@@ -1068,6 +1112,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.
 
+**0.14.0**
+
+One breaking change: on an edge written with `<-`, `from:` and `to:` now name the sides of the first and second names written. They used to follow the arrow, so `disk <- writer  from: bottom` meant Writer's bottom; it now means Disk's. Swap the two on any `<-` edge that names a side. No other file draws differently.
+
+- A line can have no arrowhead: `edge a -- b`, or `edge a - b`.
+- Each end of a line can carry a mark: an arrowhead filled or outlined, a dot, a diamond or a bar, written in the arrow (`a o--> b`, `a diamond--arrow b`) or as `from-mark:` and `to-mark:`, which a style can carry. See "What is drawn at each end".
+
+**0.13.0**
+
+No syntax changes, and no file that worked is refused. Lines move: every line that goes round something, and every line with `below`/`above`/`left of`/`right of` or `between`, may be drawn differently.
+
+- A fix, no syntax change. Lines told which side of a node to pass (`below a`) or which gap to go through (`between a and b`) now find their way as every other line does, so they take lanes and keep their distance from boxes, and two lines through one gap no longer cross where they need not. Several identical `below a` lines used to be drawn on one path, reading as one line with three arrowheads, and a `between` line could run a couple of pixels from a box and come into its target down the target's own edge.
+- A curved line that goes round something now sweeps through its turns instead of cornering, as widely as the room allows; a line that steps sideways and carries on is one S. `path: square, corners: rounded` is the way to get the cornered look. Existing diagrams with a line going round a box, a clause or a `between` will look different.
+- A line with `below`/`left of` clauses that its direct shape already keeps is drawn direct, as a line without them would be, rather than always with corners. Where it does have to turn, it takes the fewest turns that keep every clause; the old "across first, then down" rule no longer decides. A line told `below m` that would otherwise never reach M's underside is now sent round under M.
+
 **0.12.0**
 
 - Diagrams can be written straight into a web page. Load `dist/element.js` from the package, and each `<reladraw-diagram>` element is drawn in place from the source inside it, with `theme=` choosing the colors. See "In a web page" in the README.
@@ -1156,7 +1215,7 @@ Pre-1.0, so the minor number is where a breaking change goes. Every removal belo
 
 Open questions the benchmark raised, recorded so a later session does not rediscover them.
 
-- ~~One edge passing some nodes above or below and others left or right — an L-shaped line, across under one node and then down past another — is refused today.~~ Answered in 0.6.0: such an edge turns between the two kinds as few times as it can, and where two orders both fit, a standing rule picks — a side named at an end says which way the line goes first, and with none named it goes across first. See "Passing on one side of a node" above.
+- ~~One edge passing some nodes above or below and others left or right — an L-shaped line, across under one node and then down past another — is refused today.~~ Answered in 0.6.0: such an edge turns between the two kinds as few times as it can, and where two orders both fit, a standing rule picks — a side named at an end says which way the line goes first, and with none named it goes across first. Since 0.13.0, such a line takes whichever way keeps its clauses with the fewest turns, and the across-first rule no longer applies. See "Passing on one side of a node" above.
 - Named gaps are the first step toward numbers, but making them minimums took most of the pressure off: they now set how much a diagram breathes, never whether something fits. Whether four names is the right number is still open.
 - Four machines each holding a `files` child with the same text means writing the same line four times. This is the strongest case for a set-level declaration, for terseness rather than for placement.
 - The 2×2 arrangement around a hub is four independent statements, so a fifth machine has no slot to reflow into. There are only eight directions.

package/dist/ast.d.ts

@@ -276,12 +276,34 @@ export interface NodeStmt {
     attrs: Attrs;
     line: number;
 }
+/**
+ * What may be drawn at an end of a line. The `o` prefix is the outlined form of
+ * the shape, one rule for every shape; `none` says there is definitely nothing,
+ * where an end with no mark written leaves it to a style.
+ */
+export declare const MARKS: readonly ["arrow", "oarrow", "dot", "odot", "diamond", "odiamond", "bar", "none"];
+export type Mark = (typeof MARKS)[number];
+/**
+ * The glyphs that stand for a mark, by the end they are written at. A glyph
+ * that points is spelled the way it points, so `<` is the arrow at the left end
+ * and `>` the one at the right, which is what makes `<->` read. The diamonds
+ * have none: nothing would explain itself, and `<>` is two arrows.
+ */
+export declare const MARK_GLYPHS: Record<'from' | 'to', Record<string, Mark>>;
+/** The marks written in an edge's arrow, by end. An end with none written is absent. */
+export interface EdgeMarks {
+    from?: Mark;
+    to?: Mark;
+}
 export interface EdgeStmt {
     kind: 'edge';
+    /** The first name written. `from:` and `to:` follow writing order, never the arrow. */
     from: string;
     to: string;
-    /** `<->` rather than `->`. */
-    both: boolean;
+    /** The arrow as written, `->` or `o--odiamond`, for quoting back. */
+    arrow: string;
+    /** The marks the arrow writes at each end: `->` is an arrow at `to`, `<-` one at `from`. */
+    marks: EdgeMarks;
     text?: string;
     /** The text's bracketed modifiers, as written. Usually empty. */
     textAttrs: Attrs;

package/dist/ast.js

@@ -240,6 +240,22 @@ export const LINE_VALUES = {
     pattern: ['solid', 'dashed', 'dotted', 'dash-dot'],
     thickness: ['normal', 'thin', 'thick'],
 };
+/**
+ * What may be drawn at an end of a line. The `o` prefix is the outlined form of
+ * the shape, one rule for every shape; `none` says there is definitely nothing,
+ * where an end with no mark written leaves it to a style.
+ */
+export const MARKS = ['arrow', 'oarrow', 'dot', 'odot', 'diamond', 'odiamond', 'bar', 'none'];
+/**
+ * The glyphs that stand for a mark, by the end they are written at. A glyph
+ * that points is spelled the way it points, so `<` is the arrow at the left end
+ * and `>` the one at the right, which is what makes `<->` read. The diamonds
+ * have none: nothing would explain itself, and `<>` is two arrows.
+ */
+export const MARK_GLYPHS = {
+    from: { '<': 'arrow', '<|': 'oarrow', '*': 'dot', o: 'odot', '|': 'bar' },
+    to: { '>': 'arrow', '|>': 'oarrow', '*': 'dot', o: 'odot', '|': 'bar' },
+};
 /**
  * The attributes a `diagram` statement understands. `text` takes a bracket,
  * `text: (color: …)`, and sets the text color of everything at once — the
@@ -333,7 +349,7 @@ export const ATTR_KEYS = {
     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'],
+    edge: ['style', 'from', 'to', 'from-mark', 'to-mark', 'line', 'text', 'url'],
 };
 /**
  * Every word that is an attribute *somewhere*, which is what separates a

package/dist/grammar.d.ts

@@ -38,7 +38,7 @@ export type TokenKind =
  | 'keyword'
 /** The name a statement declares, right after its keyword. */
  | 'name'
-/** `->` and `<->`. */
+/** `->`, `<-`, `<->`, and `--` or `-` for a plain line. */
  | 'arrow'
 /** Placement and edge vocabulary: `right`, `of`, `level`, `with`, `and`, `between`, … */
  | 'relation'
@@ -71,19 +71,11 @@ export declare const STATEMENT_KEYWORDS: readonly ["node", "edge", "style", "dia
  * colors here without anybody remembering to come back.
  */
 export declare const RELATION_WORDS: string[];
-/**
- * The patterns, as source strings, so a generator can emit them into another
- * editor's grammar without reaching into a compiled RegExp. Each is written to
- * match at the point the scanner has reached; the scanner adds the sticky flag.
- *
- * A name may contain dots (containment) and hyphens, which is why the word
- * pattern is what it is rather than `\w+`.
- */
 export declare const PATTERNS: {
     readonly comment: "\\/\\/.*";
     readonly string: "\"(?:\\\\.|[^\"\\\\])*\"?";
     readonly keyword: `(?:${string})\\b`;
-    readonly arrow: "<->|->|<-";
+    readonly arrow: `${string}?-{1,2}${string}?(?=[ \\t]|$)`;
     readonly attribute: "[A-Za-z][A-Za-z0-9_-]*:";
     readonly color: "#[0-9A-Fa-f]{3,8}\\b";
     readonly relation: `(?:${string})\\b`;

package/dist/grammar.js

@@ -26,7 +26,7 @@
  * editor formats need and the reason a `.reladraw` grammar is small in all of
  * them.
  */
-import { DIRECTIONS, POSITIONS, SIDES, PASSAGE_AXES } from './ast.js';
+import { DIRECTIONS, MARKS, POSITIONS, SIDES, PASSAGE_AXES } from './ast.js';
 /**
  * The words a statement may open with. `parseStatement` in `parser.ts` is the
  * authority — its switch is what actually accepts them — and this list mirrors
@@ -71,6 +71,9 @@ function alternation(words) {
  * A name may contain dots (containment) and hyphens, which is why the word
  * pattern is what it is rather than `\w+`.
  */
+/** One end of an arrow: a mark word or glyph, bare or bracketed. Words first, so `odot` is not `o`. */
+const MARK_WORD = `(?:${[...MARKS].sort((a, b) => b.length - a.length).join('|')}|<\\||\\|>|[<>*o|])`;
+const ARROW_MARK = `(?:\\[${MARK_WORD}\\]|\\(${MARK_WORD}\\)|${MARK_WORD})`;
 export const PATTERNS = {
     comment: '\\/\\/.*',
     // The closing quote is optional: every string is unterminated for as long as
@@ -78,8 +81,10 @@ export const PATTERNS = {
     // rest of the file on every keystroke.
     string: '"(?:\\\\.|[^"\\\\])*"?',
     keyword: `(?:${alternation(STATEMENT_KEYWORDS)})\\b`,
-    // `<->` first, or `<-` would match its opening half and leave a stray `>`.
-    arrow: '<->|->|<-',
+    // A mark, one or two dashes, a mark — `->`, `o--odiamond`, `[dot]-`. It must
+    // end the token, so a hyphenated name stays a word. A mark written apart in
+    // brackets, `[dot] -- [arrow]`, colors as plain words either side of `--`.
+    arrow: `${ARROW_MARK}?-{1,2}${ARROW_MARK}?(?=[ \\t]|$)`,
     attribute: '[A-Za-z][A-Za-z0-9_-]*:',
     color: '#[0-9A-Fa-f]{3,8}\\b',
     relation: `(?:${alternation(RELATION_WORDS)})\\b`,

package/dist/model.d.ts

@@ -1,4 +1,4 @@
-import type { Attrs, Axis, Direction, Kind, Placement } from './ast.js';
+import type { Attrs, Axis, Direction, Kind, Mark, Placement } from './ast.js';
 import type { Line } from './text.js';
 import type { Body } from './icons.js';
 /** A `between` clause with its targets resolved. Mirrors `Passage` in `ast.ts`. */
@@ -115,7 +115,11 @@ export interface LayoutNode {
 export interface LayoutEdge {
     from: LayoutNode;
     to: LayoutNode;
-    both: boolean;
+    /** What is drawn at each end, settled: the arrow, then the edge's own attributes, then its style. */
+    marks: {
+        from: Mark;
+        to: Mark;
+    };
     text?: string;
     /** The text split into the lines that will be drawn, each as its runs. */
     lines?: Line[];

package/dist/parser.js

@@ -1,4 +1,4 @@
-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 { COLOR_KEYS, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, LINE_KEYS, LINE_VALUES, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, MARKS, MARK_GLYPHS, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { SourceError } from './errors.js';
 import { STATEMENT_KEYWORDS } from './grammar.js';
 import { isAttrKey, tokenizeLine } from './lexer.js';
@@ -516,27 +516,109 @@ function parseNode(head, line) {
         line,
     };
 }
+const NEEDS_ARROW = 'an edge needs a line between its endpoints: "->", "<-", "<->" or "--"';
 /**
- * `edge <from> -> <to> ["<text>"] [between <a> and <b>]`, with `<->` for a
- * two-headed arrow and `<-` for one pointing the other way.
+ * The arrow between an edge's two names: a mark, a shaft, a mark. The shaft is
+ * `-` or `--`, and either mark may be left off, so `--` is a plain line and
+ * `<->` an arrow at each end.
  *
- * `a <- b` is exactly `b -> a` and carries no meaning of its own downstream.
- * What it buys is the ordering: the name written first is the one the line is
- * about, and plenty of edges have the target as their subject.
+ * A mark is a word or a glyph, bare or in `()` or `[]`, and it must touch the
+ * dashes or be bracketed: `edge a -- dot b` would otherwise read like a line to
+ * a node named `dot`. So a bracketed mark may stand apart, which is why the
+ * arrow can span several tokens — `[dot] -- [arrow]` is three, and `(dot)` is
+ * three on its own, since the lexer splits a bracket that opens a token.
+ */
+function readArrow(head, line) {
+    let at = 2;
+    const pieces = [];
+    const bracketed = () => {
+        const token = head[at];
+        if (!token || token.quoted)
+            return;
+        if (token.text === '(' && head[at + 2]?.text === ')' && !head[at + 1].quoted) {
+            pieces.push(`(${head[at + 1].text})`);
+            at += 3;
+        }
+        else if (/^\[[^\]]*\]$/.test(token.text)) {
+            pieces.push(token.text);
+            at += 1;
+        }
+    };
+    bracketed();
+    const shaft = head[at];
+    if (!shaft || shaft.quoted || !shaft.text.includes('-'))
+        throw new SourceError(NEEDS_ARROW, line);
+    pieces.push(shaft.text);
+    at += 1;
+    if (shaft.text.endsWith('-'))
+        bracketed();
+    const text = pieces.join('');
+    const parts = /^([^-]*)(-+)([^-]*)$/.exec(text);
+    if (!parts) {
+        throw new SourceError(`"${text}" is not an arrow — the line is one run of dashes, with a mark at either end`, line);
+    }
+    if (parts[2].length > 2) {
+        throw new SourceError(`"${text}" has ${parts[2].length} dashes — the line is "-" or "--"`, line);
+    }
+    const from = readMark(parts[1], 'from', text, line);
+    const to = readMark(parts[3], 'to', text, line);
+    return {
+        text,
+        marks: { ...(from !== undefined ? { from } : {}), ...(to !== undefined ? { to } : {}) },
+        next: at,
+    };
+}
+/** One end of an arrow, as written: a mark word or glyph, perhaps bracketed, or nothing. */
+function readMark(written, end, arrow, line) {
+    if (written === '')
+        return undefined;
+    const inner = /^\((.*)\)$/.exec(written)?.[1] ?? /^\[(.*)\]$/.exec(written)?.[1] ?? written;
+    if (MARKS.includes(inner))
+        return inner;
+    const glyph = MARK_GLYPHS[end][inner];
+    if (glyph !== undefined)
+        return glyph;
+    const other = end === 'from' ? 'to' : 'from';
+    const turned = MARK_GLYPHS[other][inner];
+    if (turned !== undefined) {
+        // A pointing glyph written at the end it points away from: `>--` or `--<`.
+        const right = Object.entries(MARK_GLYPHS[end]).find(([, mark]) => mark === turned)[0];
+        throw new SourceError(`"${arrow}": "${inner}" points the other way — at the ${end === 'from' ? 'left' : 'right'} end ` +
+            `the ${turned} is "${right}", or write the word "${turned}"`, line);
+    }
+    throw new SourceError(`"${arrow}": "${inner}" is not a mark. The marks are ${MARKS.join(', ')}, and the glyphs ` +
+        `${Object.keys(MARK_GLYPHS.to).join(' ')} and ${Object.keys(MARK_GLYPHS.from).filter((g) => !(g in MARK_GLYPHS.to)).join(' ')}`, line);
+}
+/**
+ * `edge <from> <arrow> <to> ["<text>"] [between <a> and <b>]`. The arrow is
+ * read by `readArrow`.
+ *
+ * `from` and `to` are the order the names are written in, never the arrow's
+ * direction: `a <- b` is `a` then `b` with an arrow at `a`. With a mark at each
+ * end many lines have no direction at all, and the written order is the one
+ * every edge has — so `from:` names the first name's side on every edge.
  */
-const ARROWS = ['->', '<->', '<-'];
 function parseEdge(head, line) {
     const left = requireName(head[1], 'edge', line);
-    const arrow = head[2];
-    if (!arrow || arrow.quoted || !ARROWS.includes(arrow.text)) {
-        throw new SourceError('an edge needs "->", "<-" or "<->" between its endpoints', line);
-    }
-    const rightToken = head[3];
+    const arrow = readArrow(head, line);
+    const rightToken = head[arrow.next];
     if (!rightToken || rightToken.quoted) {
         throw new SourceError('an edge needs a node on the right of the arrow', line);
     }
-    const back = arrow.text === '<-';
-    let at = 4;
+    let at = arrow.next + 1;
+    const stray = head[at];
+    if (stray &&
+        !stray.quoted &&
+        !isAttrKey(stray) &&
+        stray.text !== '(' &&
+        stray.text !== 'between' &&
+        !isDirection(stray.text) &&
+        (MARKS.includes(rightToken.text) || Object.hasOwn(MARK_GLYPHS.to, rightToken.text))) {
+        // `edge a -- dot b`: a mark standing apart, which reads as a node named
+        // `dot`. Said outright rather than left to the "not a direction" error.
+        throw new SourceError(`edge ${left} ${arrow.text} ${rightToken.text} ${stray.text}: a mark touches the dashes or is ` +
+            `in brackets — write "${arrow.text}${rightToken.text}" or "${arrow.text} [${rightToken.text}]"`, line);
+    }
     const textToken = head[at]?.quoted ? head[at] : undefined;
     if (textToken)
         at += 1;
@@ -603,9 +685,10 @@ function parseEdge(head, line) {
     return {
         kind: 'edge',
         textAttrs: bracket.values,
-        from: back ? rightToken.text : left,
-        to: back ? left : rightToken.text,
-        both: arrow.text === '<->',
+        from: left,
+        to: rightToken.text,
+        arrow: arrow.text,
+        marks: arrow.marks,
         ...(textToken ? { text: textToken.text } : {}),
         ...(between ? { between } : {}),
         ...(passes.length > 0 ? { passes } : {}),