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
@@ -0,0 +1,35 @@
1
+ function k(t,e,i){return t==="light"||t==="dark"?t:e==="light"||e==="dark"?e:i?"dark":"light"}function w(t){let e=t.dataset.theme;return e==="light"||e==="dark"?e:t.classList.contains("dark")?"dark":t.classList.contains("light")?"light":null}function v(t,e){let i=e?.dark??(t?void 0:"night");return i&&i!==t?i:null}function M(t){let e="";for(let i=0;i<t.length;i+=32768)e+=String.fromCharCode(...t.subarray(i,i+32768));return btoa(e).replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"")}async function A(t,e){let i=new Blob([t]).stream().pipeThrough(e).getReader(),s=[],a=0;for(;;){let{done:r,value:o}=await i.read();if(r)break;if(a+=o.length,a>4e6)throw await i.cancel(),Error("too large");s.push(o)}let n=new Uint8Array(a),h=0;for(let r of s)n.set(r,h),h+=r.length;return n}async function L(t){let e=JSON.stringify(t.look?{name:t.name,text:t.text,look:t.look}:{name:t.name,text:t.text});return M(await A(new TextEncoder().encode(e),new CompressionStream("deflate-raw")))}async function E(t,e){let i=new URL(t);return i.hash="fdraw="+await L(e),i.href}var C=new URL("fonts/",""+import.meta.url).href,f=()=>import("./embed/draw-CFzc4XD7.js"),m=t=>`<svg viewBox="0 0 24 24" aria-hidden="true"><path d="${t}"/></svg>`,u={in:m("M10.5 4a6.5 6.5 0 1 1 0 13a6.5 6.5 0 0 1 0-13zM15.3 15.3 20 20M7.5 10.5h6M10.5 7.5v6"),out:m("M10.5 4a6.5 6.5 0 1 1 0 13a6.5 6.5 0 0 1 0-13zM15.3 15.3 20 20M7.5 10.5h6"),fit:m("M4 9V5.5A1.5 1.5 0 0 1 5.5 4H9M15 4h3.5A1.5 1.5 0 0 1 20 5.5V9M20 15v3.5a1.5 1.5 0 0 1-1.5 1.5H15M9 20H5.5A1.5 1.5 0 0 1 4 18.5V15"),full:m("M14 4h6v6M10 20H4v-6M20 4l-6.5 6.5M4 20l6.5-6.5"),exit:m("M20 10h-6V4M4 14h6v6M14 10l6.5-6.5M10 14l-6.5 6.5"),open:m("M13 4h7v7M20 4l-9 9M17 14v4.5a1.5 1.5 0 0 1-1.5 1.5h-10A1.5 1.5 0 0 1 4 18.5v-10A1.5 1.5 0 0 1 5.5 7H10")},F=`
2
+ :host { display: block; position: relative; }
3
+ :host([hidden]) { display: none; }
4
+ [hidden] { display: none !important; }
5
+ .frame { position: relative; width: 100%; aspect-ratio: var(--fd-ratio, 2); overflow: hidden; outline: none; }
6
+ .frame:fullscreen { width: 100vw; height: 100vh; max-height: none !important; aspect-ratio: auto; }
7
+ .view { position: absolute; inset: 0; touch-action: pan-y; cursor: default; outline: none; }
8
+ .view.pannable { touch-action: none; cursor: grab; }
9
+ .view.dragging { cursor: grabbing; }
10
+ .view:focus-visible { box-shadow: inset 0 0 0 2px #dc2f2f; }
11
+ .view svg { display: block; width: 100%; height: 100%; user-select: none; -webkit-user-select: none; }
12
+ .bar {
13
+ position: absolute; top: 8px; right: 8px; display: flex; align-items: center; gap: 1px; padding: 3px;
14
+ background: rgba(255, 255, 255, 0.94); border: 1px solid #e4e4e7; border-radius: 10px;
15
+ box-shadow: 0 1px 2px rgba(24, 24, 27, 0.06), 0 2px 8px rgba(24, 24, 27, 0.05);
16
+ opacity: 0; transition: opacity 0.15s;
17
+ }
18
+ .frame:hover .bar, .frame:focus-within .bar { opacity: 1; }
19
+ @media (hover: none) { .bar { opacity: 1; } }
20
+ @media (prefers-reduced-motion: reduce) { .bar { transition: none; } }
21
+ .bar button, .bar a {
22
+ all: unset; box-sizing: border-box; display: grid; place-items: center; width: 28px; height: 28px;
23
+ border-radius: 7px; color: #52525b; cursor: pointer;
24
+ }
25
+ .bar button:hover, .bar a:hover { background: #fde3e1; color: #dc2f2f; }
26
+ .bar button:focus-visible, .bar a:focus-visible { outline: 2px solid #dc2f2f; outline-offset: -1px; }
27
+ .bar button:disabled { opacity: 0.35; cursor: default; background: none; color: #52525b; }
28
+ .bar .sep { width: 1px; height: 16px; margin: 0 3px; background: #e4e4e7; }
29
+ .bar svg { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.75; stroke-linecap: round; stroke-linejoin: round; }
30
+ .frame.dark .bar { background: rgba(24, 24, 27, 0.92); border-color: #3f3f46; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3); }
31
+ .frame.dark .bar button, .frame.dark .bar a { color: #a1a1aa; }
32
+ .frame.dark .bar button:hover, .frame.dark .bar a:hover { background: rgba(255, 107, 95, 0.2); color: #ffb4ab; }
33
+ .frame.dark .bar .sep { background: #3f3f46; }
34
+ .frame.dark .view:focus-visible { box-shadow: inset 0 0 0 2px #ff6b5f; }
35
+ `,S=typeof matchMedia=="function"?matchMedia("(prefers-reduced-motion: reduce)"):null,p=typeof matchMedia=="function"?matchMedia("(prefers-color-scheme: dark)"):null,b=new Set,y=!1;function $(){if(y)return;y=!0;let t=()=>b.forEach(e=>e.themeChanged());new MutationObserver(t).observe(document.documentElement,{attributes:!0,attributeFilter:["data-theme","class"]}),p?.addEventListener("change",t)}var x=class extends HTMLElement{static observedAttributes=["src","theme","max-height","editor"];#x;#s;#i;#m;#c;#l=null;#e=null;#L=null;#d=0;#t={x:0,y:0,k:1};#a=0;#r=0;#o=!0;#u=0;#n=new Map;#b=!1;constructor(){super();let t=this.attachShadow({mode:"open"});t.innerHTML=`<style>${F}</style><div class="fallback"><slot></slot></div><div class="frame" part="frame" hidden><div class="view" part="view" tabindex="0" role="img"></div><div class="bar" part="toolbar" role="toolbar" aria-label="Diagram controls"><button type="button" data-act="in" aria-label="Zoom in" title="Zoom in (+)">${u.in}</button><button type="button" data-act="out" aria-label="Zoom out" title="Zoom out (\u2212)">${u.out}</button><button type="button" data-act="fit" aria-label="Fit to view" title="Fit (0)">${u.fit}</button><button type="button" data-act="full" aria-label="Full screen" title="Full screen">${u.full}</button><span class="sep"></span><a class="open" target="_blank" rel="noopener" aria-label="Open in FastDraw" title="Open in FastDraw">${u.open}</a></div></div>`,this.#x=t.querySelector(".fallback"),this.#s=t.querySelector(".frame"),this.#i=t.querySelector(".view"),this.#m=t.querySelector("a.open"),this.#c=t.querySelector("[data-act=full]"),document.fullscreenEnabled||(this.#c.hidden=!0),t.querySelector(".bar").addEventListener("click",i=>{let s=i.target.closest("button")?.dataset.act;s==="in"?this.zoomBy(1.4):s==="out"?this.zoomBy(1/1.4):s==="fit"?this.fit():s==="full"&&this.#O()}),this.addEventListener("keydown",i=>this.#T(i));let e=this.#i;e.addEventListener("pointerdown",i=>this.#D(i)),e.addEventListener("pointermove",i=>this.#H(i)),e.addEventListener("pointerup",i=>this.#z(i)),e.addEventListener("pointercancel",i=>this.#z(i)),e.addEventListener("wheel",i=>this.#U(i),{passive:!1}),e.addEventListener("dblclick",()=>this.fit()),new ResizeObserver(()=>this.#B()).observe(this.#s),document.addEventListener("fullscreenchange",()=>this.#K())}connectedCallback(){b.add(this),$(),this.#R(),this.#l||this.#E()}disconnectedCallback(){b.delete(this)}attributeChangedCallback(t,e,i){e!==i&&this.isConnected&&(t==="src"?this.#E():t==="theme"?this.themeChanged():t==="max-height"?this.#R():t==="editor"&&this.#$())}get theme(){return k(this.getAttribute("theme"),w(document.documentElement),!!p?.matches)}themeChanged(){this.#l&&this.theme!==this.#L&&this.#C()}async#E(){let t=this.getAttribute("src"),e=++this.#d;if(t)try{let i=await(await f()).fetchSource(new URL(t,document.baseURI).href);if(e!==this.#d)return;this.#l=i,this.#o=!0,await this.#C(),this.#$()}catch(i){e===this.#d&&this.#F(i)}}async#C(){let t=this.#l,e=this.theme,i=++this.#d;try{let s=await(await f()).draw(t,e==="dark",this.getAttribute("fonts")??C);if(i!==this.#d)return;let a=this.#e&&this.#e.w===s.w&&this.#e.h===s.h&&this.#e.x===s.x&&this.#e.y===s.y;this.#e=s,this.#L=e,this.#i.innerHTML=s.svg;let n=this.#i.querySelector("svg");n.removeAttribute("width"),n.removeAttribute("height"),n.setAttribute("preserveAspectRatio","xMidYMid meet"),this.#i.setAttribute("aria-label",this.#I()),this.#s.style.background=s.paper,this.#s.style.setProperty("--fd-ratio",`${s.w} / ${s.h}`),this.#s.classList.toggle("dark",e==="dark"),this.#s.hidden=!1,this.#x.hidden=!0,this.#g(),this.#o||!a?this.#M():this.#h(this.#t),this.dataset.ready="",this.dispatchEvent(new CustomEvent("fastdraw-ready",{detail:{theme:e}}))}catch(s){i===this.#d&&this.#F(s)}}#F(t){console.error(`fastdraw-diagram: could not draw ${this.getAttribute("src")}`,t),this.#e||(this.#s.hidden=!0,this.#x.hidden=!1,this.dispatchEvent(new CustomEvent("fastdraw-error",{detail:{error:t}})))}#I(){return(this.getAttribute("alt")??this.querySelector("img")?.getAttribute("alt"))||`Diagram ${this.#S()}`}#S(){let t=new URL(this.#l?.url??this.getAttribute("src")??"diagram.fdraw",document.baseURI).pathname,e=t.slice(t.lastIndexOf("/")+1)||"diagram.fdraw";try{e=decodeURIComponent(e)}catch{}return e}async#$(){let t=this.#l;if(t)try{this.#m.href=await E(this.getAttribute("editor")||"https://fastdraw.dev/edit/",{name:this.#S(),text:t.text,...t.look?{look:{path:t.look.path,text:t.look.text}}:{}}),this.#m.hidden=!1}catch(e){console.warn("fastdraw-diagram: no link to the editor",e),this.#m.hidden=!0}}#R(){let t=this.getAttribute("max-height");this.#s.style.maxHeight=t?/^\d+(\.\d+)?$/.test(t)?`${t}px`:t:"inherit"}#g(){let t=this.#i.getBoundingClientRect();this.#a=t.width,this.#r=t.height}#f(){return this.#a/this.#e.w}#p(){let t=this.#e;return Math.min(this.#a/t.w,this.#r/t.h)}#k(){let t=this.#p();return{min:Math.min(t,this.#f())*.75,max:Math.max(this.#f()*8,4)}}#q(t){let e=this.#e,{min:i,max:s}=this.#k(),a=Math.min(s,Math.max(i,t.k)),n=this.#a/a,h=this.#r/a,r=(o,l,d,c)=>d<=c?l+d/2-c/2:Math.min(l+d-c,Math.max(l,o));return{k:a,x:r(t.x,e.x,e.w,n),y:r(t.y,e.y,e.h,h)}}#h(t){if(!this.#e||!this.#a||!this.#r)return;this.#t=this.#q(t);let{x:e,y:i,k:s}=this.#t,a=this.#e;this.#i.querySelector("svg")?.setAttribute("viewBox",`${e} ${i} ${this.#a/s} ${this.#r/s}`);let n=a.w*s>this.#a+.5||a.h*s>this.#r+.5;this.#i.classList.toggle("pannable",n);let{min:h,max:r}=this.#k();this.shadowRoot.querySelector("[data-act=in]").disabled=s>=r-1e-6,this.shadowRoot.querySelector("[data-act=out]").disabled=s<=h+1e-6}#w(t){cancelAnimationFrame(this.#u);let e=this.#q(t);if(S?.matches){this.#h(e);return}let i={...this.#t},s=performance.now(),a=n=>{let h=Math.min(1,(n-s)/180),r=1-(1-h)**3,o=i.k*(e.k/i.k)**r,l=(e.x-i.x)/(1/e.k-1/i.k||1),d=(e.y-i.y)/(1/e.k-1/i.k||1),c=Math.abs(e.k-i.k)>1e-9;this.#h(c?{k:o,x:i.x+l*(1/o-1/i.k),y:i.y+d*(1/o-1/i.k)}:{k:o,x:i.x+(e.x-i.x)*r,y:i.y+(e.y-i.y)*r}),h<1&&(this.#u=requestAnimationFrame(a))};this.#u=requestAnimationFrame(a)}#v(t,e,i,s=!1){let a=this.#t,{min:n,max:h}=this.#k(),r=Math.min(h,Math.max(n,t)),o={k:r,x:a.x+e/a.k-e/r,y:a.y+i/a.k-i/r};this.#o=!1,s?this.#w(o):this.#h(o)}#M(){this.#e&&(this.#o=!0,cancelAnimationFrame(this.#u),this.#y()?this.#h({k:this.#p(),x:0,y:0}):this.#h({k:this.#f(),x:this.#e.x,y:this.#e.y}))}zoomBy(t){this.#e&&this.#v(this.#t.k*t,this.#a/2,this.#r/2,!0)}fit(){this.#e&&(this.#o=!this.#y()&&this.#p()>=this.#f()-1e-6,this.#w({k:this.#p(),x:0,y:0}))}get zoom(){return this.#t.k}#B(){if(!this.#e)return;let t=this.#t.x+this.#a/2/this.#t.k,e=this.#t.y+this.#r/2/this.#t.k;this.#g(),this.#o?this.#M():this.#h({k:this.#t.k,x:t-this.#a/2/this.#t.k,y:e-this.#r/2/this.#t.k})}#A(t){let e=this.#i.getBoundingClientRect();return{x:t.clientX-e.left,y:t.clientY-e.top}}#D(t){!this.#e||t.pointerType==="mouse"&&t.button!==0||(this.#i.setPointerCapture(t.pointerId),this.#n.set(t.pointerId,this.#A(t)),this.#b=!1,cancelAnimationFrame(this.#u))}#H(t){let e=this.#n.get(t.pointerId);if(!e)return;let i=this.#A(t);if(this.#n.size===1){if(!this.#b&&Math.hypot(i.x-e.x,i.y-e.y)<3)return;this.#b=!0,this.#i.classList.add("dragging"),this.#o=!1,this.#h({k:this.#t.k,x:this.#t.x-(i.x-e.x)/this.#t.k,y:this.#t.y-(i.y-e.y)/this.#t.k}),this.#n.set(t.pointerId,i);return}let[s,a]=[...this.#n.entries()].slice(0,2).map(([c,g])=>c===t.pointerId?i:g),[n,h]=[...this.#n.values()].slice(0,2),r=Math.hypot(h.x-n.x,h.y-n.y),o=Math.hypot(a.x-s.x,a.y-s.y),l={x:(n.x+h.x)/2,y:(n.y+h.y)/2},d={x:(s.x+a.x)/2,y:(s.y+a.y)/2};this.#n.set(t.pointerId,i),r&&(this.#b=!0,this.#v(this.#t.k*(o/r),l.x,l.y),this.#h({k:this.#t.k,x:this.#t.x-(d.x-l.x)/this.#t.k,y:this.#t.y-(d.y-l.y)/this.#t.k}))}#z(t){this.#n.delete(t.pointerId),this.#n.size||this.#i.classList.remove("dragging")}#U(t){if(!this.#e||!(t.ctrlKey||t.metaKey))return;t.preventDefault();let e=t.deltaY*(t.deltaMode===1?16:t.deltaMode===2?this.#r:1),i=this.#A(t);this.#v(this.#t.k*Math.exp(-Math.max(-60,Math.min(60,e))*.006),i.x,i.y)}#T(t){if(!this.#e||t.ctrlKey||t.metaKey||t.altKey)return;let e={ArrowLeft:[-1,0],ArrowRight:[1,0],ArrowUp:[0,-1],ArrowDown:[0,1]};if(t.key==="+"||t.key==="=")this.zoomBy(1.4);else if(t.key==="-"||t.key==="_")this.zoomBy(1/1.4);else if(t.key==="0")this.fit();else if(e[t.key]&&t.composedPath()[0]===this.#i&&this.#i.classList.contains("pannable"))this.#o=!1,this.#w({k:this.#t.k,x:this.#t.x+e[t.key][0]*60/this.#t.k,y:this.#t.y+e[t.key][1]*60/this.#t.k});else return;t.preventDefault()}#y(){return this.shadowRoot.fullscreenElement===this.#s}#O(){this.#y()?document.exitFullscreen().catch(()=>{}):this.#s.requestFullscreen().catch(t=>console.warn("fastdraw-diagram: full screen was refused",t))}#K(){let t=this.#y();this.#c.innerHTML=t?u.exit:u.full,this.#c.setAttribute("aria-label",t?"Leave full screen":"Full screen"),this.#c.title=t?"Leave full screen (Esc)":"Full screen",this.#e&&requestAnimationFrame(()=>{this.#g(),this.#M()})}};typeof customElements<"u"&&!customElements.get("fastdraw-diagram")&&customElements.define("fastdraw-diagram",x);export{x as FastDrawDiagram,v as t};
Binary file
Binary file
Binary file
package/guide/guide.md CHANGED
@@ -4,24 +4,54 @@ FastDraw draws diagrams from a small text file (`.fdraw`). You place every eleme
4
4
 
5
5
  ## How to work
6
6
 
7
- 1. Run `fastdraw sizes <look file>` to see the styles you can use, their default sizes, and the look's own guidance. Follow that guidance. A diagram with no `look` line uses the built-in look: run `fastdraw sizes` with no file to see it.
8
- 2. To create or change a look (how styles are drawn), run `fastdraw guide look` instead of the steps below.
9
- 3. Run `fastdraw guide list` to see which kinds of diagram have their own guide. If yours is there, run `fastdraw guide <kind>` and follow it.
7
+ 1. To create or change a look (how styles are drawn), run `fastdraw guide look` instead of the steps below.
8
+ 2. Choose the kind of diagram as described in "Choosing the kind" below (`fastdraw guide list` says what each kind shows), and agree it with the person before drawing. If the kind has its own guide, run `fastdraw guide <kind>` and follow it; where it differs from the general rules in this guide, the kind's guide wins.
9
+ 3. Run `fastdraw sizes <look file>` to see the styles you can use, their default sizes, and the look's own guidance. Follow that guidance. A diagram with no `look` line uses the built-in look: run `fastdraw sizes` with no file to see it.
10
10
  4. Plan the composition on paper first: rows and columns, where the main thing sits.
11
- 5. Write the file.
11
+ 5. Write the file. A new diagram goes in `docs/diagrams/` (create the folder) unless the person names another place or the repo already keeps its `.fdraw` files somewhere. Never put it at the top of the repo: `fastdraw open` lends the diagram's whole folder to the editor.
12
12
  6. Run `fastdraw check <file>`. Fix every error and warning. Read the hints and fix the ones that are real.
13
13
  7. Run `fastdraw render <file>` and **look at the PNG**. Fix what looks wrong: cramped labels, uneven gaps, lopsided composition, a label sitting on a border. Repeat from 6 until it is clean and looks good.
14
- 8. To hand the diagram to a person for changes, run `fastdraw open <file>` in the background. It opens the web editor at the diagram, with its look, and saves their edits into the same file. Read the file again before you change it after that.
14
+ 8. When the diagram is done, tell the person where the file is and **ask what they want to do next**, with these three choices (use your tool for asking a question if you have one). Always ask; do not stop without it.
15
+ - **Open in fastdraw.dev**: run `fastdraw open <file>` in the background. It opens the web editor at the diagram, with its look, and saves their edits into the same file. Read its output and give the person the link it prints, in case no browser window appeared. Read the file again before you change it after that.
16
+ - **Preview as PNG**: open the PNG from `fastdraw render` in their image viewer (`xdg-open <file.png>` on Linux, `wslview` or `explorer.exe` under WSL, `open` on macOS, `start ""` on Windows).
17
+ - **Nothing**: stop there.
18
+
19
+ Do not open anything before they choose.
15
20
 
16
21
  When you change an existing diagram: do not move, resize or restyle anything that is already there unless asked. Place only what you add, in free space.
17
22
 
23
+ ## Choosing the kind
24
+
25
+ Choose by what the reader has to understand, not by a word in the request: a "request flow" or a "user flow" is not a flowchart. `fastdraw guide list` says what every kind shows. The usual choices:
26
+
27
+ | The reader has to see | Kind |
28
+ |---|---|
29
+ | how a request moves through the parts of a system, step by step | `swimlane` with columns; `sequence` when the exact messages and replies matter; `architecture` when the parts and their connections matter more than the order |
30
+ | decisions: yes/no questions and where each answer leads | `flowchart` |
31
+ | work passing between people or teams | `swimlane` with rows; `process` when inputs, outputs and tools matter |
32
+ | the parts of a system and what talks to what | `architecture`; where it runs: `deployment`; what plugs into a platform: `integration` |
33
+ | a change to a system, before and after | `architecture-delta` |
34
+ | data moving through a pipeline | `data-flow`; storage tiers: `medallion`; a whole data stack: `high-level` |
35
+ | the states one thing goes through | `state` |
36
+ | events in order, or a plan | `timeline`; `gantt` |
37
+ | a hierarchy | `tree`; owners: `org-chart`; containment: `nested`; stacked levels: `layers` |
38
+ | a data model | `er`; real tables: `db-schema`; classes: `uml-class` |
39
+ | numbers | `bar`, `line`, `scatter`, `heatmap`, `sankey`, `treemap`, `waterfall` |
40
+
41
+ - Name at least two kinds that could fit before you pick. When two fit, pick the one whose main axis is what the person asked about: order over time, structure, or decisions.
42
+ - Draw a flowchart only when there are real yes/no questions. Steps in a row with no decision are a swimlane, or a process.
43
+ - If a three-column table would say the same thing, write the table instead.
44
+
45
+ **Agree the kind before drawing.** Unless the request already names it ("a sequence diagram of..."), tell the person in one short message which kind you would draw and the closest other kind, with a line on what each shows, and ask which they want (use your tool for asking a question if you have one, your pick first). If you cannot ask, draw your pick and say which other kind would also have worked.
46
+
18
47
  ## The file
19
48
 
20
49
  One statement per line. An indented line continues the statement above it. `//` starts a comment; so does a line starting with `# `.
21
50
 
22
51
  ```
23
52
  look "./team.look" // path relative to this file; leave the line out to use the built-in look
24
- // or a look that ships with FastDraw: look headline | night | reference | sketch | whiteboard
53
+ // or a look that ships with FastDraw: look headline | night | reference | sketch | whiteboard | shade | engraved | keys | transit | offset | listing
54
+ // for a dark theme, keep the line and run fastdraw render x.fdraw --dark to get x-dark.png too
25
55
  canvas paper=#ffffff dots=none dotgap=24 // optional: changes the look's background for this diagram only
26
56
 
27
57
  // shape: id: style "text" at x,y WxH key=value ...
@@ -162,13 +192,14 @@ An arrow can end on a row: `orders.user_id -- users.id`. It attaches to the left
162
192
 
163
193
  ### Icons
164
194
 
165
- `icon=name` puts a small outline icon in any box: `db: store "Orders DB" icon=database at 440,120`. `fastdraw sizes` lists the icons the look has (server, database, user, cloud, queue, lock, mail, function, ai and about 120 more). `fastdraw icons email` searches them by name or meaning: it finds `mail`, and `k8s` finds `pod`.
195
+ `icon=name` puts a small icon in any box: `db: store "Orders DB" icon=database at 440,120`. `fastdraw sizes` lists the icons the look has (server, database, user, cloud, queue, lock, mail, function, ai and about 120 more with friendly names, plus every other Phosphor icon under its own name, about 1,500 in all). `fastdraw icons email` searches them by name or meaning: it finds `mail`, and `k8s` finds `pod`.
166
196
 
167
197
  - The icon sits just left of the text and the pair is centred. `icon.pos=top` puts it above the text instead; the box then needs about 28px more height.
168
198
  - With no text, the icon fills the box.
169
199
  - An icon on its own, with no box, is the `icon` style: `api: icon "Orders API" at 60,220 40x40 icon=server` (24x24 unless you give `WxH`). The icon is the shape, so `fill=`, `stroke=` and `sw=` style the icon itself (`fill=accent/0.2 stroke=accent sw=2`), and its text is a caption centred underneath. Lines attach to the icon and go around other icons' captions.
170
200
  - `icon.size=20` and `icon.color=link` change it; by default it takes the colour of the box's text.
171
- - `icon.fill=accent/0.2` fills the icon's closed parts for a two-tone look (none by default), and `icon.width=2` sets its stroke width in pixels. Both take look colours, tints or hex (`icon.fill=#ffd400`), and both work in a look's `style` lines so every box of a style gets the same icon treatment. Icons from a look's folder keep their own colours.
201
+ - `icon.fill=accent/0.2` lays a tint under the icon's main part for a two-tone look (none by default), and `icon.width=2` sets its line thickness in pixels; a built-in icon comes in four weights (thin, light, regular, bold), and the nearest is used. Both take look colours, tints or hex (`icon.fill=#ffd400`), and both work in a look's `style` lines so every box of a style gets the same.
202
+ - `icon.style=solid` draws a built-in icon filled in one colour, and `icon.style=duotone` draws its outline over a light tint of the same drawing (`icon=database icon.style=duotone`). They take `icon.color=` (on an `icon` shape, `stroke=`); a duotone's tint is `icon.fill=` when set, else a light shade of the icon's colour. Outline, solid and duotone are the same drawing; every built-in icon has all three, a look's own icons only the outline. Keep one style across a diagram.
172
203
  - A look can bring its own colour icons (a cloud vendor's set, product logos). `fastdraw sizes <look>` lists them first; use them the same way: `icon=virtual-machine`. They keep their own colours. Run `fastdraw icons <look> word` to search a large set.
173
204
  - Use icons where they say something the name does not (what kind of thing a box is), on every box of a row or on none. Two or three kinds of icon in one diagram is plenty.
174
205
 
@@ -232,6 +263,8 @@ Labels are drawn in small caps on a paper-coloured patch, above a horizontal lin
232
263
 
233
264
  `text "words" at x,y style=name` — `at` is the left end of the text baseline. `anchor=middle` or `anchor=end` changes that. `rotate=-90` turns the text to read upwards about its `at` point (`rotate=90`: downwards), for a label along a vertical axis. Overrides: `size=`, `color=`, `weight=`, `font=sans|mono|serif`, `italic=1` (only where the font has an italic face; the bundled sans and mono do not, the serif does).
234
265
 
266
+ Spaces inside the quotes are drawn as written, here and in every other text (labels, `sub=`, table cells): leading spaces indent, and a run of spaces stays a run. So indented code or lined-up columns can be one text per line at the same x, with `font=mono` for the columns to line up: `text " orders:" at 40,58 font=mono`.
267
+
235
268
  ### Legend
236
269
 
237
270
  One statement draws a whole legend: a rule line, a heading, and one entry per style, spaced and wrapped for you.
package/guide/look.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  A look is one text file (`.look`) that decides how every style is drawn: colours, fonts, shapes, lines and text. Diagrams point to it with `look "./team.look"`. Change the look and every diagram that uses it changes.
4
4
 
5
- Five looks ship with FastDraw and need no file: `look headline`, `look night`, `look reference`, `look sketch` and `look whiteboard` (a bare name, no quotes or `.look`). In the editor, the **Look** button shows the diagram in each of them and the built-in look, to try one before keeping it.
5
+ Eleven looks ship with FastDraw and need no file: `look engraved`, `look headline`, `look keys`, `look listing`, `look night`, `look offset`, `look reference`, `look shade`, `look sketch`, `look transit` and `look whiteboard` (a bare name, no quotes or `.look`). Six of them are styles of drawing more than palettes: `shade` (hairline boxes with a hatched shadow), `engraved` (double rules and a black plate, like a printed plate), `keys` (boxes with a side, like keycaps), `transit` (thick route lines with stops, like a network map), `offset` (two inks printed out of register) and `listing` (a printout on striped listing paper). In the editor, the **Look** button shows the diagram in each of them and the built-in look, to try one before keeping it.
6
6
 
7
7
  ## How to work
8
8
 
@@ -13,7 +13,7 @@ Five looks ship with FastDraw and need no file: `look headline`, `look night`, `
13
13
 
14
14
  Keep the style names from the built-in look (`node`, `focal`, `store`, `cloud`, `external`, `optional`, `step`, `terminal`, `terminal-focal`, `decision`, `zone`, `bar`, `arrow`, `primary`, `link`, `return`, `lifeline`, `rule`, `h1`, `eyebrow`, `caption`, `note`, `small`). The diagram guides and existing diagrams use those names. You may add more styles of your own.
15
15
 
16
- The looks that ship with FastDraw all define the same styles (the ones above plus `kicker`, `dek`, `legend`, `table`, `matrix`, `chart`, `relation`, `sticky`, `sticky-orange` and `sticky-violet`), so a diagram can move between them without a style going plain. A test holds them to that: after editing one in `looks/`, run `node tools/bundle-looks.mjs`.
16
+ The looks that ship with FastDraw all define the same styles (the ones above plus `kicker`, `dek`, `legend`, `table`, `matrix`, `chart`, `relation`, `sticky`, `sticky-orange` and `sticky-violet`), so a diagram can move between them without a style going plain. A test holds them to that: after editing one in `looks/`, run `node tools/bundle-looks.mjs`. The six style looks are written by `tools/gen-style-looks.py`; change them there.
17
17
 
18
18
  ## The file
19
19
 
@@ -22,6 +22,9 @@ One statement per line; an indented line continues the one above; `//` starts a
22
22
  ```
23
23
  canvas paper=paper dots=ink/0.06 dotgap=22 // paper= background colour; dots= dot colour and dotgap= spacing are optional; a diagram's own canvas line can override any of the three
24
24
  // sketch=1 draws every outline and line by hand (2 is rougher); see looks/sketch.look
25
+ // bars=colour stripes the page like listing paper (bargap= is the stripe height), feed=colour adds
26
+ // sprocket holes down both edges, grain=0.5 lays paper grain over everything (0 to 1)
27
+ // tint=hue or tint=alpha: how colour/opacity tints mix (see Colours)
25
28
 
26
29
  color paper #ffffff // a named colour
27
30
  color ink #1c1f2a
@@ -45,6 +48,8 @@ guidance "Use focal on at most two things in one diagram."
45
48
 
46
49
  A colour value is `#hex`, a name defined with `color`, or either followed by `/opacity`: `ink/0.3`, `#ffffff/0.85`. `none` means no fill or no stroke. Define `paper`, `ink` and `muted` at least; built-in parts fall back to those names. `card` is the fill of a plain box (white unless a look sets it; a dark look sets it to its box colour), so a diagram that writes `fill=card` stays right in every look.
47
50
 
51
+ On a light page a tint such as `amber/0.1` is the colour at that opacity over what is underneath. On a dark page that blend loses the hue: 10% of amber over navy is grey. So when `paper` is dark, a tint of a coloured colour is mixed so it keeps its hue: it gets lighter and takes on the tint's colour as if the page were neutral grey, and stays see-through. `amber/0.1` on Night is a dark amber, the counterpart of the pale amber on the built-in look, so one diagram reads in both. Tints of greys (`ink/0.06`) are blended as before. `canvas tint=alpha` turns this off for a dark look; `canvas tint=hue` turns it on for a light one.
52
+
48
53
  ### Fonts
49
54
 
50
55
  `font sans|mono|serif "Family"` sets the family for each role; styles then say `font=sans`.
@@ -59,6 +64,7 @@ font sans "Fira Sans"
59
64
  - Files must be **TTF or OTF**, one file per weight and style you use (for example Regular and SemiBold; add Italic if a style sets `italic=1`). Box titles use weight 600 by default. Use static files, not a single variable font.
60
65
  - The family name is read from inside the files, so `font sans "..."` must match it exactly. `fastdraw sizes team.look` lists the fonts and flags any family it found no file for; `fastdraw check` warns about it too.
61
66
  - Commit the font folder with the look, and keep the font's licence file beside it. Use fonts whose licence allows redistribution (for example the SIL Open Font License).
67
+ - Ligatures are turned off in every font, in the editor, the SVG and the PNG: `--`, `->`, `>=`, `!=` and `...` are drawn as the characters written, never as one joined glyph, so code, command-line flags and SQL read as typed.
62
68
  - In the browser editor the look's fonts load when a folder is open. A diagram opened as a single file, pasted, or restored from an exported image is drawn with fallback fonts until its folder is opened.
63
69
 
64
70
  ### Styles
@@ -79,16 +85,25 @@ font sans "Fira Sans"
79
85
  | `size=WxH` | default size when a diagram gives none |
80
86
  | `fill=`, `stroke=`, `sw=`, `dash=5,4` | fill colour, stroke colour, stroke width, dash pattern |
81
87
  | `hatch=colour` | fill with diagonal pencil lines on top of `fill=`; `hatch.gap=` spaces them, `hatch.sw=` weighs them |
88
+ | `halftone=colour` | fill with a field of printed dots; `halftone.gap=` spaces them, `halftone.r=` sizes them |
89
+ | `shade=colour` | a shadow of fine diagonal lines down the right and bottom of the shape; `shade.size=` is how far it reaches (default 5), `shade.gap=` and `shade.sw=` space and weigh its lines |
90
+ | `depth=N` | a slab N pixels below the shape, so it reads as a solid with a side; `depth.fill=` and `depth.stroke=` colour it. A line that ends on the bottom edge ends on the slab |
91
+ | `inner=colour` | a second, finer rule just inside the outline; `inner.gap=` (default 3.5) and `inner.sw=` |
92
+ | `corners=plus` | a mark on each corner of a box: `plus` or `square`; `corners.color=`, `corners.size=` |
93
+ | `offset=dx,dy` | print the fill that far out of register with the outline |
94
+ | `blend=multiply` | let this style's ink darken what it overlaps, like overprinting (also on line and text styles) |
82
95
  | `sketch=0` | with `canvas sketch=` on: draw this style with clean lines (works on line styles too) |
83
96
  | `layer=back` | draw behind everything (for regions like `zone`) |
84
- | `title.*` | the main text: `title.font`, `title.size`, `title.weight`, `title.color`, `title.italic=1`, `title.spacing` (in em), `title.caps=1`; `title.pos=top` puts it as a small caption at the top edge |
97
+ | `title.*` | the main text: `title.font`, `title.size`, `title.weight`, `title.color`, `title.italic=1`, `title.spacing` (in em), `title.caps=1`; `title.pos=top` puts it as a small caption at the top edge, `title.dy=` moves that caption up or down and `title.fill=` colours the patch behind it (`none` for no patch) |
85
98
  | `sub.*` | the second line (`sub=` on an element): `sub.font`, `sub.size`, `sub.color` |
86
99
  | `tag.*` | the corner marker (`tag=`): `tag.color`, `tag.border`, `tag.font`, `tag.size` |
87
100
  | `ghost.*` | the big faint number (`ghost=`): `ghost.color`, `ghost.size` |
88
101
 
89
- On a dark or saturated fill, set `title.color`, `sub.color`, `tag.color` and `tag.border` to something that contrasts, or the text disappears. Set these explicitly on every style; do not rely on defaults.
102
+ On a dark or saturated fill, set `title.color`, `sub.color`, `tag.color` and `tag.border` to something that contrasts, or the text disappears. Set these explicitly on every style; do not rely on defaults. Diagrams also lay their own text over boxes (a caption drawn on the subject): where a style's fill would swallow that text, it is drawn in the style's `title.color` instead, so a dark `focal` needs a light `title.color`.
103
+
104
+ Keep type close to the built-in look's sizes (12px titles, 9px second lines, 10px line labels). Diagrams are laid out for those, so larger type overflows boxes that fit before.
90
105
 
91
- The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's details (a cylinder rim) out of the top 20px or flatten them. A `title.pos=top` caption is centred on the top edge with a paper-coloured patch behind it.
106
+ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's details (a cylinder rim) out of the top 20px or flatten them. A `title.pos=top` caption is centred on the top edge with a patch behind it, 6px wider than the words on each side. A patch that crosses the outline is paper-coloured, so the edge stops at the words; one that sits inside the shape takes the shape's own fill, so it hides the page dots behind the words and is otherwise invisible.
92
107
 
93
108
  **Table styles** (`shape=table`) use `fill`, `stroke`, `sw`, `radius`, `dash` and `title.*` like any box, plus:
94
109
 
@@ -121,10 +136,14 @@ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's
121
136
  | `route=` | `ortho` (right-angle turns), `straight`, or `curve` (a smooth line) |
122
137
  | `radius=` | corner radius of the turns |
123
138
  | `head=` | the marker `->` draws: `arrow` (default), `open`, `triangle`, `diamond`, `diamond-solid`, `dot`, `circle`, or one of the relationship ends (`one`, `only-one`, `many`, `one-many`, `zero-one`, `zero-many`). `head=none` marks a style meant for plain lines, never arrows |
124
- | `tail=` | a marker for the start of the line, if the style always has one |
125
- | `label.*` | the text on the line: `label.font`, `label.size`, `label.color`, `label.spacing`, `label.caps=0` to keep the label's own case (default is capitals) |
139
+ | `tail=` | a marker for the start of the line, if the style always has one. `stop` is a ring, like a station on a route map (`stop.color=`) |
140
+ | `head.size=` | scale the arrowhead, for a wide line (1 is the default; 0.5 to 4) |
141
+ | `cap=round` | round the ends and corners of the line |
142
+ | `casing=colour` | a wider line of that colour underneath, so lines that cross stay apart; `casing.width=` is how far it shows on each side |
143
+ | `double=colour` | a finer line of that colour on top, which turns a wide line into two rails; `double.sw=` |
144
+ | `label.*` | the text on the line: `label.font`, `label.size`, `label.color`, `label.spacing`, `label.caps=0` to keep the label's own case (default is capitals), `label.weight`, `label.italic=1`. `label.fill=` and `label.border=` make the label a plate instead of a patch of paper (`label.radius=`, `label.pad=`, `label.sw=`) |
126
145
 
127
- **Text styles** (`style name text ...`): `font=`, `size=`, `weight=`, `color=`, `italic=1`, `spacing=`, `caps=1`.
146
+ **Text styles** (`style name text ...`): `font=`, `size=`, `weight=`, `color=`, `italic=1`, `spacing=`, `caps=1`. `echo=colour` prints the text a second time underneath, a little off (`echo.dx=`, `echo.dy=`, default 3).
128
147
 
129
148
  ### Built-in styles you can restyle
130
149
 
@@ -132,13 +151,13 @@ The tag sits 8px in from the top-left corner and is 12px tall, so keep a path's
132
151
 
133
152
  ### Icons
134
153
 
135
- Every look starts with a set of outline icons (see `fastdraw sizes`). Add your own, or replace one, with
154
+ Every look starts with a set of built-in icons (see `fastdraw sizes`), each as an outline, solid or duotone: about 130 with friendly names, and every other Phosphor icon under Phosphor's own name (`anchor`, `acorn`; `fastdraw icons <word>` finds them; a Phosphor name that a friendly name already uses, such as `book`, is `ph-book`). Add your own, or replace one, with
136
155
 
137
156
  ```
138
157
  icon queue "M4 6h16" "M4 12h16" "M4 18h16"
139
158
  ```
140
159
 
141
- The quoted parts are SVG path data drawn in a 24x24 box; they are stroked, not filled, in the colour of the box's text. Keep to simple outlines with a 1.5 stroke in mind, so they match the bundled ones. A style can carry an icon (`style store extends node icon=database`), and `icon.size=`, `icon.color=`, `icon.pos=top` work in a style too.
160
+ The quoted parts are SVG path data drawn in a 24x24 box; they are stroked, not filled, in the colour of the box's text. Keep to simple outlines with a 1.5 stroke in mind, so they sit with the built-in ones. An icon of your own (or one you replace) is an outline only: it has no solid or duotone style. A style can carry an icon (`style store extends node icon=database`), and `icon.size=`, `icon.color=`, `icon.pos=top` work in a style too.
142
161
 
143
162
  **Colour icons and vendor sets** go in a folder of SVG files next to the look:
144
163
 
@@ -152,13 +171,24 @@ Every `.svg` file directly in that folder becomes an icon, drawn exactly as the
152
171
  - Files over 300 KB are skipped. Only the icons a diagram uses are carried inside its exported image.
153
172
  - A file with the same name as a built-in icon replaces it.
154
173
 
174
+ ### Dark version
175
+
176
+ `dark` names the look that draws the same diagrams on a dark page. `fastdraw render x.fdraw --dark` writes `x.png` with the diagram's look and `x-dark.png` with the look its `dark` line names, for a site that shows one or the other with the reader's theme.
177
+
178
+ ```
179
+ dark night // a look that ships with FastDraw
180
+ dark "./team-night.look" // a look file, relative to this look file
181
+ ```
182
+
183
+ The built-in look's dark version is `night`, and Night names itself, since it is already dark. A dark look should keep the same style names, so the diagram draws the same way in both. Without a `dark` line, `--dark` stops with an error that names the look. To draw one diagram with another look without changing the file, use `fastdraw render x.fdraw --look night` (or `--look ./other.look`).
184
+
155
185
  ### Guidance
156
186
 
157
187
  `guidance "..."` lines are shown to agents by `fastdraw sizes`. Use them for rules a drawing tool cannot enforce: how many accent elements are allowed, when to use `tag=`, what `sub=` is for.
158
188
 
159
189
  ## What makes a look good
160
190
 
161
- - **On dark paper, use solid fills for the accent.** A translucent tint (`accent/0.15`) over a dark background turns muddy; a solid accent with dark text on it stays clean.
191
+ - **On dark paper, tints are quiet.** A tint (`accent/0.15`) keeps its hue but stays dark; for the one thing that must stand out, a solid accent with dark text on it is clearer.
162
192
  - **Decide the accent first.** One colour carries the focus (`focal`, `terminal-focal`, `primary`). Everything else is ink, greys and paper. A look with three bright colours has no focus.
163
193
  - **Separate by more than colour.** `external`, `optional`, `cloud` and `store` should differ in shape, fill or dash, so they read in greyscale and for colour-blind readers.
164
194
  - **Two or three stroke weights at most**, and the accent arrow slightly heavier than the default arrow.
package/guide/swimlane.md CHANGED
@@ -1,8 +1,17 @@
1
1
  # Swimlane diagrams
2
2
 
3
- Shows a process that passes between people or teams: who does each step, and where the work changes hands.
3
+ Shows a process that passes between people, teams or parts of a system: who does each step, and where the work changes hands.
4
4
 
5
- ## Lanes
5
+ ## Rows or columns
6
+
7
+ Pick one before you start:
8
+
9
+ - **Columns** (one vertical lane per actor, time running down): for a request or call path through a system, such as browser, gateway, services and stores, or for any flow where each step hands over to the next. It reads top to bottom like a sequence diagram but keeps a box for each step. See "Columns" at the end.
10
+ - **Rows** (one horizontal lane per actor, time running right): for a business process between people or teams, where an actor often does several steps in a row.
11
+
12
+ ## Rows
13
+
14
+ ### Lanes
6
15
 
7
16
  One horizontal lane per actor, in the order they first act. The look has no lane style; draw lanes with plain lines (`--`) and text. Title at `40,52` (`style=h1`); the first lane line is y=96. Lanes are 112px tall: lane k (from 0) has its top line at `y = 96 + 112k`. (Tall lanes leave a 64px vertical handoff, long enough for a head and a label.)
8
17
 
@@ -17,7 +26,7 @@ text "Reviewer" at 60,268 style=eyebrow // baseline 60px under the lane's top l
17
26
  - All lanes have the same height. The name column is 120px wide (x 40 to 160). Every lane has a name; keep it to about 14 characters.
18
27
  - Three to five lanes. With more, merge actors that never act separately. The lines run as far right as the steps need (x=960 above), all to the same x.
19
28
 
20
- ## Steps
29
+ ### Steps
21
30
 
22
31
  - A step is a `node` written `120x48` (the default 144x64 does not fit the lane), placed 32px under its lane's top line, so it is centred in the lane. Widths 120 to 136; 80 for a one-word step. Main text is the action; `sub=` (small sans) is the tool or detail.
23
32
  - A step belongs to one lane. Never stretch a step across two.
@@ -27,7 +36,7 @@ text "Reviewer" at 60,268 style=eyebrow // baseline 60px under the lane's top l
27
36
  - Lanes need not have the same number of steps. A lane with one step is fine.
28
37
  - The step the process exists to reach gets `focal`.
29
38
 
30
- ## Arrows
39
+ ### Arrows
31
40
 
32
41
  - Arrows inside a lane are plain, straight and unlabelled.
33
42
  - Arrows that cross a lane line are the handoffs, the point of the diagram. Label them. The handoff that costs most (waiting, coupling, an approval) uses `style=primary`.
@@ -35,6 +44,53 @@ text "Reviewer" at 60,268 style=eyebrow // baseline 60px under the lane's top l
35
44
  - A label on a segment that crosses a lane line lands on that line, and `check` reports it. Move it into the gap above the line with `lpos=x,y`: x is the segment's x plus 12 plus half the label's width (a label is about 5px wide per character), y is the lane line minus 6. This holds for a vertical handoff and for the vertical leg of an elbow alike. A label on a horizontal leg sits 10px above that leg and needs no `lpos`.
36
45
  - If the flow snakes back to the left, reorder the steps or the lanes until it runs mostly left to right and downward.
37
46
 
38
- ## Legend
47
+ ### Legend
39
48
 
40
49
  One `legend at 40,Y` statement, 32px under the last lane line, with entries for the step, the focal step and each arrow style used.
50
+
51
+ ## Columns
52
+
53
+ ### Lanes
54
+
55
+ One vertical lane per actor, left to right in the order they first act; the one that starts the flow (the browser, the user) is on the left. Title at `40,52` (`style=h1`). Columns are 208px wide: column k (from 0) starts at `x = 40 + 208k`. The names sit in a header row at the top.
56
+
57
+ ```
58
+ 40,96 -- 872,96 stroke=ink/0.22 // top of the header (872 = 40 + 208 * columns)
59
+ 40,140 -- 872,140 stroke=ink/0.22 // under the names
60
+ 248,96 -- 248,676 style=rule // between columns: one every 208px
61
+ 40,96 -- 40,676 stroke=ink/0.22 // left edge; the right edge is the same at x=872
62
+ 40,676 -- 872,676 stroke=ink/0.22 // bottom line: 24px under the last step
63
+ text "API gateway" at 268,124 style=eyebrow // 20px inside the column, baseline y=124
64
+ ```
65
+
66
+ - Three to five columns. Every column has a name; keep it to about 16 characters.
67
+
68
+ ### Steps
69
+
70
+ - A step is a `node` written `136x48`, 36px inside its column (`x = 40 + 208k + 36`), so it is centred in it. Main text is the action; `sub=` is the detail (an endpoint, a table, a tool).
71
+ - One step per row: row r has its top at `y = 164 + 88r`. Each step happens after the one above it, even in another column. This is what makes the order readable without numbers.
72
+ - The step the request exists for gets `focal`.
73
+
74
+ ### Arrows
75
+
76
+ - To the next step in the same column: `a -> b`, straight down, unlabelled.
77
+ - To a step in another column, always on the next row: `a.right -> b.top` when it is to the right, `a.left -> b.top` when it is to the left. The arrow leaves the side, runs across and turns down onto the step.
78
+ - These handoffs are the point of the diagram. Label each with what is sent: the call (`"POST /orders"`) or the answer (`"201 Created"`). A label would sit across a column line, so place it inside the receiving column with `lpos=x,y`: y is the sending step's top plus 14. Going right, x is the last column line the arrow crosses plus 12 plus half the label's width (about 5px per character); going left, x is the receiving column's right line (`40 + 208(k + 1)` for column k) minus 12 minus half the label's width.
79
+ - A response or callback uses `style=return`. The call that costs most (the slowest, or the one that can fail the request) uses `style=primary`.
80
+ - A flow with more than about eight steps is two diagrams, or a sequence diagram.
81
+
82
+ ### Legend
83
+
84
+ One `legend at 40,Y` statement, 32px under the bottom line, with entries for the step, the focal step and each arrow style used.
85
+
86
+ For example:
87
+
88
+ ```
89
+ place: node "Place order" sub="checkout page" at 76,164 136x48
90
+ token: node "Check token" sub="JWT · rate limit" at 284,252 136x48
91
+ charge: focal "Charge card" sub="Stripe" at 700,428 136x48
92
+ confirm: node "Confirm order" sub="status=paid" at 492,516 136x48
93
+
94
+ place.right -> token.top "POST /orders" lpos=290,178
95
+ charge.left -> confirm.top "paid" style=return lpos=642,442
96
+ ```
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Phosphor Icons
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fastdraw",
3
- "version": "0.1.1",
3
+ "version": "0.2.1",
4
4
  "description": "Diagrams that an AI agent writes as text and a person edits on a canvas",
5
5
  "keywords": [
6
6
  "diagram",
@@ -22,13 +22,19 @@
22
22
  "bin": {
23
23
  "fastdraw": "dist/cli.js"
24
24
  },
25
+ "exports": {
26
+ "./embed": "./dist-embed/embed.js",
27
+ "./package.json": "./package.json"
28
+ },
25
29
  "files": [
26
30
  "dist/cli.js",
31
+ "dist-embed",
27
32
  "guide",
28
33
  "fonts",
29
34
  "agents",
30
35
  "README.md",
31
- "LICENSE"
36
+ "LICENSE",
37
+ "licenses"
32
38
  ],
33
39
  "engines": {
34
40
  "node": ">=20"
@@ -36,26 +42,27 @@
36
42
  "scripts": {
37
43
  "test": "node --disable-warning=ExperimentalWarning --test test/*.test.ts",
38
44
  "dev": "vite",
39
- "build:editor": "vite build",
45
+ "build:editor": "vite build && vite build -c vite.embed.config.ts --outDir dist-editor --emptyOutDir false",
40
46
  "typecheck": "tsc -p .",
41
47
  "test:e2e": "playwright test",
42
48
  "build:cli": "esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --external:@resvg/resvg-js --banner:js=\"#!/usr/bin/env node\" --outfile=dist/cli.js",
43
- "prepack": "npm run build:cli"
49
+ "prepack": "npm run build:cli && npm run build:embed",
50
+ "build:embed": "vite build -c vite.embed.config.ts"
44
51
  },
45
52
  "dependencies": {
46
53
  "@resvg/resvg-js": "^2.6.2"
47
54
  },
48
55
  "devDependencies": {
49
56
  "@playwright/test": "^1.65.0",
50
- "@types/node": "^22.20.5",
51
- "@types/react": "^18.3.31",
52
- "@types/react-dom": "^18.3.7",
53
- "@vitejs/plugin-react": "^4.7.0",
54
- "esbuild": "^0.25.12",
57
+ "@types/node": "^26.6.6",
58
+ "@types/react": "^19.3.0",
59
+ "@types/react-dom": "^19.3.0",
60
+ "@vitejs/plugin-react": "^6.3.0",
61
+ "esbuild": "^0.28.2",
55
62
  "lucide-react": "^1.72.0",
56
- "react": "^18.3.1",
57
- "react-dom": "^18.3.1",
58
- "typescript": "^5.9.3",
59
- "vite": "^6.4.6"
63
+ "react": "^19.3.1",
64
+ "react-dom": "^19.3.1",
65
+ "typescript": "^7.0.2",
66
+ "vite": "^8.3.8"
60
67
  }
61
68
  }