%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"18px", "darkMode":false}}}%%
flowchart TD
edit(["User edits code"]) --> auto{"Auto-Update on?"}
auto -->|"yes"| commit("<code>committed.set(code)</code>")
auto -->|"no"| wait("Wait")
wait --> btn(["User clicks Render"])
btn --> commit
commit --> out[/"<code>committed</code> changes"/]
style edit fill:#FFFFFF,stroke:#3E2A1E
style btn fill:#FFFFFF,stroke:#3E2A1E
style commit fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style wait fill:#fff
style out fill:#E8A33D,color:#1B2A41
Render Cycle
This page follows one edit from the text area to the drawn diagram. The path crosses from Python to the browser once, and knowing where it crosses explains most of the app’s behavior.
Committing the code
The editor does not pass every keystroke to the viewer. editor_server() keeps a separate value called committed, and only committed code reaches the viewer. The Auto-Update switch decides when an edit is committed:
Turning Auto-Update back on also commits the current code. The _auto effect reads both the code and the switch, so a change to either one runs it again.
Crossing to the browser
viewer_server() has one effect, and it runs when the committed code or any of the three menus changes. It doesn’t return an output. Instead it sends a custom message named shypermaid-render to the browser:
%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'monospace', "fontSize":"18px", "darkMode":false}}}%%
flowchart TD
subgraph Py["<strong>Python</strong>"]
inputs[/"<code>code()</code>, <code>theme</code>,<br><code>look</code>, <code>direction</code>"/]
dir[["<code>set_direction()</code>"]]
cfg[["<code>render_config()</code>"]]
send("<code>send_custom_message()</code>")
end
subgraph JS["<strong>Browser</strong>"]
parse{"<code>mermaid.parse()</code><br>succeeds?"}
draw("<code>mermaid.render()</code><br>replace the SVG")
pz("Attach svg-pan-zoom")
err("Show the error<br>keep the last diagram")
end
inputs -->|"i. rewrite header"| dir
inputs -->|"ii. build options"| cfg
dir & cfg --> send
send -->|"iii. id, code, config"| parse
parse -->|"yes"| draw --> pz
parse -->|"no"| err
style Py fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
style JS fill:#FFFFFF,color:#1B2A41,stroke:#1B2A41,stroke-width:1px,rx:10,ry:10
style send fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style draw fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style pz fill:#2A6F77,color:#FFFFFF,rx:5,ry:5
style err fill:#B83A4B,color:#FFFFFF,rx:5,ry:5
The Python side of this picture is all of viewer_server(). Its call tree from callgrove shows the three helpers it calls in diagram.py. The tree stops at the browser, because callgrove only reads Python files:
from pathlib import Path
import shypermaid
from callgrove import call_tree_dir
call_tree_dir(Path(shypermaid.__file__).parent, root="viewer_server")█─viewer_server
├─code_theme
├─█─set_direction
│ ├─_declaration
│ └─_set_statement
└─render_config
code_theme() reads the theme set in the code’s frontmatter for the note in the toolbar. It does not change what is sent to the browser.
The top box runs in viewer_server() and the bottom box runs in mermaid-binding.js. The message carries three things: the namespaced canvas id, the code after set_direction(), and the options from render_config(). The id lets two viewers on one page draw into their own canvases.
Why errors keep the last diagram
The binding calls mermaid.parse() before mermaid.render(). A parse error jumps to the error handler before the old SVG is removed, so the canvas keeps the last good diagram. The error text is set with textContent, which means a message from Mermaid can’t inject HTML into the page.
render_config() also sets securityLevel to "strict". In strict mode Mermaid disables click handlers in diagrams and cleans the HTML in labels.
What the browser handles alone
Some actions never reach Python. The tool buttons, the Tab key in the editor, and window resizing are all handled in mermaid-binding.js:
- Tool buttons: each button carries
data-sm-actionanddata-sm-targetattributes, and one click listener on the page reads them. - Tab key: inserts four spaces in the editor instead of moving focus. Press Escape, then Tab or Shift+Tab, to leave the editor.
- Highlighting: each edit recolors a
<pre>that sits behind the text area. The text area’s own text is transparent, so Shiny still reads a plain<textarea>. - Resizing: a
ResizeObserverrefits the diagram when the sidebar opens or closes. - PNG download: draws the saved SVG on a canvas from a
data:URL. Ablob:URL would taint the canvas, because the HTML labels sit inforeignObjectelements.
Because these run in the browser, they respond at once and add no load on the server.
Recap
Edits become committed code through the Auto-Update switch or the Render button. viewer_server() prepares the code and options in Python and sends them as one custom message. The browser parses, draws, and attaches pan and zoom, and a parse error leaves the last good diagram on the canvas.