reladraw 0.17.0 → 0.18.0

package/README.md

@@ -86,7 +86,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.17.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.18.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.17.0
+# Syntax reference — 0.18.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.
 
@@ -104,14 +104,44 @@ node <name> ["<text>" [(<text settings>)]] [<placement> | <attribute>] ...
 
 Every node has one body, the thing drawn where it is, named by one of two keys.
 
-`shape:` is the outline:
+`shape:` is the outline. A shape geometry has a word for is named by it, and takes settings in a bracket after its name for what its box doesn't decide: an amount, in the file's unit, and a direction, whose first word below is the default.
+
+| shape | draws | its bracket |
+|---|---|---|
+| `rectangle` | the plain box, its corners rounded unless `corners: sharp`; the default | |
+| `document` | the box with its top-right corner folded, for an artifact rather than a process; its other corners follow `corners:` | `fold:` |
+| `circle` | a circle sized to hold its text; given a `width:` and a `height:` that differ, an ellipse | |
+| `diamond` | a diamond, a flowchart's decision | |
+| `pill` | a box with both ends round, a flowchart's start or end | |
+| `parallelogram` | a slanted box, a flowchart's input or output | `slant:`, `lean: right \| left` |
+| `hexagon` | a box with pointed ends, a flowchart's preparation | `point:` |
+| `trapezoid` | a box narrower at one end, a flowchart's manual operation | `taper:`, `narrow: bottom \| top` |
+| `triangle` | a triangle, a flowchart's merge (down) or extract (up) | `aim: down \| up \| left \| right` |
+| `cylinder` | a cylinder standing, or `lying` on its side, for stored data | `cap:`, `lying` |
+| `none` | no outline, fill or padding: bare text, or an invisible container | |
+
+```
+node in    "read input"  shape: parallelogram (slant: 2, lean: left)
+node queue "queue"       shape: cylinder (cap: 1.5, lying)  right of in
+node flat  "valid?"      shape: diamond  width: 20  height: 5  below in
+```
+
+A flowchart shape geometry has no word for is named `flow-` and what it means, and drawn the way the flowchart standard draws it, with no settings:
 
 | shape | draws |
 |---|---|
-| `rectangle` | the plain box, its corners rounded unless `corners: sharp`; the default |
-| `document` | the box with its top-right corner folded, for an artifact rather than a process; its other corners follow `corners:` |
-| `circle` | a circle sized to hold its text, always round |
-| `none` | no outline, fill or padding: bare text, or an invisible container |
+| `flow-subprocess` | a step drawn as its own chart: a box with a bar inside each side |
+| `flow-document` | a document as the standard draws it, its bottom wavy |
+| `flow-off-page` | continued on another page: a box pointed at the bottom |
+| `flow-delay` | a delay or a wait: a box with its right end round |
+| `flow-manual-input` | typed in by hand: a box whose top slopes |
+| `flow-stored-data` | the standard's other storage: curved ends, the right one hollow |
+| `flow-loop-start`, `flow-loop-end` | the start and end of a loop: a box with two corners cut, at the top or the bottom |
+| `flow-card` | a punched card: a box with its top-left corner cut |
+| `flow-display` | a screen: pointed on the left, round on the right |
+| `flow-tape` | magnetic tape: a circle with a tail |
+| `flow-punched-tape` | paper tape: wavy top and bottom |
+| `flow-collate` | collate: two triangles point to point, its text on a patch where they meet |
 
 `icon:` is a picture the node is drawn *as*, with no box:
 
@@ -131,11 +161,15 @@ node aside "Written by a nightly cron job." (wrap: 30)  shape: none  below dump
 node svc  icon: cube  right of dump
 ```
 
-Writing both keys is an error naming both. An unknown name is refused with the whole set. A name says what a thing is, never what the picture looks like: `document`, not `folded-corner`. The exception is a picture with no single meaning, such as `circle` or `cube`.
+Writing both keys is an error naming both. An unknown name is refused with the whole set, and so is a setting the shape doesn't take. A shape is named for how it looks, `diamond` and never `decision`, and no picture has two names. An icon is named for what it is: `package`, not `open-box`.
 
-A picture can't contain anything. A `shape: none` node with children is an invisible container ([Containers](#containers)). A circle can hold other nodes, centered in it. A side of a circle is the quarter of it about that compass point, so `from: right` means the same on every shape; several line ends on one side spread round that arc, each meeting the circle square on.
+**Size and text.** A shape grows until its text, with its padding, fits at the shape's middle, the center of its area: a diamond is twice the padded text each way, and a triangle's text sits a third of the way from its base. A stated `width:` and `height:` stretch the shape to fill them, which is how a diamond is made flatter; a text that no longer fits is drawn as it is and reported as `text-overflow`. The text-position words of a [node's text](#where-it-sits), such as `(inside bottom)`, move it off the middle. `flow-collate`'s text sits on a patch of its own fill where its two triangles meet; `(fill: none)` in the text's bracket draws it without one.
 
-**Corners.** `corners: sharp` draws a box's corners square, and `corners: rounded`, the default, draws them as they always were. It is the same word and values as a line's `corners:`. It reaches every outline with corners: a rectangle, a container, and a document's three round corners, whose fold stays as it is. A circle has none, so `corners:` written on a circle is refused; from a style or a default it lands only on the nodes with corners. A picture and bare text have no outline, so they refuse it too. Like a color, it never moves anything.
+**Sides.** A side of a shape is the stretch of its outline between the lines from its middle to two corners of its box: a rectangle's sides, a circle's quarters, and on a diamond the stretch round each point. So `from: right` leaves a diamond from its right point, as a flowchart's "no" does, and means the same on every shape. A corner such as `top-right` is where the line from the middle to that corner of the box meets the outline: on a circle halfway between its sides, on a diamond the middle of an edge. Several line ends on one side spread along it.
+
+A picture can't contain anything. A `shape: none` node with children is an invisible container ([Containers](#containers)). A circle can hold other nodes, centered in it; the other shapes don't hold nodes yet, and one with children is refused.
+
+**Corners.** `corners: sharp` draws a box's corners square, and `corners: rounded`, the default, draws them as they always were. It is the same word and values as a line's `corners:`. It reaches every outline with corners that round: a rectangle, a container, a `flow-subprocess`, and a document's three round corners, whose fold stays as it is. Every other shape is drawn with its points sharp, so `corners:` written on one is refused; from a style or a default it lands only on the nodes it can. A picture and bare text have no outline, so they refuse it too. Like a color, it never moves anything.
 
 ```
 style plain  corners: sharp
@@ -324,7 +358,7 @@ left-center   center          right-center
 bottom-left   bottom-center   bottom-right
 ```
 
-**A side is a segment and a point is a point.** Bare `top` is the whole side; `top-center` is the one point halfway along it, which is why every midpoint carries `-center`. Naming a side leaves the other axis free. On a circle, a corner is the point on the circle halfway between its two sides.
+**A side is a segment and a point is a point.** Bare `top` is the whole side; `top-center` is the one point halfway along it, which is why every midpoint carries `-center`. Naming a side leaves the other axis free. On any shape but a box, a point is where the line from the shape's middle toward that point of its box meets the outline ([Sides](#the-body)): on a circle a corner is halfway between its two sides.
 
 A part is written as the name, then the part: `b top`, `e bottom-left`, `hub text`.
 
@@ -588,6 +622,7 @@ node aside "Written nightly." (size: small, wrap: 30)  shape: none
 | `size` | `small`, `normal` or `large`; a multiple of normal (`1.2`); or pixels (`16px`) |
 | `wrap` | a count of characters to fold at, on top of ` / ` |
 | `align` | how the text's own lines range: `left`, `center`, `right`, or where along a side for a title (below) |
+| `fill` | on a `flow-collate` only, the patch behind its text: a color, or `none` |
 
 `small` is 21/25 of normal and `large` the same step the other way. The names are preferred: bundled into a style, a size says *why* one text is smaller. `wrap:` is a character count, not a distance: it is how a text is made narrow and tall to sit beside something.
 
@@ -1123,6 +1158,7 @@ reladraw check diagram.reladraw
 | `--guides` | draw the guides |
 | `--checks "<kind>: on, …"` | turn kinds of finding on or off, over the file |
 | `--no-checks` | print no findings; errors still print |
+| `-v`, `--version` | print the version |
 
 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.
 
@@ -1138,7 +1174,7 @@ Every attribute, and what takes one. A node's kind is what its body is: a box (`
 | `badge` | ✓ | | | | a picture joined to the text |
 | `cards` | ✓ | | | | a deck's cards, when they are only texts, front first |
 | `fill`, `border` | ✓ | | | | colors |
-| `corners` | ✓ | | | | `sharp` or `rounded`; not on a circle. A line's go in `line: (…)` |
+| `corners` | ✓ | | | | `sharp` or `rounded`; only on a box's outline. A line's go in `line: (…)` |
 | `text` | ✓ | ✓ | ✓ | ✓ | in a style only; on a statement, the bracket after the text |
 | `layout` | ✓ | | ✓ | | how the children are arranged |
 | `gather-children` | ✓ | | ✓ | | where the children sit in spare room |
@@ -1192,6 +1228,17 @@ 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.18.0**
+
+- **More shapes, for flowcharts and the rest** (#18): `diamond`, `pill`, `parallelogram`, `hexagon`, `trapezoid`, `triangle` and `cylinder`, named for how they look, and the flowchart standard's shapes that have no geometric name as `flow-` and what they mean, from `flow-subprocess` and `flow-delay` to `flow-collate`. A shape's settings go in a bracket after its name: `shape: parallelogram (slant: 2, lean: left)`, `shape: cylinder (lying)`, `shape: document (fold: 1.5)`.
+- **A shape grows to hold its text at its middle**, and a stated `width:` and `height:` stretch it. Its sides are the stretches of outline round its points, so `from: right` leaves a diamond from its right point.
+- **A circle given a `width:` and a `height:` that differ is an ellipse.** It used to stay round and say nothing about the height.
+
+**0.17.1**
+
+- **`reladraw --version`**, or `-v`, prints the version.
+- **The playground waits for a pause in typing** before it redraws a diagram that is slow to draw, so the keystrokes aren't held up behind it. A quick one still redraws on every keystroke. Suggested in #6.
+
 **0.17.0**
 
 The redesign. The tool no longer decides anything the file doesn't say: a gap is exact, nothing moves a box to make room, lines are straight unless told and go only where they are told, and anything that may not read as meant is drawn as written and reported as a finding. Almost every diagram written for 0.16.0 needs changes; the table below gives each old spelling and what to write instead.

package/dist/checks.js

@@ -9,7 +9,8 @@
  */
 import { isWithin, joinedToText } from './model.js';
 import { ARROW_MARKER_WIDTH, LINE_WIDTH, UNIT, arrowLength } from './constants.js';
-import { crossingPoints, describeEdge, planSides, traceRoute, traceVisible } from './lines.js';
+import { centerOf, crossingPoints, describeEdge, faceOfNode, planSides, traceRoute, traceVisible } from './lines.js';
+import { clearOf, insideOutline, sizeFor } from './outline.js';
 import { placeLineTexts } from './linetexts.js';
 /**
  * The kinds of finding, each with whether it is on when nothing says. Named in
@@ -135,8 +136,8 @@ function edgeNodeOverlaps(layout, routes) {
             if (holdsEnd(node, edge))
                 continue;
             const inner = { x: node.x + 1, y: node.y + 1, width: node.width - 2, height: node.height - 2 };
-            const round = node.body.kind === 'shape' && node.body.outline === 'circle';
-            const through = round ? crossingCircle(trace, node) : crossing(trace, inner);
+            const face = faceOfNode(node);
+            const through = face.round || face.outline ? crossingCircle(trace, node, face) : crossing(trace, inner);
             if (through === undefined)
                 continue;
             const own = node === edge.from || node === edge.to;
@@ -249,14 +250,18 @@ function crossing(trace, box) {
     return { enters, leaves };
 }
 /**
- * The same for a circle, which is drawn in its node's square: walked a couple
- * of pixels at a time, a point counting as inside only past a pixel within the
- * outline, so a line ending on the circle doesn't cross it.
+ * The same for a circle, or any outline but a rectangle's, which is drawn in
+ * its node's box: walked a couple of pixels at a time, a point counting as
+ * inside only past a pixel within the outline, so a line ending on it doesn't
+ * cross it.
  */
-function crossingCircle(trace, node) {
+function crossingCircle(trace, node, face) {
     const radius = node.width / 2 - 1;
-    const center = { x: node.x + node.width / 2, y: node.y + node.height / 2 };
-    const inside = (p) => Math.hypot(p.x - center.x, p.y - center.y) < radius;
+    const center = centerOf(face);
+    const polygon = face.outline;
+    const inside = polygon
+        ? (p) => insideOutline(polygon, p) && clearOf(polygon, p, 1)
+        : (p) => Math.hypot(p.x - center.x, p.y - center.y) < radius;
     const sideAt = (p) => {
         const dx = p.x - center.x;
         const dy = p.y - center.y;
@@ -564,6 +569,22 @@ function textOverflows(layout) {
         const place = node.textAttrs['place'];
         if (place !== undefined && place !== 'center' && !place.startsWith('inside'))
             continue;
+        const face = faceOfNode(node);
+        if (face.outline && node.body.outline !== 'flow-collate') {
+            // Any other outline than a box's: the text spills where it passes the outline.
+            const { outline, look } = node.body;
+            const corners = [0, 0.5, 1].flatMap((fx) => [0, 0.5, 1].map((fy) => ({ x: node.x + text.x + text.width * fx, y: node.y + text.y + text.height * fy })));
+            if (corners.every((p) => insideOutline(face.outline, p)))
+                continue;
+            const needs = sizeFor(outline, look, text.width, text.height);
+            const wider = Math.max(0, needs.width - node.width);
+            const taller = Math.max(0, needs.height - node.height);
+            const more = [wider > EPSILON ? `${units(wider)} more width` : '', taller > EPSILON ? `${units(taller)} more height` : ''].filter((part) => part.length > 0);
+            found.push(new Finding('text-overflow', `the text of node ${node.name} runs past the outline of its ${outline}` + (more.length > 0 ? `; it needs ${more.join(' and ')}` : ''), node.line));
+            continue;
+        }
+        if (node.body.outline === 'flow-collate')
+            continue;
         const spill = {
             left: Math.max(0, -text.x),
             right: Math.max(0, text.x + text.width - node.width),

package/dist/cli.js

@@ -25,6 +25,8 @@ const USAGE = `reladraw — draw a diagram from stated placement
   --checks    turn kinds of finding on or off, over what the file says:
               --checks "edge-crossings: on, node-overlap: off"
   --no-checks print no findings. Errors still print.
+  -v, --version
+              print the version.
   -h, --help  print this.
 `;
 const COMMANDS = ['render', 'check'];
@@ -33,6 +35,12 @@ async function main(argv) {
         process.stdout.write(USAGE);
         return argv.length === 0 ? 1 : 0;
     }
+    if (argv.includes('-v') || argv.includes('--version')) {
+        // package.json ships beside dist/, so the number is the installed one.
+        const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+        process.stdout.write(`${pkg.version}\n`);
+        return 0;
+    }
     const verb = argv[0];
     if (!COMMANDS.includes(verb)) {
         // A file where the command goes is the old form, and is told the new one;

package/dist/icons.d.ts

@@ -18,6 +18,7 @@
  * which caps the useful vocabulary at something that fits in a head. Add a name
  * when a diagram asks for a distinction it cannot otherwise make.
  */
+import { type ShapeLook } from './outline.js';
 /**
  * Icons carry three tones rather than colors. `ink` is the drawn line, `shade`
  * the body it encloses, and `void` is the page showing through — the same
@@ -57,23 +58,21 @@ export declare const ICON_NAMES: string[];
  * The outlines a node's body can take. `rectangle` is the plain one and needs no
  * word, since it is what a node is when it says nothing.
  *
- * Named for what a node *is*, never for the geometry, which is the same rule the
- * icon names follow: `document` and not `folded-corner`. A shape carrying a
- * conventional meaning is a second channel alongside color, and a stronger one
- * — a fill is whatever the author assigned and has to be learnt from the
- * diagram, while a folded corner has meant "an artifact, not a process" in
- * flowcharts for decades and reads with no legend at all.
+ * A shape geometry has a word for is named by that word, how it looks:
+ * `diamond`, never `decision`, since someone may just want a diamond, and
+ * reading `decision` as a diamond is a translation every reader has to make.
+ * Those take settings in a bracket for what the box doesn't decide. A
+ * flowchart shape geometry has no word for is named `flow-` and what it means,
+ * drawn the way the standard draws it, with no settings. No picture has two
+ * names. `document`, the folded corner, is older than the rule and keeps its
+ * name; the standard's wavy one is `flow-document`.
  *
- * `circle` is the one geometric name, because a circle carries no single
- * meaning to name it after — it is a state, a step, a person, whatever the
- * diagram's own convention makes it. `diamond` joins these when a diagram
- * asks. The set being short is a fact about what has been drawn, not about the
- * key.
+ * The geometry of each is in `outline.ts`.
  */
-export declare const OUTLINES: readonly ["rectangle", "document", "circle"];
+export declare const OUTLINES: readonly ["rectangle", "document", "circle", "diamond", "pill", "parallelogram", "hexagon", "trapezoid", "triangle", "cylinder", "flow-subprocess", "flow-document", "flow-off-page", "flow-delay", "flow-manual-input", "flow-stored-data", "flow-loop-start", "flow-loop-end", "flow-card", "flow-display", "flow-tape", "flow-punched-tape", "flow-collate"];
 export type Outline = (typeof OUTLINES)[number];
 /** Every value `shape:` accepts, `none` included. */
-export declare const SHAPE_WORDS: readonly ["rectangle", "document", "circle", "none"];
+export declare const SHAPE_WORDS: readonly ["rectangle", "document", "circle", "diamond", "pill", "parallelogram", "hexagon", "trapezoid", "triangle", "cylinder", "flow-subprocess", "flow-document", "flow-off-page", "flow-delay", "flow-manual-input", "flow-stored-data", "flow-loop-start", "flow-loop-end", "flow-card", "flow-display", "flow-tape", "flow-punched-tape", "flow-collate", "none"];
 /**
  * What a node is drawn as: an outline, a picture, or nothing at all.
  *
@@ -88,6 +87,7 @@ export declare const SHAPE_WORDS: readonly ["rectangle", "document", "circle", "
 export type Body = {
     kind: 'shape';
     outline: Outline;
+    look: ShapeLook;
 } | {
     kind: 'icon';
     icon: Icon;

package/dist/icons.js

@@ -19,6 +19,7 @@
  * when a diagram asks for a distinction it cannot otherwise make.
  */
 import { SourceError } from './errors.js';
+import { readShapeLook } from './outline.js';
 const GRID = 24;
 /** Line width on the 24-unit grid, scaled with everything else. */
 export const ICON_STROKE = 1.1;
@@ -119,23 +120,45 @@ export const ICON_NAMES = Object.keys(ICONS);
  * The outlines a node's body can take. `rectangle` is the plain one and needs no
  * word, since it is what a node is when it says nothing.
  *
- * Named for what a node *is*, never for the geometry, which is the same rule the
- * icon names follow: `document` and not `folded-corner`. A shape carrying a
- * conventional meaning is a second channel alongside color, and a stronger one
- * — a fill is whatever the author assigned and has to be learnt from the
- * diagram, while a folded corner has meant "an artifact, not a process" in
- * flowcharts for decades and reads with no legend at all.
+ * A shape geometry has a word for is named by that word, how it looks:
+ * `diamond`, never `decision`, since someone may just want a diamond, and
+ * reading `decision` as a diamond is a translation every reader has to make.
+ * Those take settings in a bracket for what the box doesn't decide. A
+ * flowchart shape geometry has no word for is named `flow-` and what it means,
+ * drawn the way the standard draws it, with no settings. No picture has two
+ * names. `document`, the folded corner, is older than the rule and keeps its
+ * name; the standard's wavy one is `flow-document`.
  *
- * `circle` is the one geometric name, because a circle carries no single
- * meaning to name it after — it is a state, a step, a person, whatever the
- * diagram's own convention makes it. `diamond` joins these when a diagram
- * asks. The set being short is a fact about what has been drawn, not about the
- * key.
+ * The geometry of each is in `outline.ts`.
  */
-export const OUTLINES = ['rectangle', 'document', 'circle'];
+export const OUTLINES = [
+    'rectangle',
+    'document',
+    'circle',
+    'diamond',
+    'pill',
+    'parallelogram',
+    'hexagon',
+    'trapezoid',
+    'triangle',
+    'cylinder',
+    'flow-subprocess',
+    'flow-document',
+    'flow-off-page',
+    'flow-delay',
+    'flow-manual-input',
+    'flow-stored-data',
+    'flow-loop-start',
+    'flow-loop-end',
+    'flow-card',
+    'flow-display',
+    'flow-tape',
+    'flow-punched-tape',
+    'flow-collate',
+];
 /** Every value `shape:` accepts, `none` included. */
 export const SHAPE_WORDS = [...OUTLINES, 'none'];
-const PLAIN = { kind: 'shape', outline: 'rectangle' };
+const PLAIN = { kind: 'shape', outline: 'rectangle', look: {} };
 /**
  * Which body a node has, from what it wrote and what its style carried.
  *
@@ -158,14 +181,37 @@ export function bodyFor(attrs, appearance, line, declared = new Map()) {
         throw new SourceError(`shape: ${shape} and icon: ${icon} both say what this node is drawn as, and it has one ` +
             'body — `shape:` is the outline it is drawn with, `icon:` is the picture it is drawn as', line);
     }
+    // The settings come from wherever the shape did: a node's own `shape:` takes
+    // its own bracket, never a style's.
+    const from = wroteShape ? attrs : appearance;
+    const settings = {};
+    for (const [key, value] of Object.entries(from))
+        if (key.startsWith('shape.'))
+            settings[key.slice('shape.'.length)] = value;
     if (icon !== undefined)
         return { kind: 'icon', icon: iconNamed(icon, line, declared) };
     if (shape === undefined)
         return PLAIN;
-    if (shape === 'none')
+    if (shape === 'none') {
+        if (Object.keys(settings).length > 0)
+            refuse(`\`shape: none\` draws no outline, so it takes no settings`, line);
         return { kind: 'none' };
+    }
     if (OUTLINES.includes(shape)) {
-        return { kind: 'shape', outline: shape };
+        return { kind: 'shape', outline: shape, look: readShapeLook(shape, settings, `shape: ${shape}`, line) };
+    }
+    if (shape === 'hourglass') {
+        return refuse('`shape: hourglass` is the flowchart\'s collate symbol, and it is `flow-collate`', line);
+    }
+    if (shape === 'pentagon' || shape === 'pointed' || shape === 'home-plate') {
+        return refuse(`there is no shape "${shape}" — the flowchart's off-page connector, a box with one end pointed, is \`flow-off-page\``, line);
+    }
+    if (shape === 'ellipse' || shape === 'oval') {
+        return refuse(`there is no shape "${shape}" — an ellipse is a circle given a width and a height: \`shape: circle  width: 20  height: 8\``, line);
+    }
+    if (shape === 'decision' || shape === 'terminal' || shape === 'process') {
+        const look = { decision: 'diamond', terminal: 'pill', process: 'rectangle' }[shape];
+        return refuse(`a shape is named for how it looks, so a ${shape} is \`shape: ${look}\``, line);
     }
     // Until 0.3.0 `shape:` also took an icon name and drew the node as that
     // picture. The two jobs are two parts and now have two keys, so an older file

package/dist/lines.d.ts

@@ -11,6 +11,13 @@ export interface Face {
     height: number;
     /** A circle is drawn in this square, so a line meets the circle. */
     round: boolean;
+    /**
+     * Any other outline but a rectangle's, as a polygon on the page, with the
+     * shape's middle: a line meets the polygon, and the lines from the middle
+     * to the box's corners cut it into its four sides.
+     */
+    outline?: Point[];
+    middle?: Point;
 }
 export type Side = 'top' | 'bottom' | 'left' | 'right';
 /** One piece of a drawn line, from where the last one ended: straight, or a cubic. */
@@ -69,6 +76,7 @@ export declare function planSides(layout: Layout): {
 export declare function faceOfNode(node: LayoutNode): Face;
 /** The point a share of the way along a polyline, bends included, or its start or end. */
 export declare function alongLength(trace: Point[], at: number | 'start' | 'end'): Point;
+/** A face's middle: its box's, or a shape's own, which is a triangle's a third of the way from its base. */
 export declare function centerOf(face: Face): Point;
 /** The points with repeats and points in line with both neighbors dropped. */
 export declare function tidyCorners(points: Point[]): Point[];

package/dist/lines.js

@@ -16,6 +16,7 @@ import { GAPS } from './constants.js';
 import { EDGE_ORDER_KEYS, PART_SIDES, WAYS, isPosition } from './ast.js';
 import { SourceError } from './errors.js';
 import { gapPixels } from './place.js';
+import { isBoxy, isRound, lineCrossings, middleOf, rayExit, shapeOf, sideOfPoint, sideStretch, towardOutline } from './outline.js';
 /**
  * How far apart copies of one line run, like lanes on a road (6.5). A fixed
  * step, so adding a copy widens the set by one lane and moves no other lane.
@@ -464,6 +465,9 @@ function meetOutline(face, at, way) {
         if (disc >= 0)
             hits.push(-b - Math.sqrt(disc), -b + Math.sqrt(disc));
     }
+    else if (face.outline) {
+        hits.push(...lineCrossings(face.outline, at, way));
+    }
     else {
         const within = (value, low, size) => value >= low - 0.5 && value <= low + size + 0.5;
         for (const x of [face.x, face.x + face.width]) {
@@ -497,6 +501,10 @@ function leaving(face, from, way) {
         const t = -b + Math.sqrt(Math.max(0, b * b - (fx * fx + fy * fy - r * r)));
         return { x: from.x + way.x * t, y: from.y + way.y * t };
     }
+    if (face.outline) {
+        const t = rayExit(face.outline, from, way) ?? 0;
+        return { x: from.x + way.x * t, y: from.y + way.y * t };
+    }
     const tx = way.x > 1e-9 ? (face.x + face.width - from.x) / way.x : way.x < -1e-9 ? (face.x - from.x) / way.x : Infinity;
     const ty = way.y > 1e-9 ? (face.y + face.height - from.y) / way.y : way.y < -1e-9 ? (face.y - from.y) / way.y : Infinity;
     const t = Math.max(0, Math.min(tx, ty));
@@ -576,13 +584,20 @@ const WAY_VECTOR = {
 const MET_SIDE = { down: 'top', up: 'bottom', left: 'right', right: 'left' };
 /** The drawn rectangle of a node. */
 export function faceOfNode(node) {
-    return {
+    const face = {
         x: node.x,
         y: node.y,
         width: node.width,
         height: node.height,
-        round: node.body.kind === 'shape' && node.body.outline === 'circle',
+        round: node.body.kind === 'shape' && isRound(node.body.outline, node.width, node.height),
     };
+    if (node.body.kind === 'shape' && !isBoxy(node.body.outline) && !face.round) {
+        const { outline, look } = node.body;
+        face.outline = shapeOf(outline, look, node.width, node.height).polygon.map((p) => ({ x: node.x + p.x, y: node.y + p.y }));
+        const middle = middleOf(outline, look, node.width, node.height);
+        face.middle = { x: node.x + middle.x, y: node.y + middle.y };
+    }
+    return face;
 }
 function endOf(edge, which) {
     const node = which === 'from' ? edge.from : edge.to;
@@ -1027,8 +1042,9 @@ function distance(a, b) {
     return Math.hypot(b.x - a.x, b.y - a.y);
 }
 // --- points on a box ------------------------------------------------------------
+/** A face's middle: its box's, or a shape's own, which is a triangle's a third of the way from its base. */
 export function centerOf(face) {
-    return { x: face.x + face.width / 2, y: face.y + face.height / 2 };
+    return face.middle ?? { x: face.x + face.width / 2, y: face.y + face.height / 2 };
 }
 /** The sides a position sits on: `bottom-right` is on the bottom and the right, `top-center` on the top only. */
 function cornerSides(position) {
@@ -1046,9 +1062,12 @@ function positionPoint(face, position) {
         x: horizontal === 'left' ? face.x : horizontal === 'right' ? face.x + face.width : face.x + face.width / 2,
         y: vertical === 'top' ? face.y : vertical === 'bottom' ? face.y + face.height : face.y + face.height / 2,
     };
-    // A circle has no corners; its corner is where the diagonal meets it.
+    // A circle has no corners; its corner is where the diagonal meets it. On
+    // another shape every point is where the line from its middle meets it.
     if (face.round && vertical && horizontal)
         return outlineToward(face, point);
+    if (face.outline)
+        return outlineToward(face, point);
     return point;
 }
 /** A point a fraction of the way along a side, from its left or top end. */
@@ -1066,6 +1085,29 @@ function onSide(face, side, along) {
         const angle = { right: turn, bottom: Math.PI / 2 - turn, left: Math.PI - turn, top: -Math.PI / 2 + turn }[side];
         return { x: center.x + radius * Math.cos(angle), y: center.y + radius * Math.sin(angle) };
     }
+    if (face.outline) {
+        // The side is the stretch of outline between the lines from the middle to
+        // its two corners. `along` lands where the stretch passes it, so a line
+        // down from the middle of one box's bottom meets the next square on; one
+        // past the stretch's ends is placed on it in proportion instead.
+        const stretch = sideStretch(face.outline, centerOf(face), face, side);
+        const key = side === 'top' || side === 'bottom' ? 'x' : 'y';
+        const low = key === 'x' ? face.x : face.y;
+        const size = key === 'x' ? face.width : face.height;
+        const values = stretch.map((p) => p[key]);
+        const lo = Math.min(...values);
+        const hi = Math.max(...values);
+        const target = along >= lo && along <= hi ? along : lo + ((along - low) / size) * (hi - lo);
+        for (let i = 1; i < stretch.length; i++) {
+            const a = stretch[i - 1];
+            const b = stretch[i];
+            if ((a[key] - target) * (b[key] - target) <= 0 && a[key] !== b[key]) {
+                const f = (target - a[key]) / (b[key] - a[key]);
+                return { x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f };
+            }
+        }
+        return Math.abs(stretch[0][key] - target) < Math.abs(stretch[stretch.length - 1][key] - target) ? stretch[0] : stretch[stretch.length - 1];
+    }
     switch (side) {
         case 'top':
             return { x: along, y: face.y };
@@ -1089,6 +1131,8 @@ function outlineToward(face, target) {
         const length = Math.hypot(dx, dy);
         return { x: center.x + (dx / length) * radius, y: center.y + (dy / length) * radius };
     }
+    if (face.outline)
+        return towardOutline(face.outline, center, target);
     const scale = Math.min(dx === 0 ? Infinity : face.width / 2 / Math.abs(dx), dy === 0 ? Infinity : face.height / 2 / Math.abs(dy));
     return { x: center.x + dx * scale, y: center.y + dy * scale };
 }
@@ -1106,6 +1150,8 @@ function headingAt(face, at) {
         const dy = at.y - center.y;
         return Math.abs(dx) >= Math.abs(dy) ? SIDE_NORMAL[dx >= 0 ? 'right' : 'left'] : SIDE_NORMAL[dy >= 0 ? 'bottom' : 'top'];
     }
+    if (face.outline)
+        return SIDE_NORMAL[sideOfPoint(centerOf(face), face, at)];
     distances.sort((a, b) => a[0] - b[0]);
     return SIDE_NORMAL[distances[0][1]];
 }