reladraw 0.27.0 → 0.28.0

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

@@ -11,11 +11,11 @@ Every other diagram language hands the arrangement to a layout engine, so where
 
 That matters here specifically. You can't see the SVG you produced. With auto-layout that leaves you guessing; with reladraw the arrangement is in the sentences you just wrote, and where the picture may not read as meant, the tool tells you in words.
 
-**Show every diagram as its page.** Whenever the user is to see a diagram, whether one you drew, one you changed, or an existing file they asked to look at, render it with `--page` and open it in the default browser, as step 7 of the loop says. The bare SVG is for putting into something else, such as a README or a document, not for showing.
+**Show every diagram on its served page.** Whenever the user is to see a diagram, whether one you drew, one you changed, or an existing file they asked to look at, serve it with `reladraw serve`, as step 7 of the loop says. The page redraws whenever the file changes, and the user can edit and save the file from it, so you and the user work on the one file. `render --page` writes a page to send to someone else, and the bare SVG is for putting into something else, such as a README; neither is for showing.
 
 ## Check it is installed, and the same version as this skill
 
-This skill teaches reladraw 0.27.0. Once per session, before the first render, run:
+This skill teaches reladraw 0.28.0. Once per session, before the first render, run:
 
 ```
 reladraw --version
@@ -29,7 +29,7 @@ If `reladraw` isn't installed, `npx reladraw` works without installing, and `npm
 
 ## The loop
 
-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.
+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. Tell the user where it is, so they can move it somewhere lasting if they want to keep 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:
@@ -41,7 +41,9 @@ diagram.reladraw:9: warning(edge-node-overlap): line api -> db crosses node cach
 
 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` 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.
+7. Finish by showing the user the picture. Give the diagram a title with `diagram  title: "…"`, which heads the page, then run `reladraw serve diagram.reladraw` from the folder that holds the file (`cd` there first for a diagram in the outside folder of step 1), in the background, since it runs until stopped. It opens the page in the default browser: the diagram in its own colors, panning, zooming and going full screen, with an editor (Edit, or `e`) whose Save writes the file. Serve each diagram once: the page redraws by itself when you change the file, so there is nothing to tell the user to reload. Serving a second file from the same folder opens its page on the server already running and returns at once. Don't build a page of your own around 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 open it, add `--no-open` and give them the address it prints. When the user wants a page to send to someone, `reladraw render diagram.reladraw --page` writes `diagram.html`, one file that needs nothing running; put it in the outside folder of step 1 with `-o` for a diagram kept in the project, 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.
+
+**The user edits the file too.** On the served page the user can change the diagram and save it, so read the file again before every change you make to it, even one you wrote a minute ago; what you remember may no longer be what is there. After each change, describe it in a few words, which the page's Versions menu shows as yours: `reladraw note diagram.reladraw "moved the cache under the API"`, run from the folder you served. With no server running it notes nothing and says so, which is fine.
 
 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.
 
@@ -193,7 +195,7 @@ Owns the order records. See [the docs](https://example.com/orders).
 """
 ```
 
-**Notes about a thing go in its description, not in a box beside it.** A description is shown when the thing is selected on the `--page` page, and as hover text in an SVG; it is never drawn, so it can run to paragraphs and lists in Markdown. Write a short one on the statement, and a long one with `description for`, after the diagram's statements, so it doesn't crowd them. When several things share one text, name them all after `for`.
+**Notes about a thing go in its description, not in a box beside it.** A description is shown when the thing is selected on the diagram's page, and as hover text in an SVG; it is never drawn, so it can run to paragraphs and lists in Markdown. Write a short one on the statement, and a long one with `description for`, after the diagram's statements, so it doesn't crowd them. When several things share one text, name them all after `for`.
 
 **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.
 

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

@@ -1,4 +1,4 @@
-# Syntax reference — 0.27.0
+# Syntax reference — 0.28.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.
 
@@ -1021,7 +1021,7 @@ guide node column ""  below a  width: 10  height: 20
 
 **A guide does everything its kind does except draw.** It places things, holds children, is placed against, and shapes the lines through it. A `guide node` container's children are drawn; only its box and title aren't. That gives a reserved empty space, a column to align against, or a group with no outline.
 
-Guides are shown by whoever renders the file, not by the file: `--guides` on the command line, the Guides box in the playground. A file that explains its own construction, such as a tutorial, may say `diagram  guides: show`. Shown guides are dashed, in the theme's secondary color, and unfilled. Their look changes per kind with `default guide node`, `default guide edge`, `default guide point` and `default guide region`; a bare `default guide` is refused, listing the four.
+Guides are shown by whoever renders the file, not by the file: `--guides` on the command line, the Guides switch in View on the page and in the playground. A file that explains its own construction, such as a tutorial, may say `diagram  guides: show`. Shown guides are dashed, in the theme's secondary color, and unfilled. Their look changes per kind with `default guide node`, `default guide edge`, `default guide point` and `default guide region`; a bare `default guide` is refused, listing the four.
 
 A container styled with no border is different: the same picture with guides hidden, but showing guides never reveals it. A guide box draws nothing, so it is left out of the overlap and overflow findings.
 
@@ -1257,7 +1257,7 @@ The file and line of the statement at fault, `warning` in a fixed spot, the kind
 
 Kinds are turned on or off by name, in the file or on the command line: `diagram  checks: (edge-crossings: on, crowded-edge-ends: off)`, or `--checks "edge-crossings: on"`. A kind not mentioned keeps its default. A deliberate overlap is stated on the thing itself (`overlap: allow`), not turned off for the whole file.
 
-In the playground, where you are looking at the picture, checks run only when you press Check. The findings are listed under the diagram, apart from errors, and clicking one selects its line.
+On the page and in the playground, the findings are listed in the side panel and redone as you type; an error that stops the diagram drawing heads the list. Clicking a finding lights what its statement drew, and, with the source shown, selects its line.
 
 ## The command line
 
@@ -1278,6 +1278,8 @@ reladraw check diagram.reladraw
 | `--no-checks` | print no findings; errors still print |
 | `-v`, `--version` | print the version |
 
+`reladraw serve diagram.reladraw` opens a page for the diagram that redraws whenever the file changes and can edit and save it, `reladraw serve` with no file opens the playground on this machine, and `reladraw note` describes a change made to a served file; see [A page that follows its file](#a-page-that-follows-its-file).
+
 `reladraw install-skill` installs the agent skill that came with this version of reladraw, for every project, by running `npx skills add` on it with `--copy`. `--claude` installs it in `~/.claude/skills`, `--agents` in `~/.agents/skills` (Codex and others), and both may be given; with neither, it asks, or, with no terminal to ask in, refuses and names them. For any other agent it prints the `skills` command to run.
 
 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.
@@ -1288,11 +1290,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. 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, or press `g` to grab the diagram and pan it with the arrow keys or `h` `j` `k` `l` (Shift for bigger steps, `g` or Escape to let go); 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, and clicking one lights up what its line drew. A box's or a line's name shows under the pointer.
+`--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, or press `g` to grab the diagram and pan it with the arrow keys or `h` `j` `k` `l` (Shift for bigger steps, `g` or Escape to let go); 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 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, and clicking one lights up what its line drew. A box's or a line's name shows under the pointer.
 
 **The View menu** holds the page's settings, each row a switch that says on or off. **Theme** opens a list of themes, and draws the diagram in the one picked, as `--theme` would, keeping the view and the selection; a page or text color the file states holds in every theme. It starts on "Diagram's theme", the one the file names (or dark), which follows the file when it is rendered again. A theme picked by name is the reader's: it holds on every reladraw page in that browser, whatever the file says, until "Diagram's theme" is picked again. **Side panel** shows or hides the panel beside the drawing, which then stays hidden whatever is selected. **Auto-hide panel** shows it only while something is selected or the findings are open, and the findings start folded. Both are remembered by the browser for every page. **Findings**, with their count, open or fold the findings in the panel. **Guides**, with their count, draws the [guides](#guides) as `--guides` does; it starts as the file or `--guides` says, and a change lasts for that page only. Save SVG, PNG and Copy SVG take the theme and the guides as shown.
 
-**From the keyboard**, `m` reaches the bar: it is ringed, each control shows its letter, and a strip under it names where the keys are and which keys work there. `v` opens View, `s` opens Save, and `f` goes full screen. In a menu a row's letter does what the row does, and the menu stays open, so several can be changed in turn: in View, `t` theme, `p` side panel, `a` auto-hide, `f` findings and `g` guides; in Save, `p` this page, `r` the source, `s` SVG, `n` PNG and `c` Copy SVG. The arrow keys and Enter work too. In the theme list the arrows draw the diagram in each theme as they reach it, and Enter keeps the one reached. Backspace steps back one level at a time: from the theme list to View, from a menu to the bar, from the bar to the diagram, and then lets go of a grab, a lit finding and the selection in turn. Escape goes straight back to the plain diagram from anywhere: every menu closes, a theme tried and not kept is dropped, and a grab, a lit finding and the selection are all cleared. With the menus closed, `p` shows or hides the side panel and `f` goes full screen; `+` `-` `0` `1` zoom at every level.
+**From the keyboard**, `m` reaches the bar: it is ringed, each control shows its letter, and a strip under it names where the keys are and which keys work there. `v` opens View, `x` opens Export, and `f` goes full screen. In a menu a row's letter does what the row does, and the menu stays open, so several can be changed in turn: in View, `t` theme, `p` side panel, `a` auto-hide, `f` findings and `g` guides; in Export, `p` this page, `r` the source, `s` SVG, `n` PNG and `c` Copy SVG. The arrow keys and Enter work too. In the theme list the arrows draw the diagram in each theme as they reach it, and Enter keeps the one reached. Backspace steps back one level at a time: from the theme list to View, from a menu to the bar, from the bar to the diagram, and then lets go of a grab, a lit finding and the selection in turn. Escape goes straight back to the plain diagram from anywhere: every menu closes, a theme tried and not kept is dropped, and a grab, a lit finding and the selection are all cleared. With the menus closed, `p` shows or hides the side panel and `f` goes full screen; `+` `-` `0` `1` zoom at every level.
 
 **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. Its description, if it has one, comes last ([Descriptions](#descriptions)). A box with links underlines its text under the pointer. A click on the background, Escape or Backspace clears the selection.
 
@@ -1300,6 +1302,36 @@ reladraw render arch.reladraw --page
 
 Keys: `+` and `-` zoom, `0` fits, `1` is actual size, `f` is full screen, `p` shows or hides the side panel, `s` and `/` select, `n` `i` `l` step from the selection, Escape clears the selection.
 
+### A page that follows its file
+
+```
+reladraw serve arch.reladraw
+```
+
+`serve` opens the same page in the browser, served from this machine and tied to the file: whenever the file changes on disk, whoever changed it, the page draws it again, keeping the view, the theme and the selection. Under the title it says the page is live, and when the file was last read or changed. A file that stops drawing keeps the last picture that drew, with the error at the head of the findings, and draws again as soon as the file does.
+
+**Edit** (or `e`) shows the source beside the picture, colored as in the playground, with the cheatsheet under it, and the picture redraws as you type. The divider between them can be dragged. **Save** (or ⌘S, Ctrl+S) writes the file, and nothing else does; a dot beside the file's name means there is text the file doesn't have. **Format** lays the source out as `reladraw format` would, with the nearest `.reladraw-format`.
+
+If the file changes on disk while the editor holds unsaved text, the text stays, and a strip says the file changed, by whom when that is known, with **Load it** to replace the text with the file's and **Keep mine** to carry on. Saving over a change made since you started editing asks first.
+
+**Versions** (or `o` from the bar) lists the file's versions since the server started, newest first: each one saved from the page, each change on disk, and each change an agent described with `reladraw note`, with its note. Picking one puts it in the editor as unsaved text, to save if you want it back. They are kept only while the server runs.
+
+One server serves the folder it was started in, and only `.reladraw` files inside it, to this machine only. Serving another file from that folder opens its page on the server already running and returns at once. Ctrl-C stops the server, and an open page then says so; it follows the file again when a server is started in the same folder. `--no-open` prints the page's address instead of opening it.
+
+**Export ▾ ▸ This page** saves the diagram as `reladraw render --page` would write it: a page to send, not one tied to the file.
+
+```
+reladraw serve
+```
+
+With no file, `serve` opens the playground, served from this machine: the source shown, the examples, Open…, and the format settings, with your text kept in the browser. Its first **Save** asks for a path inside the folder, such as `docs/flow.reladraw`, and asks before replacing a file already there. From then on the page is tied to that file, as if `serve` had been given it.
+
+```
+reladraw note arch.reladraw "moved the cache under the API"
+```
+
+`note` describes the change just made to a served file, for its Versions list, which shows it as an agent's. With no server serving the folder, it notes nothing, says so, and succeeds.
+
 ### Formatting
 
 ```
@@ -1420,6 +1452,13 @@ 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.28.0**
+
+- **`reladraw serve` opens a page that follows its file.** The page redraws whenever the file changes on disk, edits it beside the picture, and writes it on Save or ⌘S. Unsaved text is never replaced by a change on disk without asking, and a Versions menu keeps the file's recent versions, saved from the page, changed on disk, or described by an agent with **`reladraw note`**. One server serves a folder. See [A page that follows its file](#a-page-that-follows-its-file).
+- **`reladraw serve` with no file opens the playground** on this machine; its first Save names a file in the folder, and the page then follows that file.
+- **The playground is the page.** It gains selection, the side panel, View and the keys. The Guides box and the theme picker are now in View, and the theme picked there no longer writes a `diagram theme:` line into the source. Check is gone: the findings are in the side panel and redone as you type. Examples, Open…, Save…, Format settings, the cheatsheet and the text kept in your browser are as they were.
+- **The page's Save menu is now Export**, opened by `x` from the bar, so that Save can mean writing the file on a served page. On a page with an editor, Export's This page saves a snapshot, as `render --page` writes it.
+
 **0.27.0**
 
 - **The `--page` page selects from the keyboard.** `s` puts a letter on every box and line and a letter selects it; `/` filters what gets a letter by text, `is:node`, `is:edge`, `is:container` or `style:`; with something selected, `n` letters what is one line away, `i` what is inside it and the box it sits in, and `l` its links. See [A page for looking at a diagram](#a-page-for-looking-at-a-diagram).

package/README.md

@@ -47,7 +47,7 @@ npm install -g reladraw
 reladraw render diagram.reladraw -o diagram.svg
 ```
 
-`reladraw check diagram.reladraw` prints the warnings without writing a picture, and `reladraw format diagram.reladraw` lines its statements up in columns. `reladraw render diagram.reladraw --page` writes a page for looking at it in a browser, with pan, zoom, full screen and the warnings beside it.
+`reladraw check diagram.reladraw` prints the warnings without writing a picture, and `reladraw format diagram.reladraw` lines its statements up in columns. `reladraw serve diagram.reladraw` opens it in a browser on a page with pan, zoom, full screen and the warnings beside it, which redraws whenever the file changes and can edit and save it, so you and an agent can work on the one file. `reladraw serve` with no file opens the playground on your machine, and its first Save makes the file. `reladraw render diagram.reladraw --page` writes the same page as one file to send to someone.
 
 Or from a clone, which also gets you the examples:
 
@@ -94,7 +94,7 @@ To install the skill from the main branch instead, which can run ahead of the re
 
 ## Status
 
-Version 0.27.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.28.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.27.0
+# Syntax reference — 0.28.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.
 
@@ -1021,7 +1021,7 @@ guide node column ""  below a  width: 10  height: 20
 
 **A guide does everything its kind does except draw.** It places things, holds children, is placed against, and shapes the lines through it. A `guide node` container's children are drawn; only its box and title aren't. That gives a reserved empty space, a column to align against, or a group with no outline.
 
-Guides are shown by whoever renders the file, not by the file: `--guides` on the command line, the Guides box in the playground. A file that explains its own construction, such as a tutorial, may say `diagram  guides: show`. Shown guides are dashed, in the theme's secondary color, and unfilled. Their look changes per kind with `default guide node`, `default guide edge`, `default guide point` and `default guide region`; a bare `default guide` is refused, listing the four.
+Guides are shown by whoever renders the file, not by the file: `--guides` on the command line, the Guides switch in View on the page and in the playground. A file that explains its own construction, such as a tutorial, may say `diagram  guides: show`. Shown guides are dashed, in the theme's secondary color, and unfilled. Their look changes per kind with `default guide node`, `default guide edge`, `default guide point` and `default guide region`; a bare `default guide` is refused, listing the four.
 
 A container styled with no border is different: the same picture with guides hidden, but showing guides never reveals it. A guide box draws nothing, so it is left out of the overlap and overflow findings.
 
@@ -1257,7 +1257,7 @@ The file and line of the statement at fault, `warning` in a fixed spot, the kind
 
 Kinds are turned on or off by name, in the file or on the command line: `diagram  checks: (edge-crossings: on, crowded-edge-ends: off)`, or `--checks "edge-crossings: on"`. A kind not mentioned keeps its default. A deliberate overlap is stated on the thing itself (`overlap: allow`), not turned off for the whole file.
 
-In the playground, where you are looking at the picture, checks run only when you press Check. The findings are listed under the diagram, apart from errors, and clicking one selects its line.
+On the page and in the playground, the findings are listed in the side panel and redone as you type; an error that stops the diagram drawing heads the list. Clicking a finding lights what its statement drew, and, with the source shown, selects its line.
 
 ## The command line
 
@@ -1278,6 +1278,8 @@ reladraw check diagram.reladraw
 | `--no-checks` | print no findings; errors still print |
 | `-v`, `--version` | print the version |
 
+`reladraw serve diagram.reladraw` opens a page for the diagram that redraws whenever the file changes and can edit and save it, `reladraw serve` with no file opens the playground on this machine, and `reladraw note` describes a change made to a served file; see [A page that follows its file](#a-page-that-follows-its-file).
+
 `reladraw install-skill` installs the agent skill that came with this version of reladraw, for every project, by running `npx skills add` on it with `--copy`. `--claude` installs it in `~/.claude/skills`, `--agents` in `~/.agents/skills` (Codex and others), and both may be given; with neither, it asks, or, with no terminal to ask in, refuses and names them. For any other agent it prints the `skills` command to run.
 
 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.
@@ -1288,11 +1290,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. 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, or press `g` to grab the diagram and pan it with the arrow keys or `h` `j` `k` `l` (Shift for bigger steps, `g` or Escape to let go); 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, and clicking one lights up what its line drew. A box's or a line's name shows under the pointer.
+`--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, or press `g` to grab the diagram and pan it with the arrow keys or `h` `j` `k` `l` (Shift for bigger steps, `g` or Escape to let go); 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 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, and clicking one lights up what its line drew. A box's or a line's name shows under the pointer.
 
 **The View menu** holds the page's settings, each row a switch that says on or off. **Theme** opens a list of themes, and draws the diagram in the one picked, as `--theme` would, keeping the view and the selection; a page or text color the file states holds in every theme. It starts on "Diagram's theme", the one the file names (or dark), which follows the file when it is rendered again. A theme picked by name is the reader's: it holds on every reladraw page in that browser, whatever the file says, until "Diagram's theme" is picked again. **Side panel** shows or hides the panel beside the drawing, which then stays hidden whatever is selected. **Auto-hide panel** shows it only while something is selected or the findings are open, and the findings start folded. Both are remembered by the browser for every page. **Findings**, with their count, open or fold the findings in the panel. **Guides**, with their count, draws the [guides](#guides) as `--guides` does; it starts as the file or `--guides` says, and a change lasts for that page only. Save SVG, PNG and Copy SVG take the theme and the guides as shown.
 
-**From the keyboard**, `m` reaches the bar: it is ringed, each control shows its letter, and a strip under it names where the keys are and which keys work there. `v` opens View, `s` opens Save, and `f` goes full screen. In a menu a row's letter does what the row does, and the menu stays open, so several can be changed in turn: in View, `t` theme, `p` side panel, `a` auto-hide, `f` findings and `g` guides; in Save, `p` this page, `r` the source, `s` SVG, `n` PNG and `c` Copy SVG. The arrow keys and Enter work too. In the theme list the arrows draw the diagram in each theme as they reach it, and Enter keeps the one reached. Backspace steps back one level at a time: from the theme list to View, from a menu to the bar, from the bar to the diagram, and then lets go of a grab, a lit finding and the selection in turn. Escape goes straight back to the plain diagram from anywhere: every menu closes, a theme tried and not kept is dropped, and a grab, a lit finding and the selection are all cleared. With the menus closed, `p` shows or hides the side panel and `f` goes full screen; `+` `-` `0` `1` zoom at every level.
+**From the keyboard**, `m` reaches the bar: it is ringed, each control shows its letter, and a strip under it names where the keys are and which keys work there. `v` opens View, `x` opens Export, and `f` goes full screen. In a menu a row's letter does what the row does, and the menu stays open, so several can be changed in turn: in View, `t` theme, `p` side panel, `a` auto-hide, `f` findings and `g` guides; in Export, `p` this page, `r` the source, `s` SVG, `n` PNG and `c` Copy SVG. The arrow keys and Enter work too. In the theme list the arrows draw the diagram in each theme as they reach it, and Enter keeps the one reached. Backspace steps back one level at a time: from the theme list to View, from a menu to the bar, from the bar to the diagram, and then lets go of a grab, a lit finding and the selection in turn. Escape goes straight back to the plain diagram from anywhere: every menu closes, a theme tried and not kept is dropped, and a grab, a lit finding and the selection are all cleared. With the menus closed, `p` shows or hides the side panel and `f` goes full screen; `+` `-` `0` `1` zoom at every level.
 
 **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. Its description, if it has one, comes last ([Descriptions](#descriptions)). A box with links underlines its text under the pointer. A click on the background, Escape or Backspace clears the selection.
 
@@ -1300,6 +1302,36 @@ reladraw render arch.reladraw --page
 
 Keys: `+` and `-` zoom, `0` fits, `1` is actual size, `f` is full screen, `p` shows or hides the side panel, `s` and `/` select, `n` `i` `l` step from the selection, Escape clears the selection.
 
+### A page that follows its file
+
+```
+reladraw serve arch.reladraw
+```
+
+`serve` opens the same page in the browser, served from this machine and tied to the file: whenever the file changes on disk, whoever changed it, the page draws it again, keeping the view, the theme and the selection. Under the title it says the page is live, and when the file was last read or changed. A file that stops drawing keeps the last picture that drew, with the error at the head of the findings, and draws again as soon as the file does.
+
+**Edit** (or `e`) shows the source beside the picture, colored as in the playground, with the cheatsheet under it, and the picture redraws as you type. The divider between them can be dragged. **Save** (or ⌘S, Ctrl+S) writes the file, and nothing else does; a dot beside the file's name means there is text the file doesn't have. **Format** lays the source out as `reladraw format` would, with the nearest `.reladraw-format`.
+
+If the file changes on disk while the editor holds unsaved text, the text stays, and a strip says the file changed, by whom when that is known, with **Load it** to replace the text with the file's and **Keep mine** to carry on. Saving over a change made since you started editing asks first.
+
+**Versions** (or `o` from the bar) lists the file's versions since the server started, newest first: each one saved from the page, each change on disk, and each change an agent described with `reladraw note`, with its note. Picking one puts it in the editor as unsaved text, to save if you want it back. They are kept only while the server runs.
+
+One server serves the folder it was started in, and only `.reladraw` files inside it, to this machine only. Serving another file from that folder opens its page on the server already running and returns at once. Ctrl-C stops the server, and an open page then says so; it follows the file again when a server is started in the same folder. `--no-open` prints the page's address instead of opening it.
+
+**Export ▾ ▸ This page** saves the diagram as `reladraw render --page` would write it: a page to send, not one tied to the file.
+
+```
+reladraw serve
+```
+
+With no file, `serve` opens the playground, served from this machine: the source shown, the examples, Open…, and the format settings, with your text kept in the browser. Its first **Save** asks for a path inside the folder, such as `docs/flow.reladraw`, and asks before replacing a file already there. From then on the page is tied to that file, as if `serve` had been given it.
+
+```
+reladraw note arch.reladraw "moved the cache under the API"
+```
+
+`note` describes the change just made to a served file, for its Versions list, which shows it as an agent's. With no server serving the folder, it notes nothing, says so, and succeeds.
+
 ### Formatting
 
 ```
@@ -1420,6 +1452,13 @@ 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.28.0**
+
+- **`reladraw serve` opens a page that follows its file.** The page redraws whenever the file changes on disk, edits it beside the picture, and writes it on Save or ⌘S. Unsaved text is never replaced by a change on disk without asking, and a Versions menu keeps the file's recent versions, saved from the page, changed on disk, or described by an agent with **`reladraw note`**. One server serves a folder. See [A page that follows its file](#a-page-that-follows-its-file).
+- **`reladraw serve` with no file opens the playground** on this machine; its first Save names a file in the folder, and the page then follows that file.
+- **The playground is the page.** It gains selection, the side panel, View and the keys. The Guides box and the theme picker are now in View, and the theme picked there no longer writes a `diagram theme:` line into the source. Check is gone: the findings are in the side panel and redone as you type. Examples, Open…, Save…, Format settings, the cheatsheet and the text kept in your browser are as they were.
+- **The page's Save menu is now Export**, opened by `x` from the bar, so that Save can mean writing the file on a served page. On a page with an editor, Export's This page saves a snapshot, as `render --page` writes it.
+
 **0.27.0**
 
 - **The `--page` page selects from the keyboard.** `s` puts a letter on every box and line and a letter selects it; `/` filters what gets a letter by text, `is:node`, `is:edge`, `is:container` or `style:`; with something selected, `n` letters what is one line away, `i` what is inside it and the box it sits in, and `l` its links. See [A page for looking at a diagram](#a-page-for-looking-at-a-diagram).

package/dist/cli.js

@@ -10,6 +10,7 @@ import { format } from './format.js';
 import { DEFAULT_FORMAT, readFormatSettings, SETTINGS_FILE, settingsFileText } from './format-settings.js';
 import { draw } from './index.js';
 import { drawPage } from './page.js';
+import { noteCommand, serve } from './serve.js';
 import { THEME_NAMES, THEMES } from './themes.js';
 const USAGE = `reladraw — draw a diagram from stated placement
 
@@ -19,6 +20,8 @@ const USAGE = `reladraw — draw a diagram from stated placement
   reladraw format <input.reladraw>... [--check]
   reladraw format - [--check]
   reladraw format --init
+  reladraw serve [<input.reladraw>] [--no-open]
+  reladraw note <input.reladraw> "<what changed>"
   reladraw install-skill [--claude] [--agents]
 
   render      draw the diagram to an SVG, and print any findings: places
@@ -35,6 +38,13 @@ const USAGE = `reladraw — draw a diagram from stated placement
               folder up.
               --init writes a .reladraw-format here, every setting at its
               default with what it does.
+  serve       open a page for the diagram, served on this machine, that
+              redraws whenever the file changes, and edits and saves it. One
+              server serves the folder it was started in, until Ctrl-C;
+              serving another file there opens a page on it. --no-open
+              prints the address.
+  note        describe the change just made to a served file; the page's
+              Versions menu shows it as the agent's, with the note.
   install-skill
               install the agent skill that came with this version of
               reladraw, so it teaches what this tool accepts, for every
@@ -60,7 +70,7 @@ const USAGE = `reladraw — draw a diagram from stated placement
               print the version.
   -h, --help  print this.
 `;
-const COMMANDS = ['render', 'check', 'format', 'install-skill'];
+const COMMANDS = ['render', 'check', 'format', 'serve', 'note', 'install-skill'];
 // The version of skills this was tried with, so a change there can't break it.
 const SKILLS_PACKAGE = 'skills@1.7.6';
 // The two places the skill is installed, each picked by its flag. skills
@@ -185,6 +195,10 @@ async function main(argv) {
     // install-skill reads its own flags, -h included.
     if (argv[0] === 'install-skill')
         return installSkill(argv.slice(1));
+    if (argv[0] === 'serve')
+        return serve(argv.slice(1));
+    if (argv[0] === 'note')
+        return noteCommand(argv.slice(1));
     if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
         process.stdout.write(USAGE);
         return argv.length === 0 ? 1 : 0;

package/dist/examples.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The examples a page with no file offers, in the order its picker lists
+ * them: the hosted playground, and `reladraw serve` with no file. Every
+ * construct in the language is demonstrated by one of these files, so leaving
+ * them out makes the playground a five-line demo. The list is stated rather
+ * than globbed: the order is the point (the benchmark first, then placement,
+ * appearance, edges), and a new file under examples/ is not automatically
+ * something a stranger should be handed.
+ *
+ * Each file is listed under the name a stranger sees, with one short sentence
+ * shown above its preview. The file names are coverage and are referred to
+ * elsewhere; these are for someone who has not read the syntax yet, and say
+ * what the picture shows. Keep the sentence to one line: the file's own
+ * opening comment is there for anyone who wants more.
+ */
+export declare const OFFERED: readonly (readonly [file: string, name: string, about: string])[];
+/**
+ * The first thing a new visitor sees. No comments in it: every statement says
+ * where a node goes, which is the whole point, and a paragraph explaining that
+ * in advance only gets in the way.
+ */
+export declare const START: {
+    name: string;
+    about: string;
+    source: string;
+};

package/dist/examples.js

@@ -0,0 +1,56 @@
+/**
+ * The examples a page with no file offers, in the order its picker lists
+ * them: the hosted playground, and `reladraw serve` with no file. Every
+ * construct in the language is demonstrated by one of these files, so leaving
+ * them out makes the playground a five-line demo. The list is stated rather
+ * than globbed: the order is the point (the benchmark first, then placement,
+ * appearance, edges), and a new file under examples/ is not automatically
+ * something a stranger should be handed.
+ *
+ * Each file is listed under the name a stranger sees, with one short sentence
+ * shown above its preview. The file names are coverage and are referred to
+ * elsewhere; these are for someone who has not read the syntax yet, and say
+ * what the picture shows. Keep the sentence to one line: the file's own
+ * opening comment is there for anyone who wants more.
+ */
+export const OFFERED = [
+    ['arch', 'architecture', "A home network's file sync and backups, redrawn from a draw.io diagram."],
+    ['regions', 'beside a group', 'A node placed against several others at once.'],
+    ['points', 'points and regions', 'Places said in words and worked out from named things; turn on Guides in View to see how.'],
+    ['gaps', 'gap sizes', 'Tight, wide and no gap, each on its own placement; a node has none of its own.'],
+    ['snug', 'exactly as far', 'A gap is the distance asked for, not a minimum.'],
+    ['contents', 'inside a container', 'How children line up in a container wider than they are.'],
+    ['shapes', 'shapes', 'The outlines a node can be drawn with, and the pictures it can be drawn as.'],
+    ['icons', 'icons', 'The seven icons, and the ways to use one.'],
+    ['overlays', 'sides and corners', 'Nodes placed against part of another node: a side, a corner, or its text.'],
+    ['frames', "on the parent's edge", "A child placed on its own container's side or corner."],
+    ['text', 'room for labels', "A line's text takes no room of its own; the gap it sits in is stated."],
+    ['lanes', 'side by side', 'Lines between the same two sides fan out as copies, and copies never cross.'],
+    ['coincident', 'parallel edges', 'Several lines between the same two nodes: copies, or a bundle that bows them apart.'],
+    ['bundles', 'bundles', 'Lines that travel together, each in its own lane, in one order across.'],
+    ['corridors', 'through a gap', 'Lines sent through the point between two named nodes with via:.'],
+    ['passes', 'saying where a line goes', 'Sides and points a line passes, named with via:.'],
+    ['overhang', 'outside the nodes', 'Lines that run past the nodes, and the page grows to hold them.'],
+    ['routing', 'going round boxes', 'Every routing bug reported so far, each line now stating its course.'],
+    ['lines', 'line styles', 'Straight, square and curved lines, dashes, and how crossings are drawn.'],
+    ['linetexts', 'texts on lines', "Where a line's text sits: the middle, a fraction along, beside, or a gap from an end."],
+    ['marks', 'line ends', 'Arrowheads, dots, diamonds and bars at either end of a line, or none.'],
+];
+/**
+ * The first thing a new visitor sees. No comments in it: every statement says
+ * where a node goes, which is the whole point, and a paragraph explaining that
+ * in advance only gets in the way.
+ */
+export const START = {
+    name: 'start',
+    about: 'Three boxes in a row, each a stated distance from the last.',
+    source: [
+        'node parser "Parser"',
+        'node resolver "Resolver"  right of parser (gap: 12)',
+        'node renderer "Renderer"  right of resolver (gap: 12)',
+        '',
+        'edge parser -> resolver    "statements"',
+        'edge resolver -> renderer  "layout"',
+        '',
+    ].join('\n'),
+};

package/dist/page-data.d.ts

@@ -0,0 +1,130 @@
+import { type Finding } from './checks.js';
+import type { DrawOptions } from './index.js';
+import { type Theme } from './themes.js';
+/**
+ * What a page shows of one diagram: its drawing in every theme, what can be
+ * selected in it, and its findings. `page.ts` writes these into a page; a page
+ * that redraws as it is edited makes them in the browser, so this module is
+ * kept apart from the page's own markup and script, which it has no need of.
+ */
+/**
+ * The page's data for `source`, as a served page takes it when its file
+ * changes or its editor is typed in: the same parse, layout, drawings and
+ * findings `drawPage` puts in the page it writes. Runs in the browser too.
+ */
+export declare function pageData(source: string, file: string, options?: DrawOptions, at?: Date): {
+    title: string;
+    drawn: string;
+    data: PageData;
+};
+export declare function partsOf(source: string, file: string, options: DrawOptions, at: Date): PageParts;
+export interface PageParts {
+    title: string;
+    /** What a saved file is called, before its extension. */
+    name: string;
+    /** The line under the title saying which file the page was drawn from, and when. */
+    drawn: string;
+    /** The `.reladraw` text the page was drawn from, which Save gives back. */
+    source: string;
+    findings: Finding[];
+    /** The diagram in each theme the picker offers, by name, with guides as the page opens. */
+    themes: Record<string, ThemeView>;
+    /** The same with guides the other way, or null when the diagram has none. */
+    flipped: Record<string, ThemeView> | null;
+    /** Whether the page opens with guides shown. */
+    guidesShown: boolean;
+    /** How many guides the diagram has, which the View menu shows. */
+    guideCount: number;
+    /** The theme the page opens in. */
+    current: string;
+    graph: Graph;
+}
+/** The diagram drawn in one theme, and the page's colors to go with it. */
+interface ThemeView {
+    /** The SVG as `render` writes it, which is what Save SVG and Save PNG save. */
+    svg: string;
+    /** The same drawing with each thing grouped and named, which is what is shown. */
+    tagged: string;
+    theme: Theme;
+    /** The page's own colors, as CSS custom properties. */
+    colors: Record<string, string>;
+    /** The browser's controls: `dark`, `light`, or `light dark` when it can't be told. */
+    scheme: string;
+}
+/** A link as the panel shows it: where it goes, what it is called, and its badge drawn in each theme. */
+interface LinkView {
+    href: string;
+    label: string;
+    badges: Record<string, string>;
+}
+/**
+ * What a click on the page selects, and what the panel says about it: every
+ * node with its text and links, and every line with its two ends, upstream
+ * first. A line's index is its place in the layout, which `data-edge` names.
+ */
+interface Graph {
+    nodes: Record<string, GraphNode>;
+    edges: {
+        up: string;
+        down: string;
+        label: string;
+        links: LinkView[];
+        description?: string;
+        /** The styles it wears, by name, which a filter's `style:` matches. */
+        styles: string[];
+        guide?: true;
+    }[];
+}
+interface GraphNode {
+    label: string;
+    links: LinkView[];
+    description?: string;
+    /** Where it is in the drawing's own units, `[x, y, width, height]`: where its letter goes, even when it draws nothing. */
+    box: number[];
+    /** The box it sits in, if any. */
+    parent?: string;
+    /** The boxes inside it, in the order written, leaving out a picture `badge:` puts beside its text. */
+    children: string[];
+    styles: string[];
+    guide?: true;
+    /** The picture a `badge:` writes out: part of its box's heading, never picked on its own. */
+    badge?: true;
+    /** Text with no outline and nothing inside, whose letter goes beside it rather than over its first words. */
+    bare?: true;
+}
+export type PageData = ReturnType<typeof dataOf>;
+export declare function dataOf({ name, source, findings, themes, flipped, guidesShown, guideCount, current, graph }: PageParts): {
+    name: string;
+    source: string;
+    current: string;
+    varies: string;
+    themeGroups: {
+        dark: string[];
+        light: string[];
+    };
+    themes: {
+        [k: string]: {
+            svg: string | string[];
+            tagged: string | string[];
+            colors: Record<string, string>;
+            scheme: string;
+        };
+    };
+    flipped: {
+        [k: string]: {
+            svg: string | string[];
+            tagged: string | string[];
+            colors: Record<string, string>;
+            scheme: string;
+        };
+    } | null;
+    guidesShown: boolean;
+    guideCount: number;
+    findings: {
+        kind: "text-overlap" | "text-overflow" | "edge-node-overlap" | "edge-overlap" | "crowded-edge-ends" | "node-overlap" | "node-overflow" | "edge-no-length" | "edge-crossings";
+        message: string;
+        line: number;
+    }[];
+    graph: Graph;
+};
+export {};