fastdraw 0.1.1 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/README.md +75 -143
  2. package/agents/AGENTS-snippet.md +5 -0
  3. package/agents/README.md +8 -0
  4. package/agents/claude-skill/fastdraw/SKILL.md +8 -3
  5. package/dist/cli.js +12423 -290
  6. package/dist-embed/embed/draw-CFzc4XD7.js +1070 -0
  7. package/dist-embed/embed/iconSetAll-6ydegXby.js +1 -0
  8. package/dist-embed/embed.js +35 -0
  9. package/dist-embed/fonts/Geist-Bold.ttf +0 -0
  10. package/dist-embed/fonts/Geist-Medium.ttf +0 -0
  11. package/dist-embed/fonts/Geist-Regular.ttf +0 -0
  12. package/dist-embed/fonts/Geist-SemiBold.ttf +0 -0
  13. package/dist-embed/fonts/GeistMono-Medium.ttf +0 -0
  14. package/dist-embed/fonts/GeistMono-Regular.ttf +0 -0
  15. package/dist-embed/fonts/InstrumentSerif-Italic.ttf +0 -0
  16. package/dist-embed/fonts/InstrumentSerif-Regular.ttf +0 -0
  17. package/dist-embed/fonts/LibreFranklin-Bold.ttf +0 -0
  18. package/dist-embed/fonts/LibreFranklin-Medium.ttf +0 -0
  19. package/dist-embed/fonts/LibreFranklin-Regular.ttf +0 -0
  20. package/dist-embed/fonts/LibreFranklin-SemiBold.ttf +0 -0
  21. package/dist-embed/fonts/Newsreader-Italic.ttf +0 -0
  22. package/dist-embed/fonts/Newsreader-Medium.ttf +0 -0
  23. package/dist-embed/fonts/Newsreader-Regular.ttf +0 -0
  24. package/dist-embed/fonts/Newsreader-SemiBold.ttf +0 -0
  25. package/dist-embed/fonts/SketchHand-Regular.ttf +0 -0
  26. package/fonts/Geist-Bold.ttf +0 -0
  27. package/fonts/Geist-Variable.woff2 +0 -0
  28. package/guide/guide.md +41 -8
  29. package/guide/look.md +41 -11
  30. package/guide/swimlane.md +61 -5
  31. package/licenses/phosphor-icons.txt +21 -0
  32. package/package.json +20 -13
package/README.md CHANGED
@@ -1,42 +1,26 @@
1
1
  <div align="center">
2
2
 
3
- <img src="assets/fastdraw-icon.svg" alt="FastDraw" width="96" height="96">
3
+ <img src="assets/fastdraw-icon.svg" alt="FastDraw" width="80" height="80">
4
4
 
5
5
  # FastDraw
6
6
 
7
- **Diagrams that an AI agent writes and a person can edit.**
8
-
9
- An agent writes a diagram as a small text file and places every element itself. A person opens
10
- the same file in a browser editor, changes anything on a free canvas, and the change is saved
11
- back as a small edit to the text. Neither side has to redo the other's work.
12
-
13
- [A first diagram](#a-first-diagram) · [Getting started](#getting-started) · [Commands](#the-command-line-tool) · [Agents](#using-it-with-an-agent) · [Editor](#the-editor) · [Looks](#looks) · [Gallery](#gallery)
14
-
15
- <img src="assets/how-it-works.png" alt="An AI agent writes diagram.fdraw; a person edits the same file in the browser editor; a look file sets the styles" width="860">
7
+ [![npm](https://img.shields.io/npm/v/fastdraw)](https://www.npmjs.com/package/fastdraw)
8
+ [![CI](https://github.com/coccor/fastdraw/actions/workflows/ci.yml/badge.svg)](https://github.com/coccor/fastdraw/actions/workflows/ci.yml)
9
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
16
10
 
17
11
  </div>
18
12
 
19
- > **Status: proof of concept.** The language, the tool and the editor all work, but nothing is
20
- > published as a package yet and details may change.
21
-
22
- ## What you get
13
+ FastDraw is a diagram format and set of tools for diagrams that AI coding agents write and people
14
+ edit. A diagram is a `.fdraw` text file with one element per line and exact coordinates. The
15
+ `fastdraw` command checks the file and renders it to PNG or SVG. The browser editor at
16
+ [fastdraw.dev/edit](https://fastdraw.dev/edit/) opens the same file and saves changes back to it as
17
+ small text edits, so the file stays readable in a diff.
23
18
 
24
- - **A text format agents can get right.** A `.fdraw` file has one statement per line, with exact
25
- coordinates. There is no automatic layout to fight, so what the agent writes is what is drawn.
26
- - **A checker that reads the picture.** `fastdraw check` reports overlapping boxes, arrows that
27
- cross a box, labels that collide and text that does not fit, each with a line number.
28
- - **Looks.** A `.look` file holds named styles, colours, fonts and icons, so a team decides once
29
- how its diagrams are drawn. The same diagram can be drawn with another look.
30
- - **A visual editor.** A static site with no server. It edits the same text file and keeps the
31
- changes minimal, so diffs stay readable.
32
- - **Guides for over forty kinds of diagram.** Architecture, flowchart, sequence, database schema,
33
- Gantt, Sankey, swimlane and more. Each guide tells an agent how to compose that kind well.
34
- - **Pictures you can reopen.** Exported PNG and SVG files carry the diagram and its look inside
35
- them. Drop one on the editor to keep editing. The editor's Export dialog (Ctrl+Shift+E) picks
36
- PNG or SVG, a scale from 1x to 4x, a see-through background, and whether the diagram goes
37
- inside; it downloads the image or copies it to the clipboard.
19
+ <p align="center">
20
+ <img src="assets/how-it-works.png" alt="An AI agent writes diagram.fdraw; a person edits the same file in the browser editor; a look file sets the styles" width="760">
21
+ </p>
38
22
 
39
- ## A first diagram
23
+ ## Example
40
24
 
41
25
  ```
42
26
  shopper: external "Shopper" at 40,60
@@ -50,145 +34,93 @@ legend at 40,172 external="Outside what you own" focal="The service this is abou
50
34
  ```
51
35
 
52
36
  <p align="center">
53
- <img src="assets/example.png" alt="The diagram drawn from the text above: Shopper, Orders API and Orders DB joined by two arrows, with a legend" width="760">
37
+ <img src="assets/example.png" alt="The diagram drawn from the text above: Shopper, Orders API and Orders DB joined by two arrows, with a legend" width="680">
54
38
  </p>
55
39
 
56
- This file is [`assets/example.fdraw`](assets/example.fdraw). It names no look, so it is drawn
57
- with the built-in one.
40
+ There is no automatic layout: what the file says is what is drawn. `fastdraw check` reports
41
+ overlapping boxes, arrows that cross a box, colliding labels and text that does not fit, each with a
42
+ line number, so an agent can fix its own layout before anyone looks at it.
58
43
 
59
44
  ## Getting started
60
45
 
61
- FastDraw needs Node 20 or later. The command-line tool runs through `npx`, so nothing needs installing:
62
-
63
- ```
64
- npx fastdraw setup # tell this repo's coding agents about FastDraw
65
- npx fastdraw check docs/example.fdraw # report problems, with line numbers
66
- npx fastdraw render docs/example.fdraw # write a PNG next to the file
67
- npx fastdraw open docs/example.fdraw # edit it in the browser; changes save back
68
- ```
69
-
70
- The editor is at https://fastdraw.dev/edit/. Agents that read the web can learn the language from
71
- https://fastdraw.dev/llms.txt with no setup at all.
72
-
73
- To work on FastDraw itself (needs Node 22.18 or later, because the sources run as TypeScript directly):
46
+ FastDraw needs Node 20 or later.
74
47
 
75
48
  ```
76
- git clone https://github.com/coccor/fastdraw.git
77
- cd fastdraw
78
- npm install
79
- bin/fastdraw check assets/example.fdraw
80
- npm run dev # the website and editor, at http://localhost:5199
49
+ npx fastdraw setup # add FastDraw instructions for this repo's coding agents
50
+ npx fastdraw check docs/example.fdraw # report problems, with line numbers
51
+ npx fastdraw render docs/example.fdraw # write example.png next to the file
52
+ npx fastdraw open docs/example.fdraw # edit in the browser; changes save to the file
81
53
  ```
82
54
 
83
- ## The command-line tool
55
+ `fastdraw setup` supports Claude Code, Codex, OpenCode and GitHub Copilot. Chat assistants without a
56
+ shell can read the language from https://fastdraw.dev/llms.txt.
84
57
 
85
- | Command | What it does |
86
- |---|---|
87
- | `fastdraw check <file.fdraw>` | Report problems, with line numbers |
88
- | `fastdraw render <file.fdraw> [-o out.png\|.svg] [--scale 2] [--transparent] [--no-embed]` | Draw the diagram (PNG by default). `--transparent` leaves out the page colour and dots; `--no-embed` leaves the diagram out of the image |
89
- | `fastdraw guide [topic]` | Print the language guide, or the guide for one kind of diagram |
90
- | `fastdraw guide list` | List the kinds of diagram that have a guide |
91
- | `fastdraw sizes [file]` | List a look's styles and their sizes (the built-in look when no file is given) |
92
- | `fastdraw icons [file.look] [word]` | List the icons a look offers, or search them by name or meaning (`email` finds `mail`) |
93
- | `fastdraw init-look [path]` | Write the built-in look to a file, to start your own |
94
- | `fastdraw preview-look [file.look]` | Draw every style of a look on one sheet |
95
- | `fastdraw setup [claude\|agents\|copilot] [--global]` | Tell a repo's coding agents about FastDraw: a Claude Code skill, a section in `AGENTS.md`, or in Copilot's instructions. With no name, sets up the agents the repo already uses. Running it again updates them |
96
- | `fastdraw open <file.fdraw> [--editor URL]` | Open the diagram in the web editor with its look, fonts and icons; edits there save back to the file. Runs until Ctrl-C |
58
+ ### Updating
97
59
 
98
- ## Using it with an agent
60
+ The instructions `setup` writes are short: they tell the agent to run `fastdraw guide`, and the guide,
61
+ the kinds of diagram, the looks, `check` and `render` all come from the fastdraw that runs. Through
62
+ `npx fastdraw` that is the newest release, so most of an update arrives by itself.
99
63
 
100
- An agent needs only the `fastdraw` command. `fastdraw guide` teaches it the language and the way
101
- of working: write the file, run `check` until it is clean, then render and look at the picture.
64
+ The instruction files themselves change only when `setup` runs again. Each one carries the version that
65
+ wrote it, and when it is older than the fastdraw running, `fastdraw guide` starts with a note asking the
66
+ agent to tell you. To update them, run this in the repository; it rewrites the skill and replaces only
67
+ FastDraw's own section of `AGENTS.md` or Copilot's instructions:
102
68
 
103
- | Agent | What to do |
104
- |---|---|
105
- | Claude Code | `npx fastdraw setup claude` (adds `.claude/skills/fastdraw/`; `--global` for every repo) |
106
- | Codex, OpenCode | `npx fastdraw setup agents` (adds a section to `AGENTS.md`) |
107
- | GitHub Copilot | `npx fastdraw setup copilot` (adds a section to `.github/copilot-instructions.md`) |
108
- | Chat assistants | Ask it to read https://fastdraw.dev/llms.txt first, or paste that file in; then paste the reply into the editor with "Paste diagram text" |
109
-
110
- More detail is in [`agents/README.md`](agents/README.md).
111
-
112
- ## The editor
69
+ ```
70
+ npx fastdraw@latest setup # or name them: setup claude agents copilot
71
+ npx fastdraw@latest setup claude --global # if you put the skill in ~/.claude
72
+ ```
113
73
 
114
- <p align="center">
115
- <img src="compare/editor-default-look.png" alt="The FastDraw editor with a three-box diagram open, a style panel on the left and a toolbar on top" width="860">
116
- </p>
74
+ If fastdraw is installed on the PATH (`npm install -g fastdraw`), agents use that copy instead of `npx`.
75
+ `fastdraw guide` checks npm for a newer release at most once a day and says so when there is one; update
76
+ with `npm install -g fastdraw@latest`. Set `FASTDRAW_NO_UPDATE_CHECK=1` to turn the check off; it is off on CI.
117
77
 
118
- In Chrome and Edge the editor saves in place and re-reads the file about once a second, so an
119
- agent and a person can work on the same diagram at the same time. Other browsers keep changes in
120
- memory and download the result. Nothing is uploaded; there is no server.
78
+ ## Features
121
79
 
122
- `fastdraw open diagram.fdraw` is the one-step way in, in any browser: it lends the diagram's folder
123
- to the editor at https://fastdraw.dev/edit/ from a small server on `127.0.0.1` (a random link, answered
124
- only for the editor's own address), opens the browser at the diagram, and writes edits back to the
125
- `.fdraw` file. The files never leave the computer. Chrome may ask once to let the page reach apps
126
- on this device. `--editor http://localhost:5173/` points it at a local editor instead.
80
+ - **Checker.** Finds layout problems by measuring the drawn picture, not just parsing the text.
81
+ - **Editor.** Move, resize, restyle and add elements on a canvas. In Chrome and Edge it edits the
82
+ file in place while an agent works on it. Nothing is uploaded.
83
+ - **Looks.** A `.look` file holds named styles, colours, fonts and icons. Twelve ship with
84
+ FastDraw, including the built-in one, and a team can write its own.
85
+ - **Guides for over forty kinds of diagram**, including architecture, flowchart, sequence,
86
+ database schema, Gantt, Sankey and swimlane. Agents read them with `fastdraw guide`.
87
+ - **Exports that reopen.** PNG and SVG files carry the diagram source, so dropping one on the
88
+ editor opens it for editing.
89
+ - **Embedding.** Show a diagram as a live drawing on a docs site with `<fastdraw-diagram>`, or as
90
+ an SVG image in a GitHub README.
127
91
 
128
- `npm run build:editor` writes the website to `dist-editor/` as a static site you can host anywhere: the
129
- landing page at `/`, the editor at `/edit/`, and the guide for agents at `/llms.txt` and `/guide/<kind>.md`.
92
+ ## Gallery
130
93
 
131
- ## Looks
94
+ Written by agents from the guides alone and drawn in the built-in look; sources are in
95
+ [`examples/kinds/`](examples/kinds).
132
96
 
133
- A look is a text file of named styles. Start from the built-in one and change anything:
97
+ | | | |
98
+ |:---:|:---:|:---:|
99
+ | <img src="assets/gallery/deployment.png" alt="Deployment diagram of a checkout service across three zones" width="260"><br>Deployment | <img src="assets/gallery/db-schema.png" alt="Database schema with four tables and their foreign keys" width="260"><br>Database schema | <img src="assets/gallery/swimlane.png" alt="Swimlane diagram of publishing an article across four roles" width="260"><br>Swimlane |
134
100
 
135
- ```
136
- bin/fastdraw init-look team.look
137
- bin/fastdraw preview-look team.look
138
- ```
101
+ ## Documentation
139
102
 
140
- A diagram picks its look with one line, `look "./team.look"`, or names one that ships with FastDraw:
141
- `look headline`, `look night`, `look reference`, `look sketch` or `look whiteboard`. In the editor, the **Look** button
142
- previews the diagram in each one before you keep it. A look can also bring its own fonts
143
- (`fontdir`) and colour icons (`icondir`). `fastdraw guide look` explains the format.
103
+ - [Command-line tool](docs/cli.md): every command and option, and setup for each coding agent
104
+ - [Editor](docs/editor.md): editing in the browser and `fastdraw open`
105
+ - [Looks](docs/looks.md): the bundled looks and writing your own
106
+ - [Showing diagrams on other sites](docs/embedding.md): `<fastdraw-diagram>` and GitHub images
107
+ - The language: `npx fastdraw guide`, or https://fastdraw.dev/llms.txt
144
108
 
145
- ## Gallery
109
+ FastDraw is at version 0.x, and details of the language may still change.
146
110
 
147
- All of these were written by agents from the guides alone. Sources are in
148
- [`examples/kinds/`](examples/kinds); they are drawn here with `looks/reference.look`.
111
+ ## Contributing
149
112
 
150
- | | | |
151
- |:---:|:---:|:---:|
152
- | <img src="compare/kinds/sankey.png" alt="Sankey diagram" width="270"><br>Sankey | <img src="compare/kinds/db-schema.png" alt="Database schema" width="270"><br>Database schema | <img src="compare/kinds/swimlane.png" alt="Swimlane diagram" width="270"><br>Swimlane |
153
- | <img src="compare/kinds/uml-class.png" alt="UML class diagram" width="270"><br>UML class | <img src="compare/kinds/deployment.png" alt="Deployment diagram" width="270"><br>Deployment | <img src="compare/kinds/exploded.png" alt="Exploded layer diagram" width="270"><br>Exploded layers |
154
-
155
- ## Repository layout
156
-
157
- | Path | What it is |
158
- |---|---|
159
- | `src/` | Core: parser, look loader, arrow router, SVG renderer, checker, text-edit operations |
160
- | `src/cli.ts`, `bin/fastdraw` | The command-line tool |
161
- | `guide/` | What an agent reads to learn the language and how to compose each kind of diagram |
162
- | `src/defaultLook.ts` | The built-in look, used when a diagram names none |
163
- | `agents/` | Thin instruction files that point coding agents at `fastdraw guide` |
164
- | `looks/reference.look` | Test look that mirrors diagram-design's default palette, for quality comparison |
165
- | `looks/whiteboard.look` | Whiteboard: an online-whiteboard look with pastel sticky notes, white rounded shapes, curved connectors and one blue accent. Samples in `examples/whiteboard/` |
166
- | `looks/night.look` | Night: the built-in look after dark, on a deep navy page with the same styles, so a diagram can switch with one line |
167
- | `looks/headline.look` | Headline: serif headline over flat newspaper-graphics blocks, one muted crimson accent. An alternative to the built-in look |
168
- | `editor/` | The browser editor (Vite + React) |
169
- | `examples/` | Diagrams written by agents from the guides, and looks used in tests |
170
- | `compare/` | Renders next to the diagram-design originals, plus editor screenshots |
171
- | `fonts/` | Geist, Geist Mono and Newsreader (the built-in look), Libre Franklin and Instrument Serif (SIL Open Font License, texts included) |
172
- | `assets/` | The icon, and the diagrams shown on this page with their sources |
173
- | `test/`, `e2e/` | Core tests and editor tests |
174
-
175
- ## Development
113
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for building from source, running the tests and the
114
+ repository layout.
176
115
 
177
- ```
178
- npm test # core tests
179
- npm run typecheck
180
- npm run test:e2e # editor tests (Playwright)
181
- npm run build:editor # static site in dist-editor/
182
- ```
116
+ ## License
183
117
 
184
- ## Credits
118
+ MIT. See [LICENSE](LICENSE).
185
119
 
186
- The kinds of diagram FastDraw has guides for, and many of the composition ideas in those guides
187
- (how few elements to use, one accent, legends, what makes each kind read well), follow
120
+ The kinds of diagram FastDraw has guides for, and many of the composition ideas in them, follow
188
121
  [diagram-design](https://github.com/cathrynlavery/diagram-design) by Cathryn Lavery (MIT licence,
189
- copyright (c) 2025 Cathryn Lavery). The guides are written anew for FastDraw's language. The
190
- pictures in `compare/kinds/*-ref.png` are renders of diagram-design's own example pages, kept for
191
- side-by-side comparison; `looks/reference.look` mirrors its default palette for the same purpose.
192
-
193
- The bundled icons (`src/icons.ts`) are from [Tabler Icons](https://tabler.io/icons) (MIT licence,
194
- copyright (c) 2020-2024 Paweł Kuna), the same generic set diagram-design uses.
122
+ copyright (c) 2025 Cathryn Lavery); the guides are written anew for FastDraw's language, and
123
+ `looks/reference.look` and `compare/kinds/*-ref.png` mirror it for side-by-side comparison. The
124
+ bundled icons are [Phosphor Icons](https://phosphoricons.com) (MIT licence, copyright (c) 2023
125
+ Phosphor Icons); the licence is in `licenses/phosphor-icons.txt`. The fonts are under the SIL Open
126
+ Font License, with texts in `fonts/`.
@@ -4,7 +4,12 @@
4
4
 
5
5
  Diagrams in this repo are FastDraw files (`.fdraw`), drawn with the look in `.look` files. People edit them visually afterwards.
6
6
 
7
+ - Save a new diagram in `docs/diagrams/` unless the person names another place or the repo already keeps its `.fdraw` files somewhere; never at the top of the repo.
7
8
  - Before writing or changing one, run `fastdraw guide` and follow it; it is the only reference for the language.
9
+ - Choose the kind of diagram by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart); `fastdraw guide list` says what each kind shows. Unless the request names the kind, tell the person which kind you would draw and the closest other kind, and ask before drawing.
8
10
  - Finish with `fastdraw check <file>` clean, then run `fastdraw render <file>` and look at the PNG.
11
+ - `fastdraw check <folder>` and `fastdraw render <folder>` work on every `.fdraw` file under a folder. `fastdraw render <file> --dark` also writes `<file>-dark.png` with the look's dark version, for sites with a dark theme; `--look <name|file.look>` draws with another look without changing the file.
12
+ - When the diagram is done, always ask the person what to do next: open it in fastdraw.dev (run `fastdraw open <file>` in the background, then give them the link it prints in case no browser window appeared; edits save back to the file), preview the PNG (open it in their image viewer), or nothing. Do not open anything before they choose.
13
+ - On a docs site (a web page, not a GitHub README), show a diagram with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js and keep the rendered PNG inside it as the fallback image; see "Embedding a diagram" in FastDraw's README.
9
14
  - When changing an existing diagram, leave the position, size and styling of existing elements alone unless asked.
10
15
  - If `fastdraw` is not on the PATH, run it as `npx fastdraw`.
package/agents/README.md CHANGED
@@ -9,3 +9,11 @@ All three are thin pointers to `fastdraw guide`, so there is one place to mainta
9
9
  | Codex, OpenCode | `npx fastdraw setup agents` | `AGENTS-snippet.md` as a section of `AGENTS.md` |
10
10
  | GitHub Copilot | `npx fastdraw setup copilot` | `AGENTS-snippet.md` as a section of `.github/copilot-instructions.md` |
11
11
  | Chat assistants | none | Ask it to read https://fastdraw.dev/llms.txt first (or paste that file in), then paste the reply into the editor with "Paste diagram text" |
12
+
13
+ ## Diagrams on a docs site
14
+
15
+ A README on GitHub can only show the PNG from `fastdraw render`. A docs site (Starlight, Docusaurus,
16
+ VitePress, plain HTML) can show the `.fdraw` file itself with the `<fastdraw-diagram>` element from
17
+ https://fastdraw.dev/embed.js, keeping the PNG inside it for readers without JavaScript. Both instruction
18
+ files above tell the agent to do that; the element is described under "Embedding a diagram" in the
19
+ main README.
@@ -7,8 +7,13 @@ description: Draw or change a diagram (architecture, flowchart, sequence, or any
7
7
 
8
8
  FastDraw diagrams are small text files (`.fdraw`). You place every element yourself; a look file (`.look`) decides how styles are drawn. People edit the same file in a browser editor afterwards.
9
9
 
10
- 1. Run `fastdraw guide` and follow it. It is the single source for the language and the way of working, and it points to `fastdraw guide architecture|flowchart|sequence` and `fastdraw sizes`.
11
- 2. Always finish with `fastdraw check <file>` clean and a look at the PNG from `fastdraw render <file>`.
12
- 3. When changing an existing diagram, do not move, resize or restyle what is already there unless asked. A person may have arranged it by hand.
10
+ 1. Save a new diagram in `docs/diagrams/` (create the folder), unless the person names another place or the repo already keeps its `.fdraw` files somewhere. Never at the top of the repo: `fastdraw open` lends the diagram's whole folder to the editor.
11
+ 2. Run `fastdraw guide` and follow it. It is the single source for the language and the way of working, and it points to `fastdraw guide list` (what each kind of diagram shows), `fastdraw guide <kind>` and `fastdraw sizes`.
12
+ Choose the kind by what the reader has to understand, not by a word in the request ("request flow" is not a flowchart). Unless the request names the kind, tell the person which kind you would draw and the closest other kind, and ask with AskUserQuestion (your pick first) before drawing. If you cannot ask, draw your pick and say which other kind would also have worked.
13
+ 3. Always finish with `fastdraw check <file>` clean and a look at the PNG from `fastdraw render <file>`.
14
+ 4. When the diagram is done, always ask the person what to do next with AskUserQuestion; do not end your turn without asking. The choices: **Open in fastdraw.dev** (run `fastdraw open <file>` with `run_in_background`, then read its output and give the person the link it prints, in case no browser window appeared; it saves their edits back to the file), **Preview as PNG** (open the rendered PNG in their image viewer) or **Nothing**. Do not open anything before they choose.
15
+ 5. For a site with light and dark themes, `fastdraw render <file or folder> --dark` writes `x.png` and `x-dark.png` (the look's dark version, Night for the built-in look). Do not copy the file to swap its look line; `--look <name|file.look>` draws with another look. A folder means every `.fdraw` file under it, for `check` too.
16
+ 6. When changing an existing diagram, do not move, resize or restyle what is already there unless asked. A person may have arranged it by hand.
17
+ 7. For a docs site (a web page, not a GitHub README), put the diagram on the page with `<fastdraw-diagram src="....fdraw">` from https://fastdraw.dev/embed.js, with the rendered PNG inside it as the fallback image. It draws the file live, pannable and zoomable, and follows the page's dark mode.
13
18
 
14
19
  If the `fastdraw` command is not on the PATH, run it as `npx fastdraw` (for example `npx fastdraw guide`).