canvas

Canvas

The Canvas plugin gives the user a drawing panel next to the thread. The user draws boxes, arrows, text, and freehand strokes. You see the same drawing as text through kg canvas show <name> or the canvas_read tool. You change it through canvas_edit. Every change shows in the panel at once.

Model

• One canvas has a name. The user picks it in the panel. A message that shares a canvas names it and gives the command to read it: kg canvas show my-project.
• Coordinates range from −1,000,000 to 1,000,000, negative included. y grows down. The user pans and zooms, and Zoom to fit (Shift+1) puts the whole drawing on screen, so nothing gets lost.
• canvas_read starts with a summary line saying how many elements there are and which area they use. Place new work beside that area, not on top of it. On an empty canvas, draw near 0,0.
• Each element has a stable id: b1 box, a2 arrow, t3 text, p4 freehand path. Ids only increase. A deleted id is never reused.
• An arrow with from and to (two box ids) sticks to those boxes. It routes on right angles and follows the boxes. Delete a box and its arrows go too.
• heads says which ends carry an arrowhead: end (the default), start, both, or none. An arrow with heads: "none" is a plain line, and canvas_read prints it as line.
• Colors: ink accent muted working needs failed. The active Workbench theme resolves them; omitted color is ink. Theme roles may share a color, so use labels as well.

Draw a readable diagram

The panel clips a label to the box. A long sentence in a small box is lost. Keep the picture small and sparse.

• A box label is a noun phrase: "web", "coach-tools", "blocked". Not a sentence. Not a paragraph.
• Size the box to the label: w = max(200, chars * 10 + 24), h = 80. A wrapped label can use h = 80 + 20 * extra lines.
• Leave a gap of 80 between boxes. Align a row on one y. Align a column on one x.
• Bind every arrow with from and to, and set x1, y1, x2, and y2 to 0. Do not compute endpoints. The panel also binds an arrow the person draws when the pointer ends on or just beside a box.
• Put a title or a note in text above or beside the row. Never put a title inside a large empty box that other boxes sit in: the title lands in the middle and covers them.
• One color per lane or per row. Skip an arrow label unless it names the relation in a few characters ("GraphQL", "blocks").
• Keep the whole diagram inside about 1600 by 1200 so it fits the panel at one glance.