fastdraw 0.0.0-stage → 0.1.0
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.
- package/LICENSE +21 -0
- package/README.md +192 -2
- package/agents/AGENTS-snippet.md +10 -0
- package/agents/README.md +11 -0
- package/agents/claude-skill/fastdraw/SKILL.md +14 -0
- package/dist/cli.js +3598 -0
- package/fonts/Geist-Medium.ttf +0 -0
- package/fonts/Geist-Regular.ttf +0 -0
- package/fonts/Geist-SemiBold.ttf +0 -0
- package/fonts/GeistMono-Medium.ttf +0 -0
- package/fonts/GeistMono-Regular.ttf +0 -0
- package/fonts/InstrumentSerif-Italic.ttf +0 -0
- package/fonts/InstrumentSerif-Regular.ttf +0 -0
- package/fonts/LibreFranklin-Bold.ttf +0 -0
- package/fonts/LibreFranklin-Medium.ttf +0 -0
- package/fonts/LibreFranklin-Regular.ttf +0 -0
- package/fonts/LibreFranklin-SemiBold.ttf +0 -0
- package/fonts/Newsreader-Italic.ttf +0 -0
- package/fonts/Newsreader-Medium.ttf +0 -0
- package/fonts/Newsreader-Regular.ttf +0 -0
- package/fonts/Newsreader-SemiBold.ttf +0 -0
- package/fonts/OFL-Geist.txt +93 -0
- package/fonts/OFL-InstrumentSerif.txt +93 -0
- package/fonts/OFL-LibreFranklin.txt +93 -0
- package/fonts/OFL-Newsreader.txt +93 -0
- package/fonts/OFL-SketchHand.txt +49 -0
- package/fonts/SketchHand-Regular.ttf +0 -0
- package/guide/architecture-delta.md +52 -0
- package/guide/architecture.md +28 -0
- package/guide/axonometric-plan.md +54 -0
- package/guide/bar.md +61 -0
- package/guide/data-flow.md +42 -0
- package/guide/db-schema.md +46 -0
- package/guide/dependency.md +38 -0
- package/guide/deployment.md +46 -0
- package/guide/er.md +49 -0
- package/guide/exploded.md +53 -0
- package/guide/fishbone.md +44 -0
- package/guide/flowchart.md +22 -0
- package/guide/gantt.md +48 -0
- package/guide/guide.md +278 -0
- package/guide/heatmap.md +59 -0
- package/guide/high-level.md +38 -0
- package/guide/integration.md +33 -0
- package/guide/it-state.md +33 -0
- package/guide/journey.md +35 -0
- package/guide/kanban.md +53 -0
- package/guide/layers.md +49 -0
- package/guide/line.md +112 -0
- package/guide/look.md +174 -0
- package/guide/loop.md +45 -0
- package/guide/medallion.md +37 -0
- package/guide/nested.md +36 -0
- package/guide/org-chart.md +48 -0
- package/guide/polar.md +57 -0
- package/guide/process.md +41 -0
- package/guide/pyramid.md +46 -0
- package/guide/quadrant.md +44 -0
- package/guide/radar.md +60 -0
- package/guide/sankey.md +53 -0
- package/guide/scatter.md +73 -0
- package/guide/security-matrix.md +47 -0
- package/guide/sequence.md +39 -0
- package/guide/state.md +38 -0
- package/guide/story-map.md +29 -0
- package/guide/swimlane.md +40 -0
- package/guide/timeline.md +49 -0
- package/guide/tree.md +33 -0
- package/guide/treemap.md +67 -0
- package/guide/uml-class.md +59 -0
- package/guide/venn.md +48 -0
- package/guide/wardley.md +35 -0
- package/guide/waterfall.md +47 -0
- package/package.json +59 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 coccor
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,193 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<img src="assets/fastdraw-icon.svg" alt="FastDraw" width="96" height="96">
|
|
4
|
+
|
|
5
|
+
# FastDraw
|
|
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">
|
|
16
|
+
|
|
17
|
+
</div>
|
|
18
|
+
|
|
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
|
|
23
|
+
|
|
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.
|
|
38
|
+
|
|
39
|
+
## A first diagram
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
shopper: external "Shopper" at 40,60
|
|
43
|
+
api: focal "Orders API" sub="REST" at 296,60
|
|
44
|
+
db: store "Orders DB" at 552,56
|
|
45
|
+
|
|
46
|
+
shopper -> api "HTTPS" style=link
|
|
47
|
+
api -> db "writes" style=primary
|
|
48
|
+
|
|
49
|
+
legend at 40,172 external="Outside what you own" focal="The service this is about" store="Holds data"
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
<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">
|
|
54
|
+
</p>
|
|
55
|
+
|
|
56
|
+
This file is [`assets/example.fdraw`](assets/example.fdraw). It names no look, so it is drawn
|
|
57
|
+
with the built-in one.
|
|
58
|
+
|
|
59
|
+
## Getting started
|
|
60
|
+
|
|
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):
|
|
74
|
+
|
|
75
|
+
```
|
|
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
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## The command-line tool
|
|
84
|
+
|
|
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 |
|
|
97
|
+
|
|
98
|
+
## Using it with an agent
|
|
99
|
+
|
|
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.
|
|
102
|
+
|
|
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
|
|
113
|
+
|
|
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>
|
|
117
|
+
|
|
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.
|
|
121
|
+
|
|
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.
|
|
127
|
+
|
|
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`.
|
|
130
|
+
|
|
131
|
+
## Looks
|
|
132
|
+
|
|
133
|
+
A look is a text file of named styles. Start from the built-in one and change anything:
|
|
134
|
+
|
|
135
|
+
```
|
|
136
|
+
bin/fastdraw init-look team.look
|
|
137
|
+
bin/fastdraw preview-look team.look
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
A diagram picks its look with one line, `look "./team.look"`, or names one that ships with FastDraw:
|
|
141
|
+
`look headline`, `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.
|
|
144
|
+
|
|
145
|
+
## Gallery
|
|
146
|
+
|
|
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`.
|
|
149
|
+
|
|
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/headline.look` | Headline: serif headline over flat newspaper-graphics blocks, one muted crimson accent. An alternative to the built-in look |
|
|
167
|
+
| `editor/` | The browser editor (Vite + React) |
|
|
168
|
+
| `examples/` | Diagrams written by agents from the guides, and looks used in tests |
|
|
169
|
+
| `compare/` | Renders next to the diagram-design originals, plus editor screenshots |
|
|
170
|
+
| `fonts/` | Geist, Geist Mono and Newsreader (the built-in look), Libre Franklin and Instrument Serif (SIL Open Font License, texts included) |
|
|
171
|
+
| `assets/` | The icon, and the diagrams shown on this page with their sources |
|
|
172
|
+
| `test/`, `e2e/` | Core tests and editor tests |
|
|
173
|
+
|
|
174
|
+
## Development
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
npm test # core tests
|
|
178
|
+
npm run typecheck
|
|
179
|
+
npm run test:e2e # editor tests (Playwright)
|
|
180
|
+
npm run build:editor # static site in dist-editor/
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Credits
|
|
184
|
+
|
|
185
|
+
The kinds of diagram FastDraw has guides for, and many of the composition ideas in those guides
|
|
186
|
+
(how few elements to use, one accent, legends, what makes each kind read well), follow
|
|
187
|
+
[diagram-design](https://github.com/cathrynlavery/diagram-design) by Cathryn Lavery (MIT licence,
|
|
188
|
+
copyright (c) 2025 Cathryn Lavery). The guides are written anew for FastDraw's language. The
|
|
189
|
+
pictures in `compare/kinds/*-ref.png` are renders of diagram-design's own example pages, kept for
|
|
190
|
+
side-by-side comparison; `looks/reference.look` mirrors its default palette for the same purpose.
|
|
191
|
+
|
|
192
|
+
The bundled icons (`src/icons.ts`) are from [Tabler Icons](https://tabler.io/icons) (MIT licence,
|
|
193
|
+
copyright (c) 2020-2024 Paweł Kuna), the same generic set diagram-design uses.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
<!-- Paste into AGENTS.md (Codex, OpenCode) or .github/copilot-instructions.md (GitHub Copilot). -->
|
|
2
|
+
|
|
3
|
+
## Diagrams
|
|
4
|
+
|
|
5
|
+
Diagrams in this repo are FastDraw files (`.fdraw`), drawn with the look in `.look` files. People edit them visually afterwards.
|
|
6
|
+
|
|
7
|
+
- Before writing or changing one, run `fastdraw guide` and follow it; it is the only reference for the language.
|
|
8
|
+
- Finish with `fastdraw check <file>` clean, then run `fastdraw render <file>` and look at the PNG.
|
|
9
|
+
- When changing an existing diagram, leave the position, size and styling of existing elements alone unless asked.
|
|
10
|
+
- If `fastdraw` is not on the PATH, run it as `npx fastdraw`.
|
package/agents/README.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Telling agents about FastDraw
|
|
2
|
+
|
|
3
|
+
All three are thin pointers to `fastdraw guide`, so there is one place to maintain.
|
|
4
|
+
`npx fastdraw setup` writes them into a repository; running it again updates them in place.
|
|
5
|
+
|
|
6
|
+
| Agent | Command | What it writes |
|
|
7
|
+
|---|---|---|
|
|
8
|
+
| Claude Code | `npx fastdraw setup claude` (`--global` for every repo) | `claude-skill/fastdraw/` as `.claude/skills/fastdraw/` |
|
|
9
|
+
| Codex, OpenCode | `npx fastdraw setup agents` | `AGENTS-snippet.md` as a section of `AGENTS.md` |
|
|
10
|
+
| GitHub Copilot | `npx fastdraw setup copilot` | `AGENTS-snippet.md` as a section of `.github/copilot-instructions.md` |
|
|
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" |
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fastdraw
|
|
3
|
+
description: Draw or change a diagram (architecture, flowchart, sequence, or any boxes-and-arrows picture) as a FastDraw .fdraw file that people can later edit visually. Use when asked to create, update or fix a diagram in a repo that uses FastDraw, or when a .fdraw or .look file is involved.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# FastDraw
|
|
7
|
+
|
|
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
|
+
|
|
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.
|
|
13
|
+
|
|
14
|
+
If the `fastdraw` command is not on the PATH, run it as `npx fastdraw` (for example `npx fastdraw guide`).
|