reladraw 0.19.1 → 0.20.0

package/README.md

@@ -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.20.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.20.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
 
@@ -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,7 +1029,7 @@ 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.
 
@@ -1126,7 +1139,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 |
 
@@ -1281,6 +1295,16 @@ 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.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
@@ -368,6 +383,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;

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

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/grammar.js

@@ -77,6 +77,8 @@ export const RELATION_WORDS = [
     // `(inside top)`, `outside router right`, `via: inside p top`.
     'inside',
     'outside',
+    // `stays above laptop.photos`, a limit (design.org 5.6).
+    'stays',
     // Lines (design.org 6): `straight down from z3`, `each child of pool`,
     // `leg climb`, `via: through slot horizontal`.
     'straight',

package/dist/model.d.ts

@@ -1,4 +1,4 @@
-import type { Attrs, EdgeTextPlace, Kind, Mark, NodeCorners, Placement, PlacementTarget, ViaEntry, Way } from './ast.js';
+import type { Attrs, EdgeTextPlace, Kind, Limit, Mark, NodeCorners, Placement, PlacementTarget, ViaEntry, Way } from './ast.js';
 /** A rectangle on the page; a side or a point has no size on one axis or both. */
 export interface Rect {
     x: number;
@@ -55,6 +55,8 @@ export interface LayoutNode {
      * (design.org 7.2).
      */
     titlePlacements?: Placement[];
+    /** `stays above laptop.photos`: what it keeps clear of (design.org 5.6). */
+    limits?: Limit[];
     x: number;
     y: number;
     width: number;

package/dist/parser.js

@@ -1238,7 +1238,15 @@ function parseNode(head, line) {
         listed: NODE_TEXT_LISTED,
     });
     refuseNodeReads(bracket.values['reads'], subject, line);
-    const tail = parseTail(head, bracket.next, line, subject);
+    const limits = [];
+    const tail = parseTail(head, bracket.next, line, subject, (tokens, index) => {
+        const word = tokens[index];
+        if (word.quoted || word.text !== 'stays')
+            return undefined;
+        const read = readLimit(tokens, index, line, subject);
+        limits.push(read.limit);
+        return read.next;
+    });
     refuseTextKey(tail.attrs, subject, 'after the name', line);
     return {
         kind: 'node',
@@ -1248,10 +1256,43 @@ function parseNode(head, line) {
         textAttrs: place === undefined ? bracket.values : { ...bracket.values, place },
         ...(titlePlacements.length > 0 ? { titlePlacements } : {}),
         placements: tail.placements,
+        ...(limits.length > 0 ? { limits } : {}),
         attrs: tail.attrs,
         line,
     };
 }
+/**
+ * `stays above laptop.photos (gap: wide)`: a limit (design.org 5.6). The words
+ * after `stays` are read as a placement would be, then held to one straight
+ * way and one target, since a limit says which side of one thing to keep to.
+ */
+function readLimit(tokens, at, line, subject) {
+    const way = tokens[at + 1];
+    const straight = ['above', 'below', 'left', 'right'];
+    if (!way || way.quoted || !straight.includes(way.text)) {
+        const diagonal = way !== undefined && !way.quoted && isDirection(way.text);
+        throw new SourceError(diagonal
+            ? `${subject}: "stays ${way.text}" keeps to two sides at once — write one limit for each, such as \`stays above a  stays right of a\``
+            : `${subject}: "stays" is followed by the way it keeps to — stays above, stays below, stays left of or stays right of`, line);
+    }
+    const read = readPlacement(tokens, at + 1, line, subject, true);
+    const placement = read.placement;
+    if (placement.kind !== 'offset' || placement.own !== undefined || placement.gaps !== undefined) {
+        throw new SourceError(`${subject}: "stays" names a way and one thing, such as \`stays above laptop.photos\``, line);
+    }
+    if (placement.targets.length !== 1) {
+        throw new SourceError(`${subject}: "${describePlacement(placement)}" after "stays" names ${placement.targets.length} things — a limit keeps clear of one; write one for each`, line);
+    }
+    return {
+        limit: {
+            way: way.text,
+            target: placement.targets[0],
+            ...(placement.gap !== undefined ? { gap: placement.gap } : {}),
+            line,
+        },
+        next: read.next,
+    };
+}
 /**
  * A node's text takes the look keys and `reads:` (design.org 7.2). `at` is
  * read only to be refused with the side form, so it isn't listed as one it takes.
@@ -2394,6 +2435,12 @@ function checkColorWord(value, subject, 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);
     }
+    // Hex digits without their `#` are no CSS color, so the viewer would draw nothing.
+    if (/^([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(value)) {
+        // `bad` and `face` are spelled in hex digits too, so without a digit it is only a guess.
+        const fix = /\d/.test(value) ? 'a hex color is written' : 'if it is a hex color, write';
+        throw new SourceError(`${subject}: \`${value}\` is not a color — ${fix} \`#${value}\``, line);
+    }
 }
 function follows(tokens, at, word) {
     const token = tokens[at];

package/dist/place.d.ts

@@ -130,6 +130,8 @@ export declare class Placer {
     private readonly sizes;
     private readonly frames;
     private readonly outlines;
+    /** A container's box while a limit tries it out (`roomFor`), in place of its final one. */
+    private readonly trials;
     private readonly working;
     /** What is being worked out, innermost last, for reporting a circle. */
     private readonly trail;
@@ -181,6 +183,20 @@ export declare class Placer {
     };
     /** Work out everything, and write it onto the nodes. */
     run(): void;
+    /**
+     * What a limit may relate (design.org 5.6): two things in one box that
+     * nothing else ties together, since the box's own spacing between them is
+     * the only distance it may lengthen.
+     */
+    private checkLimitTargets;
+    /**
+     * Which of the things a box holds that nothing ties to each other a member
+     * belongs to, on one axis: its title, what is placed against the box's
+     * sides, or the rest, placed against each other.
+     */
+    private groupOf;
+    /** A limit the box couldn't make room for: no side helps, or a stated size holds it in. */
+    private checkLimitsMet;
     /** Where a node starts on the page. */
     page(node: LayoutNode, axis: Axis): number;
     /**
@@ -226,6 +242,26 @@ export declare class Placer {
     private frame;
     /** A container's outline around what it holds, before anything states its size. */
     private outline;
+    /**
+     * A container's outline with room made for its children's limits
+     * (design.org 5.6). The only distance a limit may lengthen is between what
+     * the box holds and its sides, which every placement inside leaves unstated.
+     * Each side's room moves a limit's two ends apart at a fixed rate (all of
+     * it for a corner, half for the middle of a side), so one trial of each
+     * side gives the rate, and the room is the shortfall over the rate. A side
+     * that doesn't help is never used; with both helping, as for two corner
+     * children, the box grows evenly. A limit no side helps is left unmet, and
+     * `checkLimits` refuses it.
+     */
+    private roomFor;
+    /** The limits a container's children state on one axis. */
+    private limitsIn;
+    /** How much nearer than its gap a limit's two ends are, in a trial frame of their container. */
+    private shortfall;
+    /** The distance a limit keeps: its gap, or the usual one; beside a text, as beside any text. */
+    private limitGap;
+    /** Where a child of `node` is on one axis, in a trial frame of `node`. */
+    private memberAt;
     private remember;
     /**
      * Work something out, refusing a circle. The trail holds what was being
@@ -238,6 +274,14 @@ export declare class Placer {
     private unitStart;
     /** A box's start from its own placements. */
     private placed;
+    /**
+     * Opposite placements center a box between two others, but not when one of
+     * them is its own container's box: `inside c top-right  right of c.k` would
+     * be neither in the corner nor a gap from `c.k` (design.org 5.3). Refused,
+     * naming the two ways out: the corner's other half beside the sibling, or
+     * the corner kept and the sibling held off with `stays`.
+     */
+    private refuseBoxAndSibling;
     private edgeOf;
     /** A box's start from one statement. */
     private apply;
@@ -314,6 +358,15 @@ export declare class Placer {
     private textOf;
     /** A child placed against its own container's box, which it does not grow. */
     framed(node: LayoutNode): boolean;
+    /**
+     * Framed on one axis: what says where it goes on that axis is against its
+     * container's box. `right of c.k  inside c top` is framed down, so its height
+     * is measured from the finished box, and is content across, so the box holds
+     * it there (design.org 5.6).
+     */
+    framedOn(node: LayoutNode, axis: Axis): boolean;
+    /** Whether a placement names its container's box, any part but the text. */
+    private againstBox;
     /**
      * A child placed against its container's text, or against its heading,
      * which makes the title its frame's anchor.
@@ -334,7 +387,8 @@ export declare class Placer {
     /**
      * The children a container's box is the outline of, besides its title: not
      * its heading, not what is joined to its text, and not those placed against
-     * the box.
+     * the box. Given an axis, a child placed against the box only on the other
+     * axis is content on this one.
      */
     private contentOf;
     /** Whether a node has a title: its text, what is joined to it, or a heading. */

package/dist/place.js

@@ -1,4 +1,4 @@
-import { describePlacement, describePoint, fractionAxis, nameTarget, PART_SIDES, partWordHint } from './ast.js';
+import { describeLimit, describePlacement, describePoint, fractionAxis, nameTarget, PART_SIDES, partWordHint } from './ast.js';
 import { DECK_STEP, GAPS, HEADER_GAP, UNIT } from './constants.js';
 import { SourceError } from './errors.js';
 import { isWithin, joinedToText } from './model.js';
@@ -107,6 +107,8 @@ export class Placer {
     sizes = new Map();
     frames = new Map();
     outlines = new Map();
+    /** A container's box while a limit tries it out (`roomFor`), in place of its final one. */
+    trials = new Map();
     working = new Set();
     /** What is being worked out, innermost last, for reporting a circle. */
     trail = [];
@@ -175,6 +177,8 @@ export class Placer {
     /** Work out everything, and write it onto the nodes. */
     run() {
         this.checkAnchors(this.roots, undefined);
+        for (const node of this.byName.values())
+            this.checkLimitTargets(node);
         for (const node of this.byName.values()) {
             for (const axis of BOTH_AXES) {
                 this.size(node, axis);
@@ -189,9 +193,76 @@ export class Placer {
         }
         for (const node of this.byName.values())
             this.checkYielded(node);
+        for (const node of this.byName.values())
+            this.checkLimitsMet(node);
         for (const node of this.byName.values())
             this.finish(node);
     }
+    /**
+     * What a limit may relate (design.org 5.6): two things in one box that
+     * nothing else ties together, since the box's own spacing between them is
+     * the only distance it may lengthen.
+     */
+    checkLimitTargets(node) {
+        for (const limit of node.limits ?? []) {
+            const parent = node.parent;
+            const said = `"${node.name} ${describeLimit(limit)}"`;
+            const named = this.byName.get(limit.target.name);
+            if (!named) {
+                throw new SourceError(`${said}: "${limit.target.name}" does not exist${partWordHint(limit.target.name, this.byName.keys())}`, limit.line);
+            }
+            const ownText = parent !== undefined && named === parent && limit.target.part === 'text';
+            const sibling = parent !== undefined && named.parent === parent && named !== node && limit.target.part === undefined;
+            if (!parent || !(ownText || sibling)) {
+                throw new SourceError(`${said}: a limit keeps clear of something in the same box, a sibling or ` +
+                    `${parent ? `"${parent.name} text"` : 'the box\'s own text'}, since that box is what makes room`, limit.line);
+            }
+            if (ownText && !this.hasTitle(parent)) {
+                throw new SourceError(`${said}: "${parent.name}" has no text`, limit.line);
+            }
+            const axis = limitAxis(limit);
+            const own = this.groupOf(node, parent, axis);
+            if (own !== 'frame' && own === this.groupOf(ownText ? 'text' : named, parent, axis)) {
+                const how = own === 'title' ? `with "${parent.name}"'s text` : 'against each other';
+                throw new SourceError(`${said} could never change anything: "${node.name}" and "${nameTarget(limit.target)}" are placed ${how}, ` +
+                    'so the distance between them is already stated — a limit relates two things in one box that nothing else ties together, ' +
+                    `such as a child placed against "${parent.name}"'s side and one of its other children`, limit.line);
+            }
+        }
+    }
+    /**
+     * Which of the things a box holds that nothing ties to each other a member
+     * belongs to, on one axis: its title, what is placed against the box's
+     * sides, or the rest, placed against each other.
+     */
+    groupOf(member, parent, axis) {
+        const titleTied = this.anchoredOnTitle(parent) || (parent.titlePlacements?.length ?? 0) > 0;
+        if (member === 'text' || member === parent.heading || joinedToText(member))
+            return titleTied ? 'content' : 'title';
+        return this.framedOn(member, axis) ? 'frame' : 'content';
+    }
+    /** A limit the box couldn't make room for: no side helps, or a stated size holds it in. */
+    checkLimitsMet(node) {
+        for (const limit of node.limits ?? []) {
+            const parent = node.parent;
+            const axis = limitAxis(limit);
+            const frame = this.frame(parent, axis);
+            if (this.shortfall(parent, axis, { subject: node, limit }, frame) <= LIMIT_EPSILON)
+                continue;
+            const said = `"${describeLimit(limit)}"`;
+            if (frame.boxSize !== this.outline(parent, axis).boxSize) {
+                throw new SourceError(`"${node.name} ${describeLimit(limit)}", but "${parent.name}"'s stated ${axis === 'x' ? 'width' : 'height'} leaves no room for it — ` +
+                    'make it bigger, or leave the size unstated so the box can make room', limit.line);
+            }
+            const named = this.byName.get(limit.target.name);
+            const framed = [node, named].find((member) => member !== parent && this.framedOn(member, axis));
+            const where = framed
+                ? this.statements(framed, axis).map((statement) => `"${framed.name} ${describePlacement(statement.placement)}"`).join(' and ')
+                : undefined;
+            throw new SourceError(`"${node.name}" can't keep to ${said}${where ? ` with ${where}` : ''}: "${parent.name}" holds both, and growing it ` +
+                'never moves them apart — keep one of the two', limit.line);
+        }
+    }
     // --- the quantities ------------------------------------------------------
     /** Where a node starts on the page. */
     page(node, axis) {
@@ -363,6 +434,9 @@ export class Placer {
     /** A container's box and title in its own frame, at the size it ends up. */
     frame(node, axis) {
         const key = `${node.name}\n${axis}`;
+        const trial = this.trials.get(key);
+        if (trial)
+            return trial;
         const known = this.frames.get(key);
         if (known)
             return known;
@@ -376,10 +450,91 @@ export class Placer {
         const known = this.outlines.get(key);
         if (known)
             return known;
-        const worked = this.guard(`outline\n${key}`, node, axis, undefined, () => this.workOutFrame(node, axis));
+        const worked = this.guard(`outline\n${key}`, node, axis, undefined, () => this.roomFor(node, axis));
         this.outlines.set(key, worked);
         return worked;
     }
+    /**
+     * A container's outline with room made for its children's limits
+     * (design.org 5.6). The only distance a limit may lengthen is between what
+     * the box holds and its sides, which every placement inside leaves unstated.
+     * Each side's room moves a limit's two ends apart at a fixed rate (all of
+     * it for a corner, half for the middle of a side), so one trial of each
+     * side gives the rate, and the room is the shortfall over the rate. A side
+     * that doesn't help is never used; with both helping, as for two corner
+     * children, the box grows evenly. A limit no side helps is left unmet, and
+     * `checkLimits` refuses it.
+     */
+    roomFor(node, axis) {
+        const limits = this.limitsIn(node, axis);
+        let room = NO_ROOM;
+        let frame = this.workOutFrame(node, axis);
+        for (let round = 0; round < limits.length * 2; round++) {
+            const short = (at) => Math.max(...limits.map((each) => this.shortfall(node, axis, each, at)));
+            const owed = short(frame);
+            if (owed <= LIMIT_EPSILON)
+                break;
+            const rate = (more) => (owed - short(this.workOutFrame(node, axis, more))) / owed;
+            const low = rate({ low: room.low + owed, high: room.high });
+            const high = rate({ low: room.low, high: room.high + owed });
+            if (low > LIMIT_EPSILON && high > LIMIT_EPSILON) {
+                const both = rate({ low: room.low + owed, high: room.high + owed });
+                room = { low: room.low + owed / both, high: room.high + owed / both };
+            }
+            else if (low > LIMIT_EPSILON) {
+                room = { ...room, low: room.low + owed / low };
+            }
+            else if (high > LIMIT_EPSILON) {
+                room = { ...room, high: room.high + owed / high };
+            }
+            else {
+                break;
+            }
+            frame = this.workOutFrame(node, axis, room);
+        }
+        return frame;
+    }
+    /** The limits a container's children state on one axis. */
+    limitsIn(node, axis) {
+        return node.children.flatMap((subject) => (subject.limits ?? []).filter((limit) => limitAxis(limit) === axis).map((limit) => ({ subject, limit })));
+    }
+    /** How much nearer than its gap a limit's two ends are, in a trial frame of their container. */
+    shortfall(node, axis, { subject, limit }, at) {
+        const own = this.memberAt(subject, node, axis, at);
+        const other = limit.target.name === node.name ? { start: at.textStart, size: at.textSize } : this.memberAt(this.byName.get(limit.target.name), node, axis, at);
+        const gap = this.limitGap(subject, limit);
+        const toward = limit.way === 'above' || limit.way === 'left';
+        return toward ? own.start + own.size + gap - other.start : other.start + other.size + gap - own.start;
+    }
+    /** The distance a limit keeps: its gap, or the usual one; beside a text, as beside any text. */
+    limitGap(subject, limit) {
+        if (limit.gap !== undefined)
+            return gapPixels(limit.gap, `"${subject.name}"`, limit.line);
+        const parent = subject.parent;
+        if (limit.target.name === parent.name)
+            return this.hasTitle(parent) ? UNIT : 0;
+        return GAPS['normal'];
+    }
+    /** Where a child of `node` is on one axis, in a trial frame of `node`. */
+    memberAt(member, node, axis, at) {
+        const size = this.size(member, axis);
+        if (member === node.heading)
+            return { start: at.titleStart, size };
+        if (joinedToText(member))
+            return { start: at.textStart + this.unitStart(member, axis), size };
+        if (!this.framedOn(member, axis))
+            return { start: this.start(member, axis), size };
+        // Placed against the box: where the trial box puts it, worked out
+        // without remembering, since the box isn't final.
+        const key = `${node.name}\n${axis}`;
+        this.trials.set(key, at);
+        try {
+            return { start: this.placed(member, axis), size };
+        }
+        finally {
+            this.trials.delete(key);
+        }
+    }
     remember(memo, node, axis, work) {
         const key = `${node.name}\n${axis}`;
         const known = memo.get(key);
@@ -480,6 +635,7 @@ export class Placer {
         }
         const [first, second] = statements;
         if (first.kind !== 'align' && second.kind !== 'align' && first.kind !== second.kind) {
+            this.refuseBoxAndSibling(node, axis, first.placement, second.placement);
             // Opposite placements: centered between the two at its own size. Each
             // target stays where its own statement put it.
             const after = first.kind === 'after' ? first : second;
@@ -494,6 +650,36 @@ export class Placer {
             return pins.start;
         throw this.overStated(node, axis, statements);
     }
+    /**
+     * Opposite placements center a box between two others, but not when one of
+     * them is its own container's box: `inside c top-right  right of c.k` would
+     * be neither in the corner nor a gap from `c.k` (design.org 5.3). Refused,
+     * naming the two ways out: the corner's other half beside the sibling, or
+     * the corner kept and the sibling held off with `stays`.
+     */
+    refuseBoxAndSibling(node, axis, first, second) {
+        const parent = node.parent;
+        if (!parent || this.againstBox(first, parent) === this.againstBox(second, parent))
+            return;
+        const [box, other] = this.againstBox(first, parent) ? [first, second] : [second, first];
+        if (other.kind !== 'offset')
+            return;
+        const ways = [];
+        const corner = box.targets[0]?.part;
+        if (box.kind === 'offset' && box.written !== undefined && corner !== undefined && corner.includes('-')) {
+            const [down, across] = corner.split('-');
+            const kept = axis === 'x' ? down : across;
+            ways.push(`to sit ${describePlacement(other)} at the ${kept} of ${parent.name}, write "${describePlacement(other)}  ${box.written} ${parent.name} ${kept}"`);
+        }
+        const way = component(other.direction, axis);
+        const straight = axis === 'x' ? (way === 'after' ? 'right' : 'left') : way === 'after' ? 'below' : 'above';
+        const of = axis === 'x' ? ' of' : '';
+        if (other.targets.length === 1) {
+            ways.push(`to stay ${describePlacement(box)} and clear of ${nameTarget(other.targets[0])}, write "stays ${straight}${of} ${nameTarget(other.targets[0])}"`);
+        }
+        throw new SourceError(`"${node.name}" says twice where it goes ${AXIS_SAID[axis]}, with "${describePlacement(box)}" and "${describePlacement(other)}"` +
+            (ways.length > 0 ? `; ${ways.join('; ')}` : ' — keep one'), other.line);
+    }
     edgeOf(node, axis, statement) {
         return this.guard(`edge\n${node.name}\n${axis}\n${statement.placement.line}`, node, axis, statement.placement, () => statement.kind === 'align' ? 0 : statement.edge());
     }
@@ -991,7 +1177,7 @@ export class Placer {
                 text = { start: frame.textStart, size: frame.textSize };
         }
         else if (named.parent === parent) {
-            if (this.framed(named) && !this.framed(node)) {
+            if (this.framedOn(named, axis) && !this.framedOn(node, axis)) {
                 throw new SourceError(`"${node.name}" is placed against "${named.name}", which is placed against "${parent.name}" itself. ` +
                     `Nothing may be placed against a thing placed against its container's side or corner — place ` +
                     `"${node.name}" against another child`, placement.line);
@@ -1049,7 +1235,27 @@ export class Placer {
         const parent = node.parent;
         if (!parent || this.facts.get(parent).layout || this.facts.get(parent).venn)
             return false;
-        return node.placements.some((placement) => placement.targets.some((target) => target.name === parent.name && target.part !== 'text'));
+        return node.placements.some((placement) => this.againstBox(placement, parent));
+    }
+    /**
+     * Framed on one axis: what says where it goes on that axis is against its
+     * container's box. `right of c.k  inside c top` is framed down, so its height
+     * is measured from the finished box, and is content across, so the box holds
+     * it there (design.org 5.6).
+     */
+    framedOn(node, axis) {
+        if (!this.framed(node))
+            return false;
+        const parent = node.parent;
+        const statements = this.statements(node, axis);
+        if (statements.length > 0)
+            return statements.some((statement) => this.againstBox(statement.placement, parent));
+        // Nothing states this axis, so a lone direction on the other one centers it on its target.
+        return node.placements.some((placement) => placement.kind === 'offset' && component(placement.direction, axis) === undefined && this.againstBox(placement, parent));
+    }
+    /** Whether a placement names its container's box, any part but the text. */
+    againstBox(placement, parent) {
+        return placement.targets.some((target) => target.name === parent.name && target.part !== 'text');
     }
     /**
      * A child placed against its container's text, or against its heading,
@@ -1111,10 +1317,13 @@ export class Placer {
     /**
      * The children a container's box is the outline of, besides its title: not
      * its heading, not what is joined to its text, and not those placed against
-     * the box.
+     * the box. Given an axis, a child placed against the box only on the other
+     * axis is content on this one.
      */
-    contentOf(node) {
-        return node.children.filter((child) => child !== node.heading && !joinedToText(child) && !this.framed(child));
+    contentOf(node, axis) {
+        return node.children.filter((child) => child !== node.heading &&
+            !joinedToText(child) &&
+            !(axis === undefined ? this.framed(child) : this.framedOn(child, axis)));
     }
     /** Whether a node has a title: its text, what is joined to it, or a heading. */
     hasTitle(node) {
@@ -1307,12 +1516,12 @@ export class Placer {
      * not placed against the box itself, and the title when it sits inside the
      * border or on it.
      */
-    workOutFrame(node, axis) {
+    workOutFrame(node, axis, room = NO_ROOM) {
         const facts = this.facts.get(node);
         const title = this.titleOf(node);
         const hasTitle = this.hasTitle(node);
         const titleSize = this.titleSize(node, axis);
-        const content = this.contentOf(node);
+        const content = this.contentOf(node, axis);
         const anchoredOnTitle = this.anchoredOnTitle(node);
         let low = Infinity;
         let high = -Infinity;
@@ -1343,6 +1552,12 @@ export class Placer {
                 high = Math.max(high, band);
             }
         }
+        // Room a child's limit asks for (design.org 5.6), between what the box
+        // holds and its sides, so a title against a side moves out with it.
+        if (!empty) {
+            low -= room.low;
+            high += room.high;
+        }
         // Where the title sits in the frame. When something is placed against it,
         // it is the frame's anchor and sits at the origin; otherwise it is placed
         // against the children by its side.
@@ -1358,6 +1573,10 @@ export class Placer {
                 low = titleStart;
                 high = titleStart + titleSize;
             }
+            if (empty) {
+                low -= room.low;
+                high += room.high;
+            }
         }
         else if (title.how === 'center' || title.side === 'center') {
             titleStart = (low + high) / 2 - titleSize / 2;
@@ -1590,7 +1809,7 @@ export class Placer {
     innerOther(node, axis) {
         const key = `inner\n${node.name}\n${axis}`;
         return this.guard(key, node, axis, undefined, () => {
-            const content = this.contentOf(node);
+            const content = this.contentOf(node, axis);
             let low = Infinity;
             let high = -Infinity;
             for (const child of content) {
@@ -2173,6 +2392,13 @@ export class Placer {
         return { low, high };
     }
 }
+const NO_ROOM = { low: 0, high: 0 };
+/** Less than this is no distance at all, for a limit worked out in floating point. */
+const LIMIT_EPSILON = 0.01;
+/** The axis a limit keeps to: up and down for above and below. */
+function limitAxis(limit) {
+    return limit.way === 'above' || limit.way === 'below' ? 'y' : 'x';
+}
 /**
  * `top even with 2 below design top` on a venn's set: the other set's same
  * side, moved up or down. Anything else, such as its bottom or a sideways

package/dist/resolve.js

@@ -771,6 +771,7 @@ function buildTree(statements, styles, defaults, icons) {
             attrs: stmt.attrs,
             appearance,
             placements: stmt.placements,
+            ...(stmt.limits ? { limits: stmt.limits } : {}),
             ...(stmt.guide ? { guide: true } : {}),
             line: stmt.line,
         };

package/package.json

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