reladraw 0.22.0 → 0.23.0

package/.claude/skills/reladraw/SKILL.md

@@ -15,7 +15,7 @@ That matters here specifically. You can't see the SVG you produced. With auto-la
 
 ## Check it is installed, and the same version as this skill
 
-This skill teaches reladraw 0.22.0. Once per session, before the first render, run:
+This skill teaches reladraw 0.23.0. Once per session, before the first render, run:
 
 ```
 reladraw --version
@@ -29,8 +29,8 @@ If `reladraw` isn't installed, `npx reladraw` works without installing, and `npm
 
 ## The loop
 
-1. Write a `.reladraw` file.
-2. `reladraw render diagram.reladraw -o diagram.svg`. (`-o -` writes to stdout; the default is the input path with `.svg`.)
+1. Write a `.reladraw` file. Where it goes depends on what it is for. A diagram that belongs to the project, one the user asked to keep or that a README or document will show, goes where they say, or beside what it describes. A diagram drawn only to show the user something, such as an explanation or a sketch of a change, goes in a folder of its own outside the project, such as `~/.cache/reladraw/` or the system's temporary folder, named after what it shows, so the project isn't littered. Nothing is lost if that folder is cleared: the page in step 7 carries its source and saves it.
+2. `reladraw check diagram.reladraw`. It prints errors and findings and writes nothing.
 3. If it fails, the **error** names the line and what to write instead. Fix and re-run.
 4. If it succeeds, read the **findings** it printed. Each is one line saying what may not read as meant, where, and how much:
 
@@ -39,9 +39,9 @@ diagram.reladraw:12: warning(text-overlap): text "statements" covers the top-lef
 diagram.reladraw:9: warning(edge-node-overlap): line api -> db crosses node cache, in and out of its top
 ```
 
-5. Fix each finding in the source, by placing something differently or saying where a line goes, and re-run until there are none. `reladraw check diagram.reladraw` prints the findings without writing the SVG.
+5. Fix each finding in the source, by placing something differently or saying where a line goes, and re-run until there are none.
 6. `reladraw format diagram.reladraw` before handing the file over. It lines statements up in columns and evens out spacing, by the project's `.reladraw-format` if there is one, and changes nothing about what the file draws. A file you wrote then reads like one the user's project already has.
-7. Finish by showing the user the picture. Give the diagram a title with `diagram  title: "…"`, which heads the page, then run `reladraw render diagram.reladraw --page`. It writes `diagram.html`, a page in the diagram's own colors that pans, zooms, goes full screen and saves an SVG or PNG. Open it in the default browser: `xdg-open diagram.html` on Linux, `open diagram.html` on macOS, `start diagram.html` on Windows. Show the page rather than the bare SVG, and don't build a page of your own around it. Open it once per diagram; after later edits, render the page again and tell the user to reload it. Don't open it when there is no display to open it on, as in a remote or headless session, or when the user has said not to; give them the page's path instead.
+7. Finish by showing the user the picture. Give the diagram a title with `diagram  title: "…"`, which heads the page, then run `reladraw render diagram.reladraw --page`. It writes `diagram.html` beside the source, a page in the diagram's own colors that pans, zooms, goes full screen, and saves itself, its source, an SVG or a PNG. For a diagram kept in the project, put the page in the outside folder of step 1 instead, with `-o ~/.cache/reladraw/diagram.html`, so it isn't committed by mistake. Write an SVG only when something will use it, such as a README picture: `reladraw render diagram.reladraw` writes `diagram.svg` beside the source. Open the page in the default browser: `xdg-open diagram.html` on Linux, `open diagram.html` on macOS, `start diagram.html` on Windows. Show the page rather than the bare SVG, and don't build a page of your own around it. Open it once per diagram; after later edits, render the page again and tell the user to reload it. Don't open it when there is no display to open it on, as in a remote or headless session, or when the user has said not to; give them the page's path instead.
 
 A file with no errors and no findings has nothing on top of anything. That is still not the same as a good picture: re-read your source to confirm the arrangement says what you meant, and for a large diagram tell the user you have checked the findings but not seen the render.
 
@@ -136,7 +136,7 @@ edge [<name>] <from> -> <to> ["<text>" [(<placement>)]] [attributes]
 
 ```
 node bob      "Bob the builder" (inside top)  height: 7
-node bob_link "bob.example.com" (size: small)  inside bob bottom-center  shape: none
+node bob_role "builder" (size: small)  inside bob bottom-center  shape: none
 node count    "3"  on bob top-right  shape: circle
 ```
 
@@ -153,6 +153,27 @@ node records "Records"  style: store
 
 `fill` is a box's area, `border` its outline, `line` an edge's line, and a text's color goes in its bracket. `corners: sharp` squares a box's rounded corners, and `border: (color: theme-primary, thickness: thick)` thickens its outline, the box growing to keep its padding. Prefer theme colors, which read in light and dark themes alike: `theme-primary` and `theme-secondary` are the accents, `-subtle` is an accent softened toward the page (the one to fill a box with), `theme-muted` is quieter text. A hex or CSS color stays fixed in every theme.
 
+### Links
+
+```
+node docs  "Documentation"  url: "https://example.com/docs"
+edge api -> db  "SQL"  url: "https://example.com/schema"
+```
+
+**A link goes on the thing it is about, never in a text of its own.** Give the node a `url:`, or give it to a line's text when the link is about the connection. The whole box, or the line's text, becomes clickable. When asked to add links to a diagram, put `url:` on the nodes and lines already there. Don't add nodes to hold links: no column of link texts beside the diagram, and no caption with an address under each box. Add one only when the user asks to see the addresses written out.
+
+```
+// Wrong: a new text beside the thing the link belongs to
+node api_link "github.com/acme/api"  shape: none  right of api
+
+// Right: the link is on the thing itself
+node api "API server"  url: "https://github.com/acme/api"
+```
+
+The address is never drawn; a reader follows it by clicking. A line with no text can't carry one, and neither can a style. Quote the value, since an unquoted `//` starts a comment.
+
+**Offer links; don't add them unasked.** When the things in a diagram have real web addresses, such as the files of a pull request on GitHub, end your reply with one line offering to link each node to its file. Never guess an address, and don't link to files on the local machine.
+
 ## A complete small file
 
 ```

package/.claude/skills/reladraw/reference/syntax.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.22.0
+# Syntax reference — 0.23.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.
 
@@ -199,6 +199,8 @@ node more  icon: crate  right of store
 - **Its ids and class names are renamed**, so two icons that both call a gradient `a` don't collide.
 - **Script is refused**: a `<script>` element or an `on…` attribute.
 
+A letter icon is a few letters in a circle, with `letters:` and, if wanted, its colors: `icon gh  letters: "GH"  fill: #24292f  text: white`. A color left out is the theme's: the circle one of its two accents, picked from the letters so the same letters get the same one, and the letters that accent's own text color. It goes anywhere a picture does, as a node's `icon:`, a `badge:`, or a link's badge.
+
 A file (`icon rack "./rack.svg"`) is found relative to the diagram's own file. Only the command line can read one; in the playground or a web page, paste the SVG. A declared name replaces a built-in of the same name, and declaring one name twice is an error. Every picture is drawn into the output as path data, so the SVG stays standalone.
 
 ### Badges
@@ -1137,7 +1139,22 @@ node store "Store"  right of docs (gap: 12)
 edge docs -> store  "read first"  url: "https://example.com/order"
 ```
 
-`url:` makes a thing clickable in a viewer that follows links. The whole thing is the target: a node's box and everything in it, a line's text. The value is quoted, since an unquoted `//` starts a comment. Nothing about a destination is visible. A container's destination reaches children that name none. A line with no text is refused one, since a line is a target nobody can hit. A style may not carry one.
+`url:` makes a thing clickable in a viewer that follows links. The whole thing is the target: a node's box and everything in it, a line and its text. The value is quoted, since an unquoted `//` starts a comment. Nothing about a destination is visible. A container's destination reaches children that name none. A line with no text may have one; an unseen wider copy of the line takes the click. A style may not carry one.
+
+A thing can have several links, written one after another, each with a name and a badge in a bracket after it:
+
+```
+node api "Orders API"
+  url: "https://app.datadoghq.com/…" (name: "Datadog", icon: "D" (fill: #632ca6, text: white))
+       "https://github.com/…" (name: "GitHub", icon: gh)
+       "https://app.shortcut.com/…" (name: "Shortcut")
+```
+
+- **`name:`** is what a reader is shown, in quotes. A link with none shows its site, such as `github.com`.
+- **`icon:`** is its badge. Quoted, it is letters in a small circle, `icon: "GH"`, whose colors go in a bracket after it, `(fill: #24292f, text: white)`; left out, they are the theme's. Unquoted, it is a picture: a built-in icon, or one declared with `icon <name>` ([Your own icons](#your-own-icons)), which keeps its own colors. With no `icon:`, the badge is the first letter of the name.
+- **In an SVG**, a click follows the first link, and the browser's tooltip lists them all. **On a page** made with `--page`, a click selects the thing and the panel beside the drawing lists its links; a link is followed from there ([A page for looking at a diagram](#a-page-for-looking-at-a-diagram)).
+
+The same address twice in one `url:` is refused.
 
 ## Errors and findings
 
@@ -1196,7 +1213,11 @@ The output is a standalone SVG: every picture is drawn into it as path data, nev
 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 shows the whole diagram and 100% returns it to its own scale. The zoom is always shown, with "Fit" beside it while the whole diagram is in view. There is a full-screen button. The Export menu copies the SVG, or saves it or a PNG, as `render` would draw it. 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.
+`--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. Under the title it says which file it was drawn from and when, such as "drawn from arch.reladraw, 2026-11-05 14:32": the page is a snapshot of the file, and is behind it once the file is edited, until it is rendered again. Drag to pan; scroll, pinch or double-click to zoom; Fit shows the whole diagram and 100% returns it to its own scale. The zoom is always shown, with "Fit" beside it while the whole diagram is in view. There is a full-screen button. The Save menu saves the page itself, as it was written rather than at its current zoom; the `.reladraw` source it was drawn from; or the picture as an SVG or a PNG, as `render` would draw it; or copies the SVG. Each is named after the source file: `arch.html`, `arch.reladraw`, `arch.svg`, `arch.png`. In Chrome and Edge it asks where to save; other browsers put the file with their downloads. 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.
+
+**A click on a box or a line selects it**, and never follows a link. The selection is amber; what feeds it is green and what it feeds is red, the lines dashed and moving the way they run; the rest dims. A line runs from the end without an arrowhead when only one end has one, and otherwise from the end written first. The panel beside the drawing names the selection and lists its links, each with its badge, and the boxes it comes from and goes to; a link opens in a new tab, and a box selects it. One line out lights by default, and the panel's button lights everything upstream and downstream. A box with links underlines its text under the pointer. A click on the background or Escape clears the selection.
+
+Keys: `+` and `-` zoom, `0` fits, `1` is actual size, `f` is full screen, Escape clears the selection.
 
 ### Formatting
 
@@ -1240,7 +1261,7 @@ clause-gap: 2
 
 An unknown setting, one written twice, or a value it doesn't take is an error naming it.
 
-**Breaking a long statement.** With both at a number, a statement up to `wrap-at` stays on one line, one up to `clause-per-line-at` wraps, and a longer one goes one clause to a line. Its length is measured on its own, before columns, so whether it breaks never depends on its neighbors; its first line still lines up with theirs. A break falls only between clauses, never inside one or inside a bracket, so a clause longer than the width stands alone on its line, past it. A statement broken by hand is broken again by these rules, or joined when they leave it short enough; one kept on its lines for a comment among them is left as it is. A comment at the end of a broken statement follows its last line.
+**Breaking a long statement.** With both at a number, a statement up to `wrap-at` stays on one line, one up to `clause-per-line-at` wraps, and a longer one goes one clause to a line. Its length is measured as it would be printed, lined up with its neighbors, so a short statement pushed past the width by a long neighbor's columns breaks too; its first line still lines up with theirs. A statement that can't break, such as a node's name and text with nothing after them, is left as it is, even when its columns carry it past the width. A break falls only between clauses, never inside one or inside a bracket, so a clause longer than the width stands alone on its line, past it. A statement broken by hand is broken again by these rules, or joined when they leave it short enough; one kept on its lines for a comment among them is left as it is. A comment at the end of a broken statement follows its last line.
 
 ```
 // wrap-at: 60
@@ -1317,6 +1338,21 @@ 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.23.0**
+
+- **A box or a line can have several links**, each with a name and a badge: `url: "https://github.com/…" (name: "GitHub", icon: "GH")  "https://app.datadoghq.com/…" (name: "Datadog")`. In an SVG a click follows the first and the tooltip lists them all. See [Destinations](#destinations).
+- **A click on the page selects a box or a line.** The page made with `render --page` lights what feeds it in green and what it feeds in red, and a panel beside the drawing lists its links and the boxes at either end. A click no longer follows a link on the page; the panel does. See [A page for looking at a diagram](#a-page-for-looking-at-a-diagram).
+- **A line with no text can have a link.** It used to be refused as too thin to click; an unseen wider copy of the line now takes the click.
+- **A letter icon**: `icon gh  letters: "GH"  fill: #24292f  text: white` is a few letters in a circle, usable anywhere an icon is. See [Your own icons](#your-own-icons).
+- **The page can save its own source, and itself.** A page made with `render --page` now carries the `.reladraw` file it was drawn from, so whoever is handed the page can get the source back. Its Export menu is now a Save menu: This page, .reladraw source, SVG, PNG and Copy SVG, and in Chrome and Edge each save asks where the file goes. Under its title the page says which file it was drawn from and when, so you can tell whether it is behind the file.
+- **The agent skill keeps throwaway diagrams out of your project.** A diagram drawn only to show you something now goes in a folder outside the project, such as `~/.cache/reladraw/`, and a project's own diagram gets its page there too. While fixing findings it runs `reladraw check`, so no stray SVG is left beside the source.
+
+**0.22.1**
+
+- **`reladraw format` keeps to `wrap-at` once the columns are lined up.** A statement's length used to be measured on its own, before it was lined up with its neighbors, so a short one like `node  api  "API"  layout: column` stayed on one line and was then padded out by a long neighbor's name to nearly twice the width. It is now measured as printed and breaks like any other long statement; `clause-per-line-at` is measured the same way.
+- **Output sent to another program is no longer cut off.** `reladraw format -` and `reladraw render -o -` stopped after the first 64 KB when their output went into a pipe rather than a file, and still reported success, so an editor formatting a large diagram could replace it with a shortened copy. All of it now comes through.
+- **The agent skill puts a link on the thing it belongs to.** Asked to add links, an agent would add a new text node for each one; the skill now says to give the existing node or line a `url:`. When a diagram's things have real web addresses, such as a pull request's files, it offers to link them rather than doing it unasked.
+
 **0.22.0**
 
 - **`reladraw install-skill`** installs the agent skill that came with your reladraw, so it teaches what your copy accepts rather than what the main branch does. It hands the work to `skills`, passing on `-g`, `-a` and the rest. The npm package now carries the skill.

package/README.md

@@ -1,5 +1,7 @@
 # reladraw
 
+<a href="https://news.ycombinator.com/item?id=49858513"><img src="https://hackergit.org/badge/reladraw/reladraw.svg" alt="Hacker News" height="20"></a>
+
 reladraw is a text language for diagrams where you say where things go.
 
 > The language is changing frequently. The playground always runs the newest syntax, so a diagram that draws there today may need a small edit later. An installed copy from npm changes only when you upgrade it.
@@ -90,7 +92,7 @@ To install the skill from the main branch instead, which can run ahead of the re
 
 ## Status
 
-Version 0.22.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.23.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.22.0
+# Syntax reference — 0.23.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.
 
@@ -199,6 +199,8 @@ node more  icon: crate  right of store
 - **Its ids and class names are renamed**, so two icons that both call a gradient `a` don't collide.
 - **Script is refused**: a `<script>` element or an `on…` attribute.
 
+A letter icon is a few letters in a circle, with `letters:` and, if wanted, its colors: `icon gh  letters: "GH"  fill: #24292f  text: white`. A color left out is the theme's: the circle one of its two accents, picked from the letters so the same letters get the same one, and the letters that accent's own text color. It goes anywhere a picture does, as a node's `icon:`, a `badge:`, or a link's badge.
+
 A file (`icon rack "./rack.svg"`) is found relative to the diagram's own file. Only the command line can read one; in the playground or a web page, paste the SVG. A declared name replaces a built-in of the same name, and declaring one name twice is an error. Every picture is drawn into the output as path data, so the SVG stays standalone.
 
 ### Badges
@@ -1137,7 +1139,22 @@ node store "Store"  right of docs (gap: 12)
 edge docs -> store  "read first"  url: "https://example.com/order"
 ```
 
-`url:` makes a thing clickable in a viewer that follows links. The whole thing is the target: a node's box and everything in it, a line's text. The value is quoted, since an unquoted `//` starts a comment. Nothing about a destination is visible. A container's destination reaches children that name none. A line with no text is refused one, since a line is a target nobody can hit. A style may not carry one.
+`url:` makes a thing clickable in a viewer that follows links. The whole thing is the target: a node's box and everything in it, a line and its text. The value is quoted, since an unquoted `//` starts a comment. Nothing about a destination is visible. A container's destination reaches children that name none. A line with no text may have one; an unseen wider copy of the line takes the click. A style may not carry one.
+
+A thing can have several links, written one after another, each with a name and a badge in a bracket after it:
+
+```
+node api "Orders API"
+  url: "https://app.datadoghq.com/…" (name: "Datadog", icon: "D" (fill: #632ca6, text: white))
+       "https://github.com/…" (name: "GitHub", icon: gh)
+       "https://app.shortcut.com/…" (name: "Shortcut")
+```
+
+- **`name:`** is what a reader is shown, in quotes. A link with none shows its site, such as `github.com`.
+- **`icon:`** is its badge. Quoted, it is letters in a small circle, `icon: "GH"`, whose colors go in a bracket after it, `(fill: #24292f, text: white)`; left out, they are the theme's. Unquoted, it is a picture: a built-in icon, or one declared with `icon <name>` ([Your own icons](#your-own-icons)), which keeps its own colors. With no `icon:`, the badge is the first letter of the name.
+- **In an SVG**, a click follows the first link, and the browser's tooltip lists them all. **On a page** made with `--page`, a click selects the thing and the panel beside the drawing lists its links; a link is followed from there ([A page for looking at a diagram](#a-page-for-looking-at-a-diagram)).
+
+The same address twice in one `url:` is refused.
 
 ## Errors and findings
 
@@ -1196,7 +1213,11 @@ The output is a standalone SVG: every picture is drawn into it as path data, nev
 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 shows the whole diagram and 100% returns it to its own scale. The zoom is always shown, with "Fit" beside it while the whole diagram is in view. There is a full-screen button. The Export menu copies the SVG, or saves it or a PNG, as `render` would draw it. 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.
+`--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. Under the title it says which file it was drawn from and when, such as "drawn from arch.reladraw, 2026-11-05 14:32": the page is a snapshot of the file, and is behind it once the file is edited, until it is rendered again. Drag to pan; scroll, pinch or double-click to zoom; Fit shows the whole diagram and 100% returns it to its own scale. The zoom is always shown, with "Fit" beside it while the whole diagram is in view. There is a full-screen button. The Save menu saves the page itself, as it was written rather than at its current zoom; the `.reladraw` source it was drawn from; or the picture as an SVG or a PNG, as `render` would draw it; or copies the SVG. Each is named after the source file: `arch.html`, `arch.reladraw`, `arch.svg`, `arch.png`. In Chrome and Edge it asks where to save; other browsers put the file with their downloads. 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.
+
+**A click on a box or a line selects it**, and never follows a link. The selection is amber; what feeds it is green and what it feeds is red, the lines dashed and moving the way they run; the rest dims. A line runs from the end without an arrowhead when only one end has one, and otherwise from the end written first. The panel beside the drawing names the selection and lists its links, each with its badge, and the boxes it comes from and goes to; a link opens in a new tab, and a box selects it. One line out lights by default, and the panel's button lights everything upstream and downstream. A box with links underlines its text under the pointer. A click on the background or Escape clears the selection.
+
+Keys: `+` and `-` zoom, `0` fits, `1` is actual size, `f` is full screen, Escape clears the selection.
 
 ### Formatting
 
@@ -1240,7 +1261,7 @@ clause-gap: 2
 
 An unknown setting, one written twice, or a value it doesn't take is an error naming it.
 
-**Breaking a long statement.** With both at a number, a statement up to `wrap-at` stays on one line, one up to `clause-per-line-at` wraps, and a longer one goes one clause to a line. Its length is measured on its own, before columns, so whether it breaks never depends on its neighbors; its first line still lines up with theirs. A break falls only between clauses, never inside one or inside a bracket, so a clause longer than the width stands alone on its line, past it. A statement broken by hand is broken again by these rules, or joined when they leave it short enough; one kept on its lines for a comment among them is left as it is. A comment at the end of a broken statement follows its last line.
+**Breaking a long statement.** With both at a number, a statement up to `wrap-at` stays on one line, one up to `clause-per-line-at` wraps, and a longer one goes one clause to a line. Its length is measured as it would be printed, lined up with its neighbors, so a short statement pushed past the width by a long neighbor's columns breaks too; its first line still lines up with theirs. A statement that can't break, such as a node's name and text with nothing after them, is left as it is, even when its columns carry it past the width. A break falls only between clauses, never inside one or inside a bracket, so a clause longer than the width stands alone on its line, past it. A statement broken by hand is broken again by these rules, or joined when they leave it short enough; one kept on its lines for a comment among them is left as it is. A comment at the end of a broken statement follows its last line.
 
 ```
 // wrap-at: 60
@@ -1317,6 +1338,21 @@ 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.23.0**
+
+- **A box or a line can have several links**, each with a name and a badge: `url: "https://github.com/…" (name: "GitHub", icon: "GH")  "https://app.datadoghq.com/…" (name: "Datadog")`. In an SVG a click follows the first and the tooltip lists them all. See [Destinations](#destinations).
+- **A click on the page selects a box or a line.** The page made with `render --page` lights what feeds it in green and what it feeds in red, and a panel beside the drawing lists its links and the boxes at either end. A click no longer follows a link on the page; the panel does. See [A page for looking at a diagram](#a-page-for-looking-at-a-diagram).
+- **A line with no text can have a link.** It used to be refused as too thin to click; an unseen wider copy of the line now takes the click.
+- **A letter icon**: `icon gh  letters: "GH"  fill: #24292f  text: white` is a few letters in a circle, usable anywhere an icon is. See [Your own icons](#your-own-icons).
+- **The page can save its own source, and itself.** A page made with `render --page` now carries the `.reladraw` file it was drawn from, so whoever is handed the page can get the source back. Its Export menu is now a Save menu: This page, .reladraw source, SVG, PNG and Copy SVG, and in Chrome and Edge each save asks where the file goes. Under its title the page says which file it was drawn from and when, so you can tell whether it is behind the file.
+- **The agent skill keeps throwaway diagrams out of your project.** A diagram drawn only to show you something now goes in a folder outside the project, such as `~/.cache/reladraw/`, and a project's own diagram gets its page there too. While fixing findings it runs `reladraw check`, so no stray SVG is left beside the source.
+
+**0.22.1**
+
+- **`reladraw format` keeps to `wrap-at` once the columns are lined up.** A statement's length used to be measured on its own, before it was lined up with its neighbors, so a short one like `node  api  "API"  layout: column` stayed on one line and was then padded out by a long neighbor's name to nearly twice the width. It is now measured as printed and breaks like any other long statement; `clause-per-line-at` is measured the same way.
+- **Output sent to another program is no longer cut off.** `reladraw format -` and `reladraw render -o -` stopped after the first 64 KB when their output went into a pipe rather than a file, and still reported success, so an editor formatting a large diagram could replace it with a shortened copy. All of it now comes through.
+- **The agent skill puts a link on the thing it belongs to.** Asked to add links, an agent would add a new text node for each one; the skill now says to give the existing node or line a `url:`. When a diagram's things have real web addresses, such as a pull request's files, it offers to link them rather than doing it unasked.
+
 **0.22.0**
 
 - **`reladraw install-skill`** installs the agent skill that came with your reladraw, so it teaches what your copy accepts rather than what the main branch does. It hands the work to `skills`, passing on `-g`, `-a` and the rest. The npm package now carries the skill.

package/dist/ast.d.ts

@@ -804,6 +804,12 @@ export interface IconStmt {
      * starting with `<`. Otherwise it names a file.
      */
     pasted: boolean;
+    /** `icon gh  letters: "GH"  fill: …  text: …`: letters in a circle, in place of a picture. */
+    letters?: {
+        letters: string;
+        fill?: string;
+        text?: string;
+    };
     line: number;
 }
 export type Stmt = NodeStmt | EdgeStmt | StyleStmt | DiagramStmt | DefaultStmt | IconStmt | PointStmt | RegionStmt | BundleStmt;

package/dist/cli.js

@@ -45,9 +45,9 @@ const USAGE = `reladraw — draw a diagram from stated placement
               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.
+              pans, zooms, goes full screen, saves itself, its source, 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,
@@ -218,7 +218,7 @@ async function main(argv) {
     let drawn;
     try {
         if (page) {
-            const made = drawPage(source, basename(input).replace(/\.[^.]+$/, ''), options);
+            const made = drawPage(source, basename(input), options);
             drawn = { text: made.html, findings: made.findings };
         }
         else {
@@ -417,7 +417,13 @@ function nearestSettings(folder, found) {
     found.set(folder, result);
     return result;
 }
-main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+// The exit code is set, not exited with: process.exit ends the process at
+// once, and a write to a pipe that hasn't drained yet is lost, which cut
+// `format -` and `render -o -` off at 64 KB. Node exits on its own once the
+// output is written. `./dev.sh pipe` checks it.
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
     process.stderr.write(`reladraw: ${error instanceof Error ? error.message : String(error)}\n`);
-    process.exit(1);
+    process.exitCode = 1;
 });

package/dist/format.js

@@ -280,16 +280,15 @@ function textWidth(text) {
 /** How wide a tab counts as, where a width has to be known. */
 const TAB_WIDTH = 4;
 /**
- * Whether a statement goes past `wrap-at` or `clause-per-line-at`, and if so
- * where its first line ends. Its length is measured on its own, unaligned, so
- * whether one statement breaks never depends on its neighbors. The first line
- * holds the keyword and name, and the texts after them if `first-line` says
- * so, and shares columns with its neighbors like a one-line statement; the
- * clauses after it are laid out by `continuedLines`.
+ * Whether a statement `length` characters long goes past `wrap-at` or
+ * `clause-per-line-at`, and if so where its first line ends. The length is
+ * the line as it would be printed, lined up with its neighbors (see
+ * `layOutItems`). The first line holds the keyword and name, and the texts
+ * after them if `first-line` says so, and shares columns with its neighbors
+ * like a one-line statement; the clauses after it are laid out by
+ * `continuedLines`.
  */
-function breakStatement(item, settings, gap) {
-    const texts = item.cells.map((cell) => cell.text);
-    const length = textWidth(texts.filter((text, at) => text !== '' || at === 0).join(gap));
+function breakStatement(item, settings, length) {
     const perLine = settings['clause-per-line-at'];
     const wrap = settings['wrap-at'];
     const oneEach = perLine === 'always' || (typeof perLine === 'number' && length > perLine);
@@ -338,7 +337,8 @@ function continuedLines(item, indent, settings, gap, gapWidth) {
 function layOutItems(written, settings) {
     const gap = settings['clause-gap'] === 'tab' ? '\t' : ' '.repeat(settings['clause-gap']);
     const gapWidth = settings['clause-gap'] === 'tab' ? 1 : settings['clause-gap'];
-    const items = written.map((item) => (item.kind === 'statement' ? breakStatement(item, settings, gap) : item));
+    // Which statements break is decided further down, once the columns are known.
+    const items = [...written];
     // What lines up in columns: a one-line statement whole, a broken one's first line.
     const aligned = (item) => item.kind === 'statement' ? item.cells : item.kind === 'broken' ? item.first : undefined;
     // Which statements share columns: each is given a group number. A comment
@@ -372,17 +372,20 @@ function layOutItems(written, settings) {
         previous = item;
     });
     // Each group's column widths, and the column its trailing comments start at.
-    const widths = new Map();
+    let widths = new Map();
     const commentAt = new Map();
-    items.forEach((item, index) => {
-        const cells = aligned(item);
-        if (cells === undefined)
-            return;
-        const id = group.get(index);
-        const own = widths.get(id) ?? [];
-        cells.forEach((cell, at) => (own[at] = Math.max(own[at] ?? 0, textWidth(cell.text))));
-        widths.set(id, own);
-    });
+    const measureColumns = () => {
+        widths = new Map();
+        items.forEach((item, index) => {
+            const cells = aligned(item);
+            if (cells === undefined)
+                return;
+            const id = group.get(index);
+            const own = widths.get(id) ?? [];
+            cells.forEach((cell, at) => (own[at] = Math.max(own[at] ?? 0, textWidth(cell.text))));
+            widths.set(id, own);
+        });
+    };
     // Each cell's text, and where on the line it starts.
     const placed = (cells, id) => {
         const own = widths.get(id);
@@ -407,6 +410,50 @@ function layOutItems(written, settings) {
             line += ' '.repeat(one.at - textWidth(line)) + one.text;
         return line;
     };
+    // Which statements break. A statement is measured as it would be printed,
+    // lined up with its neighbors, so a short statement padded out past
+    // `wrap-at` by a long neighbor's columns breaks too. Breaking one takes its
+    // later clauses out of the columns, which can only narrow them and shorten
+    // the rest, so they are broken one at a time, the longest on its own first:
+    // that is the one most likely to be widening a column the others are past
+    // only because of. A statement whose break is settled by its unaligned
+    // length alone, since lining it up can only lengthen it, breaks before the
+    // first measure: one past `clause-per-line-at`, or past `wrap-at` with no
+    // `clause-per-line-at` above it to reach.
+    const ownLength = (item) => textWidth(item.cells.map((cell) => cell.text).filter((text, at) => text !== '' || at === 0).join(gap));
+    const breakAt = (index, length) => {
+        const item = items[index];
+        if (item.kind !== 'statement')
+            return false;
+        const broken = breakStatement(item, settings, length);
+        items[index] = broken;
+        return broken !== item;
+    };
+    const perLine = settings['clause-per-line-at'];
+    const settled = (length) => typeof perLine !== 'number' || length > perLine;
+    items.forEach((item, index) => {
+        if (item.kind !== 'statement')
+            return;
+        const own = ownLength(item);
+        if (settled(own))
+            breakAt(index, own);
+    });
+    for (;;) {
+        measureColumns();
+        let longest;
+        items.forEach((item, index) => {
+            if (item.kind !== 'statement')
+                return;
+            const printed = textWidth(lineOf(item.cells, group.get(index)));
+            if (breakStatement(item, settings, printed) === item)
+                return;
+            const own = ownLength(item);
+            if (longest === undefined || own > longest.own)
+                longest = { index, own, printed };
+        });
+        if (longest === undefined || !breakAt(longest.index, longest.printed))
+            break;
+    }
     items.forEach((item, index) => {
         if (item.kind !== 'statement')
             return;

package/dist/icons.d.ts

@@ -49,7 +49,17 @@ export interface PastedIcon {
     readonly attrs: string;
     readonly inner: string;
 }
-export type Icon = DrawnIcon | PastedIcon;
+/**
+ * `icon gh  letters: "GH"  fill: #24292f  text: white`: letters in a circle.
+ * A color left unsaid is the theme's, chosen from the letters, so the same
+ * letters get the same color in a theme.
+ */
+export interface LetterIcon {
+    readonly letters: string;
+    readonly fill?: string;
+    readonly text?: string;
+}
+export type Icon = DrawnIcon | PastedIcon | LetterIcon;
 /** Line width on the 24-unit grid, scaled with everything else. */
 export declare const ICON_STROKE = 1.1;
 export declare const ICONS: Record<string, Icon>;

package/dist/links.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A node's or a line's links. `url:` takes one address or several, each with
+ * an optional name and badge: `url: "https://github.com/…" (name: "GitHub",
+ * icon: "GH" (fill: #24292f, text: white))`. The parser keeps the first
+ * address under `url`, so everything that follows a single link follows the
+ * first of several, and the whole list under `url.links` when there is more
+ * to say than one bare address.
+ */
+import type { Attrs } from './ast.js';
+export declare const LINKS_KEY = "url.links";
+/** A link's badge: letters in a small circle, or a picture reladraw knows. */
+export type LinkIcon = {
+    letters: string;
+    fill?: string;
+    text?: string;
+} | {
+    picture: string;
+};
+export interface Link {
+    href: string;
+    name?: string;
+    icon?: LinkIcon;
+}
+/** Every link a thing carries, in the order the source writes them. */
+export declare function linksOf(attrs: Attrs): Link[] | undefined;
+/**
+ * What a reader is shown for a link: its name, or its site's address without
+ * the path. Two unnamed links to one site would read the same, so among
+ * `others` that share its site a link shows its whole address after the scheme.
+ */
+export declare function linkLabel(link: Link, others?: readonly Link[]): string;

package/dist/links.js

@@ -0,0 +1,34 @@
+/**
+ * A node's or a line's links. `url:` takes one address or several, each with
+ * an optional name and badge: `url: "https://github.com/…" (name: "GitHub",
+ * icon: "GH" (fill: #24292f, text: white))`. The parser keeps the first
+ * address under `url`, so everything that follows a single link follows the
+ * first of several, and the whole list under `url.links` when there is more
+ * to say than one bare address.
+ */
+export const LINKS_KEY = 'url.links';
+/** Every link a thing carries, in the order the source writes them. */
+export function linksOf(attrs) {
+    const listed = attrs[LINKS_KEY];
+    if (listed !== undefined)
+        return JSON.parse(listed);
+    const url = attrs['url'];
+    return url === undefined ? undefined : [{ href: url }];
+}
+/**
+ * What a reader is shown for a link: its name, or its site's address without
+ * the path. Two unnamed links to one site would read the same, so among
+ * `others` that share its site a link shows its whole address after the scheme.
+ */
+export function linkLabel(link, others = []) {
+    if (link.name !== undefined)
+        return link.name;
+    const host = hostOf(link.href);
+    if (host === undefined)
+        return link.href;
+    const shared = others.some((other) => other !== link && other.name === undefined && hostOf(other.href) === host);
+    return shared ? link.href.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '') : host;
+}
+function hostOf(href) {
+    return href.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#]+)/i)?.[1];
+}

package/dist/model.d.ts

@@ -7,7 +7,7 @@ export interface Rect {
     height: number;
 }
 import type { Line } from './text.js';
-import type { Body } from './icons.js';
+import type { Body, Icon } from './icons.js';
 /** A node with its geometry solved. Coordinates are absolute, origin top-left. */
 /** A distance past each side of a box. */
 export interface Reach {
@@ -312,6 +312,8 @@ export interface Layout {
      * rather than stating one, and styles are otherwise merged away by here.
      */
     markup: Record<string, string>;
+    /** The pictures links' badges name, by name, for the page that draws the badges. */
+    linkIcons: Record<string, Icon>;
     /**
      * What the `diagram` statement said, as written. Nothing here affects
      * geometry; it rides along so the renderer sees the whole compiled document

package/dist/page.d.ts

@@ -3,12 +3,15 @@ import type { DrawOptions } from './index.js';
 /**
  * `reladraw render --page`: one diagram in one self-contained HTML page, made
  * for looking at rather than embedding. The page is the diagram's own colors,
- * headed with its title, and it pans, zooms, goes full screen, saves the SVG
- * or a PNG, lists the findings, and names a box under the pointer. It needs
- * nothing running and fetches nothing, so it can be attached, mailed or
- * committed. `name` is the file's name, the title when the file states none.
+ * headed with its title, and it pans, zooms, goes full screen, saves itself,
+ * its source, the SVG or a PNG, lists the findings, and names a box under the
+ * pointer. It needs nothing running and fetches nothing, so it can be
+ * attached, mailed or committed. `file` is the source file's name, such as
+ * `flow.reladraw`; without its extension it is the title when the file states
+ * none, and the name everything saved from the page is given. The page is a
+ * snapshot of the file at `at`, and says so under its title.
  */
-export declare function drawPage(source: string, name: string, options?: DrawOptions): {
+export declare function drawPage(source: string, file: string, options?: DrawOptions, at?: Date): {
     html: string;
     findings: Finding[];
 };