reladraw 0.22.1 → 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.1. 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.
 

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

@@ -1,4 +1,4 @@
-# Syntax reference — 0.22.1
+# 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
 
@@ -1317,6 +1338,15 @@ 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.

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.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.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.1
+# 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
 
@@ -1317,6 +1338,15 @@ 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.

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 {

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[];
 };