Show HN: Cascii – A portable ASCII diagram builder written in vanilla JavaScript
238 points
1 month ago
| 24 comments
| github.com
| HN
3 months ago I wanted to draw an ASCII diagram to include in some documentation at work. I found the few tools online to be insufficient, and was suprised there wasn't a more complete tool to get the job done.

Since, I've built Cascii from scratch in vanilla Javascript (I'm not an FE dev, it might be obvious...).

I hope it works alright. Please check out the live version at https://cascii.app, report problems, make diagrams to improve your code's documentation. Hope you enjoy using it.

dimenoz
1 month ago
[-]
This is fantastic. I've always used JavE before but this being a single HTML file is a big+ and packs quite a punch. Kudos to the author!

One question though, how do edit the content later? For example I generated a few diagrams one at a time and pasted those in a local plain text file. Later when I want to edit a particular diagram/part, I tried copy pasted it in, but always got "cannot paste, content leaves canvas" error. If I tried copy-pasting a really small section (e.g. 3x3 table), it pasted it right in the center. Anyway, not sure if that's an intended work flow or not. Great job regardless.

reply
ftr1200
1 month ago
[-]
Glad you asked. Have you checked the online version https://cascii.app

There, all exported drawings come with a short link. This is so that months later anyone reading / seeing can edit their own copy online / keep it up to date.

You can also create an account to manage your own drawings.

Side note - when you use real pasting, it will not remember meaningful information (that's very hard to do elegantly). In your example, I'm guessing that 3x3 table you pasted in could not be properly edited like a table again. Hence, use short links so that Cascii remembers state.

reply
ssriram
1 month ago
[-]
Hi, great app. I'd love to understand how you are maintaining state behind that short url and see if there are ways (sans server) to at least partially recreate state from the exported ascii.

Having an Import from clipboard would truly make this a remarkable app.

reply
ssriram
1 month ago
[-]
After uploading cascii.html to deepseek.com and promptCoding with it, I saw that you had the json representaion in localStorage.

I tried generating the json from the ascii exported to the clipboard but see why this could get very tricky. So, I added an Export (JSON) to file and Import (JSON) from file and placed them in a More Popup component in which I put the existing export button, so the menu bar does not get too crowded. (for code see (1)) -

This now allows me to save the json and import/edit it at a later time - no short url needed and the data stays private.

Your code was well laid out and deepseek was able to make all the changes error-free.

(1) https://github.com/ssr1ram/cascii-core/tree/more-export-impo...

reply
ftr1200
1 month ago
[-]
Nice! Yea it should be easy to use the internal layerManager.import and .encodeAll

This might break state for the online version, but I can do some tweaks and get it merged if you open the PR.

to be clear, the short url feature is useful in that other people can easily edit / update diagrams they see referenced in code comments. If privacy is a concern and you're not distributing the diagram, then indeed exporting JSON is a good way to go.

reply
ssriram
1 month ago
[-]
Having an AI engine understand ascii diagrams and output the JSON would be ideal. Till then here is the PR (1) for a simple import and export.

(1) https://github.com/casparwylie/cascii-core/pull/5

reply
ftr1200
1 month ago
[-]
v1.0.1 now has offline import/export

https://github.com/casparwylie/cascii-core

reply
harvie
1 month ago
[-]
Exactly. Make it importable and i am sold.

Maybe base64 encoded metadata under the diagram? Maybe encode in non-printable characters?

Maybe just use non-printable characters to hint where the corners of objects are?

reply
ftr1200
1 month ago
[-]
I have thought about this a lot. I was going to do some stuff with gzip, but fundementally, I came to the conclusion that the most elegant solution (no hidden chars / extra encoded data coupled with export) might actually be training a neural net to do it. Also, this would mean being able to import diagrams that weren't even made on Cascii. Training data can be self-generated too.

Perhaps a good middle ground would just be offering the gzip dump.

reply
ftr1200
1 month ago
[-]
v1.0.1 now has offline import/export

https://github.com/casparwylie/cascii-core

reply
dimenoz
1 month ago
[-]
Makes sense. Thank you for making and sharing this.
reply
ftr1200
1 month ago
[-]
v1.0.1 now has offline import/export

https://github.com/casparwylie/cascii-core

reply
ccakes
1 month ago
[-]
Looks super cool, congrats!

Monodraw[1] is a similar product delivered as a standalone macOS app. It’s a classic pay once-type license and very polished software. Cannot recommend enough! I’ve always wanted something as good on Linux though, will definitely give this a go!

[1] https://monodraw.helftone.com/

reply
Brajeshwar
1 month ago
[-]
Happy user of Monodraw. I paid for it once a long long time ago and I use it once or twice a year.
reply
kentbrew
1 month ago
[-]
I love this so much. Thanks for using vanilla JS!

Please consider changing the link colors in the scrolling intro to yellow when in dark mode. They were really hard to make out.

reply
macintux
1 month ago
[-]
Very cool, thanks.

One of the saddest days at my current job: when the company I’m contracted to stopped offering Excalidraw in favor of Lucid. I mostly understand the rationale, but the dramatic difference in friction basically shut down all interest I had in using diagrams to help communicate with my team members.

reply
ftr1200
1 month ago
[-]
A co-worker recently showed me this. It seems really good. If they did ASCII diagrams I'd probably have never made this project!
reply
two_handfuls
1 month ago
[-]
This looks amazing! Thank you for making and sharing it. Being able to run it locally is fantastic for work, where one may not be allowed to share "internal details" with unvetted 3rd party companies.
reply
bambax
1 month ago
[-]
Wow. This is absolutely fantastic! Great work! Congrats!

Do you know if there would be a way (in the future) to export existing image diagrams to this format / will there be an API. It would be very cool for archival purposes.

reply
ftr1200
1 month ago
[-]
It really depends how much demand there is. It's a great next step but a lot of work - I was thinking about training a neural net to parse images / 3rd party diagrams into Cascii, but right now I need a break from my screen for a few weeks :)
reply
ftr1200
1 month ago
[-]
v1.0.1 now has offline import/export

https://github.com/casparwylie/cascii-core

reply
smusamashah
1 month ago
[-]
This looks awesome. The way you are dragging things around and the diagonal lines is amazing. Don't think asciiflow or the other one or two tools do this.

Since you are providing a single portable html file (which almost no one does that these days sadly) you may be interested in how sequencediagrams.org handles this. They don't offer sign up, instead have localStorage, Google drive, file export and few other ways.

Also, can you let me open it on the phone with a warning/recommendation to look at github instead of redirecting to it.

reply
ftr1200
1 month ago
[-]
Bit of a nightmare getting this elegant enough on a phone, and doubt anyone wants to draw ASCII digrams on their phone anyway, so not really a priority!
reply
dspillett
1 month ago
[-]
That looks almost exactly like something I've wanted, thought numerous times about making, but never getting around to. Thanks for scratching your itch and mine!
reply
ftr1200
1 month ago
[-]
Really glad to hear it. Enjoy!
reply
wiseowise
1 month ago
[-]
Any chance you can write a blogpost about development of cascii? It looks impressive and it would be nice to take a sneak peek behind your thought process.
reply
ftr1200
1 month ago
[-]
Yeah I'd like to talk about going back to basics with single-HTML / vanilla JS. It was a great experience, though admittedly controversial and I was expecting more people to be anti it.
reply
Rucadi
1 month ago
[-]
Best tool I've seen for diagrams in a long time, Congratulations! I'll use this anywhere.
reply
theanonymousone
1 month ago
[-]
Nice job. Thanks! Also very interesting to have it "distributed" in one html file. Sometimes people forget simple ways to do stuff :)

Is is possible to import and edit diagrams after they have been created?

reply
ftr1200
1 month ago
[-]
Please see https://cascii.app where short links are coupled with your exports
reply
ftr1200
1 month ago
[-]
v1.0.1 now has offline import/export

https://github.com/casparwylie/cascii-core

reply
primitivesuave
1 month ago
[-]
This is amazing, thank you for sharing it. Aside from being a very useful documentation tool, I hope it inspires more people to distribute simple standalone software utilities in this way.
reply
dangoodmanUT
1 month ago
[-]
it's literally just a single html file

legend

reply
leptons
1 month ago
[-]
It's a single 4992 line HTML file, which is the source code, making a lot harder to contribute to or maintain. I'd like it a bit more (and I might even contribute) if it had at least some separation of concerns, and a simple build system even if the build system is just a bash command to concatenate source files into one HTML file (if having 1 HTML file is somehow very important, but it's not).
reply
ftr1200
1 month ago
[-]
I know it's controversial to do things this way, but given it's a personal project and focuses on portability, I think the benefits are worth while.

I have taken care to break things up, comment, etc - if you start at main(), you may find it's not any more difficult to follow than if i'd broken it up. Just because it's one file doesn't mean it doesn't separate concerns.

reply
um1
1 month ago
[-]
One file is great!
reply
leptons
1 month ago
[-]
>"Contributions are very welcomed. Please feel free to submit proposals directly in the form of a PR or Issue."

Good luck getting contributions. I don't have the time to read and understand all 4000+ lines of this very long file. I have ideas, but I'm not even interested in participating because of the format.

reply
wiseowise
1 month ago
[-]
> if having 1 HTML file is somehow very important, but it's not

It is.

reply
leptons
1 month ago
[-]
As a payload that's great. As a source code file, not so great.
reply
ftr1200
1 month ago
[-]
Version 1.0.1 now has offline base64 import / export so you can permanently save drawings offline.
reply
dimenoz
1 month ago
[-]
Excellent! Thank you!
reply
nwroot
1 month ago
[-]
This is amazing thank you. Have been using asciimap or whatever, but this works so much better. Thank you.
reply
jaredwiener
1 month ago
[-]
Really cool -- and congrats!

FYI there's a typo in the link in the README -- points to casci.app instead of cascii.app.

reply
ftr1200
1 month ago
[-]
Fixed. Thanks for raising :)
reply
sdotdev
1 month ago
[-]
Nice job, its really easy to use
reply
nextts
1 month ago
[-]
See myself using this for sure!
reply
0xcb0
1 month ago
[-]
Wow! Great tool, looks so nice and useful. Thanks for building it!
reply
breadchris
1 month ago
[-]
omg this is beautiful, great job!
reply
ftr1200
1 month ago
[-]
Thank you!
reply
newusertoday
1 month ago
[-]
interesting, i generally use artist mode in emacs but this seems to have more options.
reply
shanselman
1 month ago
[-]
genius. I love it. I'll take 14 of these immediately!
reply
LarsenCC
1 month ago
[-]
Omg, crazy haha.
reply
Cypher
1 month ago
[-]
obsidian plugin please
reply