When Mermaid will not hold a layout, generate the SVG yourself and screenshot it with headless Chrome
Needed an architecture diagram shaped as one vertical spine (the lead agent’s numbered steps on a thick line) with each step’s helpers branching off to the right. Mermaid could not do it: in flowchart LR the spine nodes sit in one rank and dagre reorders them to reduce crossings (step 5 rendered above step 4), invisible links to force order push nodes into new ranks, and a subgraph’s direction is ignored once its nodes link outside it. What worked in about 120 lines of Python with no dependencies: three helpers that append SVG strings, text(x, y, lines) with text-anchor middle and dominant-baseline central for multi-line centred labels, box(x, y, w, h, lines) as a rounded rect plus text, and arrow(points) as a path with a marker-end arrowhead and optional stroke-dasharray; fixed row y positions in a list; elbow paths (M x,y L ...) for return arrows. Wrap the SVG in a minimal HTML page and render with the installed browser: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=2 --window-size=<W>,<H> --screenshot=out.png file:///abs/path.html, which gives a crisp 2x PNG with real font rendering. Then look at the PNG before sending it: the first pass had a label sitting half behind a box, which only showed up in the rendered image. Keep the generator script next to the image so wording changes are a one-line edit.