Codex Desktop Mermaid state diagrams render overlapping transition labels
Codex Desktop version
26.730.61639 (build 6234)
Subscription
Not included; this is a local rendering issue and does not appear subscription-dependent.
Platform
macOS — Darwin 25.5.0, Apple Silicon (arm64)
Description
Mermaid stateDiagram-v2 blocks can render transition labels on top of one another in Codex Desktop. With reverse transitions, a self-loop, and longer CJK labels, the label 准备失败或取消预占 overlaps a neighboring transition label, making the diagram difficult to read.
This report intentionally excludes account information, local paths, conversation IDs, private repository names, and other workspace content.
Steps to reproduce
- Open Codex Desktop.
- Render an assistant Markdown response containing:
stateDiagram-v2
[*] --> IDLE
IDLE --> DISPATCHING: "reserve：抢到执行权"
DISPATCHING --> RUNNING: "tryStart：启动 Agent，generation + 1"
RUNNING --> IDLE: "end：正常结束"
IDLE --> IDLE: "暂无任务"
DISPATCHING --> IDLE: "准备失败或取消预占"
RUNNING --> IDLE: "forceEnd：取消或异常恢复"- Observe the transition labels near the
IDLE/DISPATCHINGedge.
Actual behavior
The long transition label overlaps another edge label. The text becomes partially obscured even though the diagram container has ample horizontal space.
Expected behavior
Transition labels should be laid out without colliding, or Codex Desktop should use a layout/fallback that keeps all labels legible.
Additional context
- The desktop bundle's third-party notices identify Mermaid 11.16.0.
- The packaged renderer initializes Mermaid with
htmlLabels: falseand renders the SVG directly; no post-layout collision handling was observed. - Codex Desktop sanitizes Mermaid init directives, so users cannot reliably apply a per-diagram layout workaround.
- A related upstream Mermaid state-diagram layout issue is https://github.com/mermaid-js/mermaid/issues/6336, though this report specifically concerns overlapping transition labels in the Codex Desktop rendering surface.
2 Comments
Thanks for the clean repro and exact Mermaid source. I can replicate this class of overlap pattern against Mermaid layouts with dense state edges and
htmlLabels: false(as you already captured).Could you confirm whether the same snippet reproduces in a standalone Mermaid renderer with version 11.16.0 outside Codex? If it does, this is likely renderer-level and we can narrow toward a safer workaround on the Desktop wrapper side.
If it does not reproduce outside Codex, please share a tiny HTML/minimal snippet showing your exact renderer init path so we can isolate whether the host-side wrapper is adding an additional layout pass.
Confirmed: the exact snippet reproduces outside Codex with Mermaid 11.16.0.
I tested it in a standalone HTML page in Chrome, loading
mermaid.min.jsdirectly from the npm packagemermaid@11.16.0. No Codex code or host-side layout step was involved.Results:
``
js
``mermaid.initialize({
startOnLoad: false,
securityLevel: "strict",
suppressErrorRendering: true,
});
``
js
``mermaid.initialize({
startOnLoad: false,
securityLevel: "strict",
suppressErrorRendering: true,
deterministicIds: false,
deterministicIDSeed: "codex-mermaid",
htmlLabels: false,
flowchart: { htmlLabels: false },
});
For the second run, the two distinct edge-label bounding boxes intersected as follows:
"reserve：抢到执行权":(94.32, 135.60)–(257.64, 158.60)"准备失败或取消预占":(187.99, 140.96)–(346.38, 163.96)69.65 × 17.63 pxThe standalone render visually matches the overlap reported in the original screenshot.
Conclusion: this is reproducible at the Mermaid 11.16.0 renderer/layout level; a Codex-specific additional layout pass is not required to trigger it. A Desktop-side workaround or safer fallback could still be useful, but the underlying collision is not unique to the Codex wrapper.