reladraw 0.19.1 → 0.21.0

package/README.md

@@ -45,7 +45,7 @@ npm install -g reladraw
 reladraw render diagram.reladraw -o diagram.svg
 ```
 
-`reladraw check diagram.reladraw` prints the warnings without writing a picture, and `reladraw format diagram.reladraw` lines its statements up in columns.
+`reladraw check diagram.reladraw` prints the warnings without writing a picture, and `reladraw format diagram.reladraw` lines its statements up in columns. `reladraw render diagram.reladraw --page` writes a page for looking at it in a browser, with pan, zoom, full screen and the warnings beside it.
 
 Or from a clone, which also gets you the examples:
 
@@ -88,7 +88,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.19.1. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG, and an element that does the same inside a web page.
+Version 0.21.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.
 
 ## License
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.19.1
+# Syntax reference — 0.21.0
 
 What the language accepts. The changelog at the end lists what changed in each published version; 0.17.0's changes are large, and its entry has a table of every old spelling and what to write instead.
 
@@ -220,7 +220,7 @@ The text keeps its own position words, so `node d1 "Desktop 1 / Linux" (inside t
 
 With an empty text, `node flag "" badge: disk`, the node is exactly the picture and its padding, since an empty text takes no room.
 
-**A picture that is a thing of its own is a child**, placed like any other: `node drive.mark  icon: disk  inside drive top-right` in a corner. Placed against the text without `join-with:`, it is not part of the label: the text stays where it would be without it, and the box grows to hold both.
+**A picture that is a thing of its own is a child**, placed like any other: `node drive.mark  icon: disk  1 right of drive text` beside the text. Placed against the text without `join-with:`, it is not part of the label: the text stays where it would be without it, and the box grows to hold both. In the corner of a box its other children size, `node laptop.mark  icon: laptop  inside laptop top-right  stays above laptop.photos` ([Against its own parent](#against-its-own-parent)). A corner of a box with nothing in it but its text is on the text.
 
 ### Padding
 
@@ -241,7 +241,7 @@ above-left of X   above-right of X  below-left of X   below-right of X
 
 **A gap is exactly what was said.** `right of a` puts the box a `normal` gap from `a`'s right side. The gap goes in the placement's bracket, `right of a (gap: tight)`, or as a distance in front, `2 right of a`; writing both is refused as said twice. A diagonal distance is per axis: `2 below-right of a` is 2 across and 2 down.
 
-**A lone direction also centers on its target.** `right of a` alone puts the box level with `a`'s center, because walking right from something keeps you on its center line. That half gives way as soon as another placement says how high.
+**A lone direction also centers on its target.** `right of a` alone puts the box level with `a`'s center, because walking right from something keeps you on its center line. That half gives way as soon as another placement says how high, whichever box it is written on: with `node b right of a` and `node a even with b.1`, B goes where B.1 is level with A, rather than centered on it.
 
 ```
 node parser
@@ -316,7 +316,7 @@ A target need not be written first, but there must be an order in which each box
 
 ### One anchor
 
-Exactly one box in the file places itself, and every other is placed relative to it, directly or through others. Two unplaced boxes are refused by name. Chaining, `b right of a` then `c right of b`, is the plain way to write a few in a row; `layout:` ([Containers](#containers)) is for "these, in a line, in written order". Place against neighbors rather than hanging many boxes off one small one: a gap from a small box says nothing about the large ones also hanging off it.
+Exactly one box in the file places itself, and every other is placed relative to it, directly or through others. Two unplaced boxes are refused by name. The anchor may be split between two boxes, one saying nothing across and the other nothing up and down: with `node a "A"  even with b.1` and `node b "B" right of a`, A says nothing across, and B, once its centering on A gives way, nothing up and down. Chaining, `b right of a` then `c right of b`, is the plain way to write a few in a row; `layout:` ([Containers](#containers)) is for "these, in a line, in written order". Place against neighbors rather than hanging many boxes off one small one: a gap from a small box says nothing about the large ones also hanging off it.
 
 ### A box goes where it is placed
 
@@ -566,7 +566,20 @@ A unit that includes a box's text is placed by the text's position words: on a l
 
 ### Against its own parent
 
-A child placed against its parent's side or corner, `inside server right` or `inside server top-left`, is placed against the finished box and never grows it. If it covers something, that is reported. To make the box hold something, place it relative to the other children. Something the box holds may not be placed against a thing on its own side or corner, since the box would then depend on itself; that is refused.
+A child placed against its parent's side or corner, `inside server right` or `inside server top-left`, is placed against the finished box and never grows it. That holds one axis at a time: `node c.j "j"  right of c.k  inside c top` is beside `c.k` across, so the box holds it across, and against the box's top down. A corner and a sibling saying the same axis, `inside c top-right  right of c.k`, are refused: the error offers `right of c.k  inside c top` and `inside c top-right  stays right of c.k` (below). If it covers something, that is reported. So is a child the box has no room for in that corner, such as a two-line picture in the corner of a box one line tall, as `node-overflow`; the box doesn't grow to fit it, since a box only just tall enough would put it level with the middle, not in the corner. To make the box hold something, place it relative to the other children, or keep it in the corner and clear of them with `stays`. Something the box holds may not be placed against a thing on its own side or corner, since the box would then depend on itself; that is refused.
+
+**`stays` keeps a child clear of the rest of its box.** A picture in the corner of a box its children size can land on one of them. `stays above`, `stays below`, `stays left of` and `stays right of` say which way to keep clear:
+
+```
+node laptop "Laptop" (inside top, align: left)
+node laptop.docs "Documents"
+node laptop.photos "Photos"  right of laptop.docs
+node laptop.mark  icon: laptop  inside laptop top-right  stays above laptop.photos
+```
+
+The laptop is still in the corner; `stays` never says where something goes. It says the laptop is at least the usual gap above Photos, and when it isn't, the box makes room: everything else it holds moves down together, so no gap a placement states changes, and the box grows by just enough. `(gap: wide)` or a number after the target asks for a different distance. Beside the box's own text, `stays right of drive text`, the box widens until the picture clears the text.
+
+A limit relates two things in one box that nothing else ties together: a child placed against the box's side or corner and another child, or the box's text; two children in different corners; something beside the text and the children below it. Between two children placed against each other, or across boxes, every distance is already stated, so a limit there is refused. So is one the box can't meet by growing, such as `inside laptop bottom-right  stays above laptop.photos`, and one a stated size leaves no room for.
 
 A title inside the border counts as content, so the box makes room for it. So does anything placed against the text. A title outside the border hangs off the box and doesn't count.
 
@@ -1016,10 +1029,18 @@ The default order: a container before its own children, boxes before lines, an e
 | `(color: …)` after a text | the text | any node, an edge; `text: (color: …)` in a style or default |
 | `line` | the line and its end marks | an edge |
 
-A key means one thing everywhere, so it can be wrong: `border:` on a node with no outline is refused, and the error lists what that kind has. A color is written as the viewer receives it: a hex value, any CSS color, or a theme color. There is no list of color words: `green` works because it is a CSS color. A quoted color is refused. `none` means the part isn't painted: `fill: none`.
+A key means one thing everywhere, so it can be wrong: `border:` on a node with no outline is refused, and the error lists what that kind has. A color is written as the viewer receives it: a hex value, any CSS color, or a theme color. There is no list of color words: `green` works because it is a CSS color. A quoted color is refused, and so is a hex value without its `#`. `none` means the part isn't painted: `fill: none`.
 
 **Changing a color never moves anything.** Size is different: a bigger text or a thicker line takes more room.
 
+### A border's bracket
+
+```
+node host "Host"  border: (color: #d2904e, thickness: thick)
+```
+
+`border: red` is short for `border: (color: red)`. `thickness:` takes `thin`, `normal` (the default), `thick`, a multiple of normal such as `3`, or pixels such as `4px`; `border: thick` is refused with the bracket it meant. A thick border is drawn inside the box's outline and the box grows by the extra, so its padding is still measured from the inside of the stroke, a gap to its neighbor from the outside, and a line still ends on its outer edge. A stated `width:` or `height:` is the outside of the box, stroke included. A region's border is drawn inside the edge its points state, and the region doesn't grow.
+
 ### Styles
 
 ```
@@ -1101,9 +1122,12 @@ A default takes the words a style does and may wear a style of its own (`default
 
 ```
 diagram  theme: nord  background: #1e2229  text: (color: #e0e0e0)
+diagram  title: "How a login reaches the database"
 ```
 
-`diagram` holds what covers the whole drawing: `theme`, `background` (the page behind everything), `text: (color: …)` for every text, `guides: show`, and `checks: (…)` ([Findings](#errors-and-findings)). It has no name, since a file holds one diagram, and a second one is an error. `diagram text:` takes a color only; a text size belongs on a default.
+`diagram` holds what covers the whole drawing: `theme`, `background` (the page behind everything), `text: (color: …)` for every text, `guides: show`, `checks: (…)` ([Findings](#errors-and-findings)), and `title`. It has no name, since a file holds one diagram, and a second one is an error. `diagram text:` takes a color only; a text size belongs on a default.
+
+`title:` names the drawing, in quotes. It isn't drawn: the SVG carries it as its own title, which a browser shows on the tab and a screen reader announces, and a page made with `--page` is headed with it.
 
 ### Destinations
 
@@ -1126,7 +1150,8 @@ An **error** means the file can't be drawn: an unknown key, two placements on on
 | `edge-node-overlap` | a line across a node that isn't one of its ends, or through its own ends | on |
 | `edge-overlap` | two lines on one run for a stretch, however short; a collapsed bundle's bus, and lines from one statement such as `edge a -> b, c`, shared on purpose, are not reported | on |
 | `crowded-edge-ends` | several line ends bunched on a side too short to space them: two ends' marks would touch, or, where neither has a mark, the lines come within a third of a unit | on |
-| `node-overlap` | two nodes on one spot that no layout, `inside`, `on` or `overlap: allow` accounts for | on |
+| `node-overlap` | two nodes on one spot that no layout, `inside`, `on` or `overlap: allow` accounts for; `inside hub top-right` accounts for covering `hub`, not `hub`'s other children, and a box that draws nothing (no fill, border or text) can't be covered | on |
+| `node-overflow` | a node placed against its container's side or corner that the container has no room for there: less room on the far side than it keeps from the side it names | on |
 | `edge-no-length` | a line between two boxes that touch, drawn as its marks at the seam | on |
 | `edge-crossings` | two lines crossing | off |
 
@@ -1154,6 +1179,7 @@ reladraw check diagram.reladraw
 | option | |
 |---|---|
 | `-o`, `--out` | where `render` writes; defaults to the input with `.svg`; `-` for standard output |
+| `--page` | `render` writes a page for looking at the diagram instead, defaulting to the input with `.html` |
 | `--theme <name>` | render in another theme, whatever the file says |
 | `--guides` | draw the guides |
 | `--checks "<kind>: on, …"` | turn kinds of finding on or off, over the file |
@@ -1162,6 +1188,14 @@ reladraw check diagram.reladraw
 
 The output is a standalone SVG: every picture is drawn into it as path data, never from a font or a linked file. A web page can draw a diagram in place with `<reladraw-diagram>`; see "In a web page" in the README.
 
+### A page for looking at a diagram
+
+```
+reladraw render arch.reladraw --page
+```
+
+`--page` writes `arch.html`: one self-contained file, for opening in a browser, attaching or committing, that needs nothing running and fetches nothing. The page is in the diagram's own colors, so a dark diagram doesn't sit on a white page, and it is headed with `diagram title:`, or the file's name when there is none. Drag to pan; scroll, pinch or double-click to zoom; Fit and Actual size reset the view, and there is a full-screen button. Save SVG and Save PNG save the drawing as `render` would. The findings are listed beside it in a panel that folds away, and clicking one lights up what its line drew. A box's or a line's name shows under the pointer. Keys: `+` and `-` zoom, `0` fits, `1` is actual size, `f` is full screen.
+
 ### Formatting
 
 ```
@@ -1281,6 +1315,23 @@ Designed and absent from the code.
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal 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.21.0**
+
+- **A diagram can have a title**: `diagram  title: "How a login reaches the database"`. The SVG carries it as its own title, which a browser shows on the tab. See [The diagram](#the-diagram).
+- **`reladraw render --page`** writes a page for looking at a diagram: one self-contained HTML file in the diagram's colors, headed with its title, that pans, zooms, goes full screen, saves the SVG or a PNG, lists the findings and lights up what each one is about. See [A page for looking at a diagram](#a-page-for-looking-at-a-diagram).
+- **A border can be thicker or thinner**: `border: (color: #d2904e, thickness: thick)`, mirroring the line's bracket. A thick border is drawn inside the box, and the box grows to keep its padding, so it may move what is placed beside it. See [A border's bracket](#a-borders-bracket).
+- **A box can be lined up with something inside a box placed against it.** `node a "Node A"  even with b.1` with `node b "Node B" right of a` used to be refused, "nothing anchors the diagram", because `right of a` also centered B on A. That centering now gives way, as it already did to a placement written on B itself, and B goes where B.1 is level with A.
+
+**0.20.0**
+
+- **`stays above`, `stays below`, `stays left of` and `stays right of`** keep a child placed in its box's corner clear of the other children: `node laptop.mark  icon: laptop  inside laptop top-right  stays above laptop.photos`. The laptop stays in the corner, and the box makes room. See [Against its own parent](#against-its-own-parent).
+- **Breaking: a corner and a sibling saying the same axis are refused.** `node c.j "j"  inside c top-right  right of c.k` used to be centered between the two, neither in the corner nor beside `c.k`, straddling the box's edge. The error offers `right of c.k  inside c top` to sit beside `c.k`, and `stays right of c.k` to keep the corner. The same goes for `inside c top-right  above c.k` up and down.
+- **A new finding, `node-overflow`**: a child placed in its box's corner or against its side that the box has no room for there, such as `node drive.mark  icon: disk  inside drive top-right` on a box one line tall. It used to run out of the box with nothing said.
+- **A child in its box's corner that covers one of the box's other children is reported** as `node-overlap`, with the `stays` that would keep it clear. Being placed `inside` a box used to excuse it from covering anything in that box, not only the box.
+- **A child beside a sibling and against its parent's top stays inside the parent.** `node c.j "j"  right of c.k  inside c top` used to be drawn wholly outside `c`, with nothing reported. Being against the parent's top only measures its height from the finished box; across, the box holds it like any other child.
+- **Breaking: a hex color without its `#` is refused.** `fill: 444444` used to be passed to the viewer as is, which drew nothing. The error says to write `#444444`.
+- **The playground saves a PNG** with Save PNG, at twice the picture's size, in the fonts the page shows it in. Download is now Save SVG beside it.
+
 **0.19.1**
 
 - **A copy that states its own `step-out:` or `turn:` keeps it.** Lines between the same two sides of the same two boxes fan into lanes, and each used to be drawn as the first one's shape shifted over, so a `step-out:` or `turn:` written on any later line was ignored. A line naming either is now drawn as written and leaves the fan, and so does a line named in its side's `right-edge-order:` list. Where that puts two lines on one run, it is reported as `edge-overlap`. Prompted by #19.

package/dist/ast.d.ts

@@ -234,6 +234,21 @@ export interface OnPlacement {
  * it needs; the resolver intersects them.
  */
 export type Placement = OffsetPlacement | AlignPlacement | OnPlacement;
+/**
+ * `stays above laptop.photos (gap: wide)` — a limit, not a placement
+ * (design.org 5.6). It never says where the node goes, so no axis counts it;
+ * it rules out pictures where the node is less than a gap that way from its
+ * target, and the box holding both makes room by lengthening the one distance
+ * nobody stated.
+ */
+export interface Limit {
+    way: 'above' | 'below' | 'left' | 'right';
+    target: PlacementTarget;
+    gap?: string;
+    line: number;
+}
+/** How a limit reads back in the author's own words. */
+export declare function describeLimit(limit: Limit): string;
 /**
  * The modifiers a placement understands, in brackets after its targets. Refused
  * by name when unrecognized, for the reason `DIAGRAM_KEYS` are: a modifier that
@@ -339,6 +354,12 @@ export declare const TEXT_KEYS: readonly ["color", "size", "wrap", "align", "at"
  * of `line: (color: red)`, and both are stored under the bare `line` key.
  */
 export declare const LINE_KEYS: readonly ["color", "path", "corners", "crossing", "pattern", "thickness", "curve", "turn", "step-out"];
+/**
+ * What a box's border takes in its bracket: `border: (color: red, thickness:
+ * thick)`, mirroring the line's. `border: red` is the short form of the color,
+ * and both are stored under the bare `border` key.
+ */
+export declare const BORDER_KEYS: readonly ["color", "thickness"];
 /**
  * The words each of the line's properties takes, the default first. Thickness
  * takes a multiple of normal (`2`) or pixels (`3px`) as well. `turn:` takes a fraction and
@@ -368,6 +389,8 @@ export interface NodeStmt {
     titlePlacements?: Placement[];
     /** Everything the author said about where this goes. Empty for the anchor. */
     placements: Placement[];
+    /** `stays above laptop.photos`: what it keeps clear of (design.org 5.6). */
+    limits?: Limit[];
     attrs: Attrs;
     /** `guide node frame ""`: does everything a node does except draw (design.org 8.1). */
     guide?: boolean;
@@ -638,9 +661,10 @@ export interface DiagramStmt {
  * `text: (color: …)`, and sets the text color of everything at once — the
  * theme has one text color, shared by nodes and edges, and this is that.
  * `checks` takes a bracket too, `checks: (edge-crossings: on)`, turning kinds
- * of finding on or off by name.
+ * of finding on or off by name. `title` is quoted, and names the drawing: the
+ * SVG carries it as its own title, and a page made with `--page` heads with it.
  */
-export declare const DIAGRAM_KEYS: readonly ["theme", "background", "text", "checks", "guides"];
+export declare const DIAGRAM_KEYS: readonly ["theme", "background", "text", "checks", "guides", "title"];
 /**
  * `default leaf  fill: #2e5d3a` — a style that applies to every thing of one
  * kind without being named. The more specific wins: `node` covers every node,

package/dist/ast.js

@@ -160,6 +160,12 @@ export function describePoint(point) {
     const of = /left|right/.test(point.direction) ? ' of' : '';
     return `${point.distance} ${point.direction}${of} ${nameTarget(point.from)}`;
 }
+/** How a limit reads back in the author's own words. */
+export function describeLimit(limit) {
+    const of = limit.way === 'left' || limit.way === 'right' ? ' of' : '';
+    const gap = limit.gap === undefined ? '' : ` (gap: ${limit.gap})`;
+    return `stays ${limit.way}${of} ${nameTarget(limit.target)}${gap}`;
+}
 /**
  * The modifiers a placement understands, in brackets after its targets. Refused
  * by name when unrecognized, for the reason `DIAGRAM_KEYS` are: a modifier that
@@ -292,6 +298,12 @@ export const TEXT_KEYS = ['color', 'size', 'wrap', 'align', 'at'];
  * of `line: (color: red)`, and both are stored under the bare `line` key.
  */
 export const LINE_KEYS = ['color', 'path', 'corners', 'crossing', 'pattern', 'thickness', 'curve', 'turn', 'step-out'];
+/**
+ * What a box's border takes in its bracket: `border: (color: red, thickness:
+ * thick)`, mirroring the line's. `border: red` is the short form of the color,
+ * and both are stored under the bare `border` key.
+ */
+export const BORDER_KEYS = ['color', 'thickness'];
 /**
  * The words each of the line's properties takes, the default first. Thickness
  * takes a multiple of normal (`2`) or pixels (`3px`) as well. `turn:` takes a fraction and
@@ -339,9 +351,10 @@ export const REGION_KEYS = ['style', 'fill', 'opacity', 'border', 'padding', 'pa
  * `text: (color: …)`, and sets the text color of everything at once — the
  * theme has one text color, shared by nodes and edges, and this is that.
  * `checks` takes a bracket too, `checks: (edge-crossings: on)`, turning kinds
- * of finding on or off by name.
+ * of finding on or off by name. `title` is quoted, and names the drawing: the
+ * SVG carries it as its own title, and a page made with `--page` heads with it.
  */
-export const DIAGRAM_KEYS = ['theme', 'background', 'text', 'checks', 'guides'];
+export const DIAGRAM_KEYS = ['theme', 'background', 'text', 'checks', 'guides', 'title'];
 export const DEFAULT_TARGETS = [
     'node',
     'leaf',

package/dist/checks.d.ts

@@ -21,6 +21,7 @@ export declare const CHECK_DEFAULTS: {
     readonly 'edge-overlap': true;
     readonly 'crowded-edge-ends': true;
     readonly 'node-overlap': true;
+    readonly 'node-overflow': true;
     readonly 'edge-no-length': true;
     readonly 'edge-crossings': false;
 };

package/dist/checks.js

@@ -25,6 +25,7 @@ export const CHECK_DEFAULTS = {
     'edge-overlap': true,
     'crowded-edge-ends': true,
     'node-overlap': true,
+    'node-overflow': true,
     'edge-no-length': true,
     'edge-crossings': false,
 };
@@ -96,6 +97,8 @@ export function findings(layout, checks) {
     const found = [];
     if (checks['node-overlap'])
         found.push(...nodeOverlaps(layout));
+    if (checks['node-overflow'])
+        found.push(...nodeOverflows(layout));
     if (checks['text-overflow'])
         found.push(...textOverflows(layout));
     if (checks['edge-node-overlap'] || checks['edge-overlap'] || checks['edge-no-length'] || checks['crowded-edge-ends'] || checks['edge-crossings'] || checks['text-overlap']) {
@@ -781,12 +784,20 @@ function nodeOverlaps(layout) {
             return true;
         if (upA.some(saysOverlapAllowed) || upB.some(saysOverlapAllowed))
             return true;
-        const placedOn = (over, under) => over.some((node) => under.some((target) => stated.get(node)?.has(target)));
-        return placedOn(upA, upB) || placedOn(upB, upA);
+        // `inside hub top-right` accounts for covering hub, and what it holds
+        // covering hub, but not for covering hub's other children (design.org 5.6).
+        const placedOn = (over, under) => over.some((node) => stated.get(node)?.has(under));
+        return placedOn(upA, b) || placedOn(upB, a);
     };
     const pairs = [];
-    // A guide box draws nothing, so nothing drawn can cover it or be covered by it.
-    const sorted = layout.nodes.filter((node) => !node.guide).sort((a, b) => a.x - b.x);
+    // A guide box draws nothing, so nothing drawn can cover it or be covered by
+    // it, and neither can a box with no fill, no border, no picture and no
+    // text, such as a spacer holding its container open.
+    const blank = (node) => node.lines.every((line) => line.every((run) => run.text.trim() === '')) &&
+        node.body.kind !== 'icon' &&
+        node.appearance['fill'] === 'none' &&
+        node.appearance['border'] === 'none';
+    const sorted = layout.nodes.filter((node) => !node.guide && !blank(node)).sort((a, b) => a.x - b.x);
     let active = [];
     for (const node of sorted) {
         active = active.filter((other) => other.x + other.width > node.x + EPSILON);
@@ -809,7 +820,70 @@ function nodeOverlaps(layout) {
     const inner = ({ earlier, later }) => lineage(earlier).some((a) => lineage(later).some((b) => (a !== earlier || b !== later) && reported.has(namePair(a, b))));
     return pairs
         .filter((pair) => !inner(pair))
-        .map(({ earlier, later, width, height }) => new Finding('node-overlap', `node ${later.name} covers ${coveredPart(earlier, later)}node ${earlier.name}; ${size(width, height)}`, later.line));
+        .map(({ earlier, later, width, height }) => new Finding('node-overlap', `node ${later.name} covers ${coveredPart(earlier, later)}node ${earlier.name}; ${size(width, height)}` +
+        keepClear(earlier, later, width, height), later.line));
+}
+/**
+ * For a child placed against its container's side or corner over one of its
+ * siblings, the limit that would make the box room for it (design.org 5.6):
+ * toward the side it is against, which is the only way growing the box moves
+ * it, and of a corner's two, the one that clears the shorter overlap.
+ */
+function keepClear(a, b, width, height) {
+    const sides = framedSides;
+    if (a.parent === undefined || a.parent !== b.parent || (sides(a).length > 0) === (sides(b).length > 0))
+        return '';
+    const [own, other] = sides(a).length > 0 ? [a, b] : [b, a];
+    const words = { top: 'above', bottom: 'below', left: 'left of', right: 'right of' };
+    const ways = sides(own).map((side) => words[side]);
+    const way = ways.length === 1 ? ways[0] : height <= width ? ways.find((each) => each === 'above' || each === 'below') : ways.find((each) => each.endsWith('of'));
+    return ` — to keep ${own.name} clear of it, add "stays ${way} ${other.name}" to ${own.name}`;
+}
+/** The sides of its container a child is placed against: `inside c top-right` is top and right. */
+function framedSides(node) {
+    const parent = node.parent;
+    if (parent === undefined)
+        return [];
+    const part = node.placements
+        .flatMap((placement) => placement.targets)
+        .find((target) => target.name === parent.name && target.part !== 'text')?.part;
+    if (part === undefined)
+        return [];
+    return part.split('-').filter((word) => ['top', 'bottom', 'left', 'right'].includes(word));
+}
+/**
+ * A child placed against its container's side or corner that the box has no
+ * room for there (design.org 5.6): less room on the far side than it keeps
+ * from the side it names, so it runs into the far side's padding or out of
+ * the box. The box never grows for it, so it is drawn as stated.
+ */
+function nodeOverflows(layout) {
+    const found = [];
+    for (const node of layout.nodes) {
+        const parent = node.parent;
+        if (parent === undefined || node.guide)
+            continue;
+        const short = [];
+        for (const side of framedSides(node)) {
+            const vertical = side === 'top' || side === 'bottom';
+            const start = vertical ? node.y : node.x;
+            const end = start + (vertical ? node.height : node.width);
+            const boxStart = vertical ? parent.y : parent.x;
+            const boxEnd = boxStart + (vertical ? parent.height : parent.width);
+            const kept = side === 'top' || side === 'left' ? start - boxStart : boxEnd - end;
+            const far = side === 'top' || side === 'left' ? boxEnd - end : start - boxStart;
+            if (far >= kept - EPSILON)
+                continue;
+            const room = (vertical ? parent.height : parent.width) - kept * 2;
+            const [measure, against] = vertical ? ['tall', 'height'] : ['wide', 'width'];
+            short.push(`it is ${units(vertical ? node.height : node.width)} ${measure} and ${parent.name}'s ${against} leaves ${room > 0 ? units(room) : 'nothing'} inside its padding`);
+        }
+        if (short.length === 0)
+            continue;
+        found.push(new Finding('node-overflow', `node ${node.name} has no room in the ${framedSides(node).join('-')} of ${parent.name}: ${short.join(', and ')} — ` +
+            `give ${parent.name} more room, or place ${node.name} against ${parent.name}'s text or its other children`, node.line));
+    }
+    return found;
 }
 function namePair(a, b) {
     return a.name < b.name ? `${a.name}\n${b.name}` : `${b.name}\n${a.name}`;

package/dist/cli.js

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, resolve as resolvePath } from 'node:path';
+import { basename, dirname, resolve as resolvePath } from 'node:path';
 import { nearMatch, readChecks } from './checks.js';
 import { SourceError } from './errors.js';
 import { format } from './format.js';
 import { DEFAULT_FORMAT, readFormatSettings, SETTINGS_FILE, settingsFileText } from './format-settings.js';
 import { draw } from './index.js';
+import { drawPage } from './page.js';
 import { THEME_NAMES, THEMES } from './themes.js';
 const USAGE = `reladraw — draw a diagram from stated placement
 
   reladraw render <input.reladraw> [-o <output.svg>] [options]
+  reladraw render <input.reladraw> --page [-o <output.html>] [options]
   reladraw check <input.reladraw> [options]
   reladraw format <input.reladraw>... [--check]
   reladraw format - [--check]
@@ -33,6 +35,11 @@ const USAGE = `reladraw — draw a diagram from stated placement
 
   -o, --out   where render writes the SVG. Defaults to the input path with
               its extension replaced by .svg. Use - for standard output.
+  --page      render writes a page for looking at the diagram instead: one
+              HTML file in the diagram's colors, headed with its title, that
+              pans, zooms, goes full screen, saves the SVG or a PNG, lists the
+              findings and names what is under the pointer. Defaults to the
+              input path with .html.
   --theme     render in this theme, whatever the file's \`diagram theme:\`
               says. One of ${THEME_NAMES.join(', ')}.
   --guides    draw the guides: everything written with \`guide\` in front,
@@ -79,6 +86,7 @@ async function main(argv) {
     let checks;
     let noChecks = false;
     let guides = false;
+    let page = false;
     for (let i = 1; i < argv.length; i += 1) {
         const arg = argv[i];
         if ((arg === '-o' || arg === '--out') && command === 'render') {
@@ -119,6 +127,13 @@ async function main(argv) {
         else if (arg === '--guides') {
             guides = true;
         }
+        else if (arg === '--page' && command === 'render') {
+            page = true;
+        }
+        else if (arg === '--page') {
+            process.stderr.write('reladraw: check writes nothing, so it takes no --page; reladraw render --page writes one\n');
+            return 1;
+        }
         else if (arg.startsWith('-') && arg !== '-') {
             process.stderr.write(`reladraw: unknown option ${arg}\n`);
             return 1;
@@ -157,16 +172,24 @@ async function main(argv) {
         overChecks = (fromFile) => readChecks(written, fromFile);
     }
     const source = await readFile(input, 'utf8');
+    const options = {
+        ...(theme === undefined ? {} : { theme: THEMES[theme] }),
+        ...(guides ? { guides: true } : {}),
+        // An icon's file is found from the diagram, not from wherever the tool
+        // happens to be run.
+        readIconFile: (path) => readFileSync(resolvePath(dirname(input), path), 'utf8'),
+        ...(noChecks ? { checks: false } : overChecks ? { checks: overChecks } : {}),
+    };
     let drawn;
     try {
-        drawn = draw(source, {
-            ...(theme === undefined ? {} : { theme: THEMES[theme] }),
-            ...(guides ? { guides: true } : {}),
-            // An icon's file is found from the diagram, not from wherever the tool
-            // happens to be run.
-            readIconFile: (path) => readFileSync(resolvePath(dirname(input), path), 'utf8'),
-            ...(noChecks ? { checks: false } : overChecks ? { checks: overChecks } : {}),
-        });
+        if (page) {
+            const made = drawPage(source, basename(input).replace(/\.[^.]+$/, ''), options);
+            drawn = { text: made.html, findings: made.findings };
+        }
+        else {
+            const made = draw(source, options);
+            drawn = { text: made.svg, findings: made.findings };
+        }
     }
     catch (error) {
         if (error instanceof SourceError) {
@@ -180,12 +203,12 @@ async function main(argv) {
     if (command === 'check')
         return 0;
     if (out === '-') {
-        process.stdout.write(drawn.svg);
+        process.stdout.write(drawn.text);
         return 0;
     }
-    const target = resolvePath(out ?? input.replace(/\.[^.]+$/, '') + '.svg');
+    const target = resolvePath(out ?? input.replace(/\.[^.]+$/, '') + (page ? '.html' : '.svg'));
     await mkdir(dirname(target), { recursive: true });
-    await writeFile(target, drawn.svg, 'utf8');
+    await writeFile(target, drawn.text, 'utf8');
     process.stderr.write(`${target}\n`);
     return 0;
 }

package/dist/constants.d.ts

@@ -55,6 +55,10 @@ export declare const ARROW_MARKER_WIDTH = 7;
 export declare const ARROW_LENGTH: number;
 /** What `thickness: thin | normal | thick` draw, in pixels. `normal` is the line as it always was. */
 export declare const THICKNESS: Record<string, number>;
+/** A box's border as it always was, in pixels: `border: (thickness: normal)`. */
+export declare const BORDER_WIDTH = 1;
+/** What a border's `thickness: thin | normal | thick` draw, in pixels. */
+export declare const BORDER_THICKNESS: Record<string, number>;
 /**
  * How much of a line of this thickness its arrowhead covers. The marker scales
  * with the stroke, so a thick line gets a bigger head, and the room an edge's

package/dist/constants.js

@@ -65,6 +65,14 @@ export const THICKNESS = {
     normal: LINE_WIDTH,
     thick: LINE_WIDTH * 2,
 };
+/** A box's border as it always was, in pixels: `border: (thickness: normal)`. */
+export const BORDER_WIDTH = 1;
+/** What a border's `thickness: thin | normal | thick` draw, in pixels. */
+export const BORDER_THICKNESS = {
+    thin: BORDER_WIDTH / 2,
+    normal: BORDER_WIDTH,
+    thick: BORDER_WIDTH * 2,
+};
 /**
  * How much of a line of this thickness its arrowhead covers. The marker scales
  * with the stroke, so a thick line gets a bigger head, and the room an edge's

package/dist/constrain.d.ts

@@ -0,0 +1,56 @@
+import type { Placement } from './ast.js';
+/**
+ * The tightest arrangement satisfying a set of relative distances.
+ *
+ * Every placement in the language turns into the same shape of fact: one thing sits
+ * at least so far along an axis from another. Written as `pos[to] >= pos[from]
+ * + weight`, a whole diagram is a system of those, and the arrangement the
+ * author meant is the one where nothing is further apart than it has to be.
+ *
+ * That arrangement is unique and is found by longest paths, so no search
+ * happens and no alternative is ever weighed. Distances come out of the
+ * arithmetic; which side of what a thing sits on came from the author.
+ */
+export interface Constraint {
+    from: number;
+    to: number;
+    weight: number;
+    /** The placement this came from, so a failure can be reported in the author's words. */
+    placement?: Placement;
+}
+/** An exact distance, which is two inequalities pointing opposite ways. */
+export declare function fix(from: number, to: number, distance: number, placement?: Placement): Constraint[];
+export interface Contradiction {
+    /** The placements that cannot all hold. Empty if the loop is entirely implicit. */
+    placements: Placement[];
+}
+/**
+ * Solve, or report the placements that fight.
+ *
+ * Longest path from a virtual source joined to everything at zero, which is
+ * Bellman-Ford with the comparison flipped. A distance that keeps growing after
+ * one pass per node means the constraints run in a circle that demands ever
+ * more room, and that circle is exactly the set of placements to quote back.
+ */
+export declare function tightest(count: number, constraints: Constraint[]): {
+    positions: number[];
+} | {
+    contradiction: Contradiction;
+};
+/**
+ * Which members can be driven apart from which, along one axis.
+ *
+ * A constraint says `pos[to] >= pos[from] + weight`, so it bounds `to` from
+ * below and leaves it free to move further away. Follow those edges and the
+ * question "may this one end up beyond that one?" becomes plain reachability:
+ * if `j` is reachable from `i` and `i` is not reachable from `j`, then the file
+ * lets the distance from `i` to `j` grow without limit and never lets it be
+ * closed from the other side. Pushing `j` past `i` is then the one separation
+ * the file allows, and no choice was made.
+ *
+ * Reachable both ways means the two are pinned at a fixed distance, so they
+ * cannot be separated along this axis at all. Reachable neither way means the
+ * file said nothing that orders them, which is the case the caller must refuse
+ * rather than guess at.
+ */
+export declare function reachability(count: number, constraints: Constraint[]): boolean[][];