DSL Reference

Trazo turns a few lines of line-based pseudo-code into a deterministic SVG diagram. There are four languages: a flow DSL (flowcharts), a git DSL (commit-history graphs), a sequence DSL (sequence diagrams), and a block DSL (block-grid wireframes).

Universal rules

• One statement per line. Order matters — it drives deterministic layout.
• # starts a comment — everything after it on the line is ignored.
• Blank lines are ignored.
• The first non-comment line chooses the language:
  • starts with flow / flowchart → flow DSL
  • starts with commit / branch / checkout / merge → git DSL
  • starts with sequence / participant / a A ->> B message → sequence DSL
  • starts with block / columns → block DSL
• Deterministic: the same source always produces the same diagram.

Flow DSL

A forgiving subset of Mermaid's flowchart syntax.

Direction line

flow TD    # top-down (default)
flow LR    # left-right

Nodes

Append :role to color the node:

A["Request"]:primary
B["Cache hit"]:success
C["Error"]:error
D["Queued"]:warning
E["Streamed"]:streamed

Multi-line labels. A literal \n or a <br> inside a label becomes a line break. The box grows taller to fit the lines and sizes to its widest line:

A["Build step\nruns at deploy"]
B["one<br>two<br>three"]

Edges

Every flow edge is directed by default (-->/==> draw an arrowhead at the target). Use --- when you want a plain connector with no head, and <--> for a two-way relation.

flow LR
A["Request"]  --> B["Handler"]    # arrow:  A ▸ B
C["Cache"]    --- D["Store"]      # no arrow: plain association
E["Client"]  <--> F["Server"]     # arrows both ends: two-way sync

The same three forms with a label:

flow LR
A -->|"calls"| B       # labeled directed
C ---|"relates to"| D  # labeled, no arrow
E <-->|"syncs"| F      # labeled bidirectional

Subgraphs

Wrap a set of nodes in a labeled container box. Nodes declared between subgraph and end join the group and are kept spatially together:

flow TD
subgraph Build ["Build time"]
  A["Compile"] --> B["Bundle"]
end
subgraph Request ["Request time"]
  C["Render"] --> D["Stream"]
end
B --> C

Subgraphs are single-level (no nesting). A node belongs to at most one group — the first subgraph that declares it wins.

Example

flow TD
A(["Request arrives"]):primary ==> B["getCart()"]
B --> C{Cache?}
C -->|hit| D["Cache hit"]:success
C -->|miss| E["DB query"]:warning
D ==> F(["Response"]):success
E ==> F

Git DSL

Describes a commit DAG using four statements.

Statements

• If id looks like 6+ hex digits, it also doubles as the commit hash shown in the label.
• Author is optional, in parentheses: commit (Alice) : Fix bug.
• Message is optional, after :.
• Commits without a message render as bare markers (no label badge).

Example

commit a1b2c3 (JOYCO) : Initial commit
branch feat/checkout
commit (Elvira) : checkout: scaffold
commit (Elvira) : checkout: wire payment
checkout main
commit (JOYCO) : hotfix
merge feat/checkout : merge checkout feature

Layout options (playground toggles)

Tip — horizontal mode and label width. In horizontal orientation, each commit's label badge is centered above the commit dot. Long messages push adjacent commits further apart to prevent overlap — the diagram widens automatically but can become very wide with verbose messages. Keep horizontal-mode labels short: a branch name or a 2–3 word subject. Save full messages for vertical orientation where labels sit to the side and don't affect the horizontal spacing.

Sequence DSL

Sequence diagrams: participants with vertical lifelines and ordered messages between them.

Participants

participant C ["Client"]:primary
participant S ["Server"]

participant declares an actor with an optional ["label"] and :role. Participants are also auto-created the first time they appear in a message, in first-seen order (which sets their column order).

Messages

Notes

Note over A,B : both participants are busy

A note draws a box spanning from the first to the last participant it covers. Note text may use \n / <br> for line breaks. Notes fall in their timeline row — interleaved between messages by source order, not stacked in a side column.

Example

sequence
participant C ["Client"]:primary
participant S ["Server"]
C ->> S : GET /cart
Note over S : reads from cache
S -->> C : 200 OK (streamed)
C ->> C : hydrate

Block DSL

A 2-D wireframe grid of boxes (no edges) — Mermaid's block-beta. Cells flow left→right and wrap to the next row; a cell can span multiple columns.

block
columns 2
Nav["Navigation"] :2
Side["Sidebar"]
Main["Content"]

A trailing bare number (:2) is the column span; a known role name (:success) is the color. Both may be combined.