# 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()](../reference/editor_server.md#shypermaid.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:


*\[Rich HTML output -- view on the documentation site\]*


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()](../reference/viewer_server.md#shypermaid.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:


*\[Rich HTML output -- view on the documentation site\]*


The Python side of this picture is all of [viewer_server()](../reference/viewer_server.md#shypermaid.viewer_server). Its call tree from [`callgrove`](https://mjfrigaard.github.io/callgrove/) shows the three helpers it calls in `diagram.py`. The tree stops at the browser, because `callgrove` only reads Python files:


``` python
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()](../reference/viewer_server.md#shypermaid.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()](../reference/set_direction.md#shypermaid.set_direction), and the options from [render_config()](../reference/render_config.md#shypermaid.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()](../reference/render_config.md#shypermaid.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-action` and `data-sm-target` attributes, 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 `ResizeObserver` refits the diagram when the sidebar opens or closes.
- PNG download: draws the saved SVG on a canvas from a `data:` URL. A `blob:` URL would taint the canvas, because the HTML labels sit in `foreignObject` elements.

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()](../reference/viewer_server.md#shypermaid.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.
