Skip to content

fix(mermaid): fit wide diagrams, span full width when toc is hidden - #61

Merged
denolfe merged 2 commits into
mainfrom
feat/mermaid-intelligent-width
Oct 30, 2026
Merged

denolfe merged 2 commits into
mainfrom
feat/mermaid-intelligent-width

Conversation

@denolfe

@denolfe denolfe commented Oct 30, 2026 •

Copy link
Copy Markdown
Owner

Wide mermaid and DOT diagrams no longer clip on the right. A diagram too wide for its column renders again with tighter spacing until it fits. With the TOC hidden, diagrams can also use the free columns past the reading width.

CleanShot.2026-10-29.at.9.27.06.PM.mp4
 src/app/
 ├── App.tsx                   # derives breakoutWidth
 ├── components/
 │   ├── Viewer.tsx            # spans breakoutWidth; prose box stays at contentWidth
 │   └── blocks/CodeBlock.tsx  # renders the fitted diagram
 └── lib/
+    ├── diagram-fit.ts        # picks the loosest render that fits
     ├── preprocess.ts         # keeps the mermaid source on the node
     ├── visible-text.ts       # projects the fitted text for search
     └── commands.ts           # re-runs search on width change

Root Cause

Diagrams render to ASCII once, at load, before any width is known. ASCII art can't wrap. The Viewer clipped anything wider than the content column.

The content column is capped at the reading width (width config, default 100). Hiding the TOC adds only the sidebar's own columns. On a wide terminal, the space right of the TOC stayed empty either way.

The Viewer's inner box also had maxWidth set to the content cap. That width included its 1-column right padding. At the cap, blocks got one column less than contentWidth.

Changes

  • Width-aware diagram text
    • New codeText returns the default render when it fits. Otherwise it tries four tighter spacing presets and takes the first that fits.
    • When nothing fits, the tightest render wins. It clips the least.
    • CodeBlock, row estimates, and the search Projection (the text model that search and highlights run on) all read codeText. Highlights stay on the right characters at every width.
    • A committed search re-runs when the width changes. A re-fit moves match offsets inside diagrams.
  • Breakout width
    • New breakoutWidth in app state. It equals contentWidth with the TOC shown and the whole Viewer column with it hidden.
    • With the TOC hidden, the Viewer, sticky overlay, Cover (the mask shown during document swaps), and search bar span the terminal. The scrollbar moves to the right edge.
    • Prose stays at contentWidth. A diagram's box sets minWidth to the diagram's width and overflows the prose box.
  • Viewer column fix
    • The inner box is now exactly contentWidth + 1 wide, padding included. Blocks get the full contentWidth at the cap.
  • Docs and fixtures
    • test/mermaid-width.md covers each fit case for manual checks.
    • ARCHITECTURE.md and the CLAUDE.md glossary describe the breakout width.

Design Decisions

  • Diagrams compact through the renderer's spacing options (paddingX, boxBorderPadding). This fits most flowcharts at any terminal width. Horizontal scroll was the alternative; it would add a second scroll axis to the Viewer.
  • Breakout applies only with the TOC hidden. The seam drag (resizing content by dragging the content/TOC border) assumes the Viewer ends at contentWidth. Breaking out with the TOC shown would dock the TOC to the right edge and need a new drag model.
  • Prose keeps the reading cap when the TOC is hidden. Lifting the cap would stretch text lines across the whole terminal.
  • Sequence, class, and ER diagrams ignore the spacing options. They still clip when wider than the column.
  • Diagrams in lists and blockquotes fit to the full column, not the indented one. Framed code blocks have the same limit.

Overall Flow

 load
   renderDiagramBlocks              # default-spacing render
+    keep mermaid source on the node
 render
-  CodeBlock prints node.value
+  breakoutWidth = TOC shown ? contentWidth : whole Viewer column
+  codeText(node, breakoutWidth)    # loosest preset that fits
+    read by CodeBlock, Projection, search, row estimates

Similar Issues

🤖 Written with AI

Diagrams wider than the content column re-render with tighter spacing until
they fit, falling back to the tightest render. CodeBlock, the search
projection, and row estimates all read the fitted text, and a committed
search re-runs when the width changes.

The Viewer's inner box no longer caps at contentMaxWidth, which included its
right padding and cost blocks one column at the reading cap.

Adds test/mermaid-width.md for manual checks.
@github-actions

Copy link
Copy Markdown

Startup benchmark (--render test/exhaustive.md, linux-x64)

build mean ratio verdict
baseline (main@bade4ae) 233.0ms ± 5.8ms —
PR 240.1ms ± 16.9ms 1.03× ✅ ok

Thresholds: warn ≥ 1.1×, fail ≥ 1.25×. Baseline built from main.

First-frame (large.md, runs=10)

metric baseline (main@bade4ae) PR ratio verdict
first-frame 157.3ms 157.1ms 1.00× ✅ ok

Thresholds: warn ≥ 1.1×, fail ≥ 1.25×. Baseline built from main.

Scroll (large.md)

metric baseline (main@bade4ae) PR ratio verdict
full_mount 7637.0ms 5365.0ms 0.70× ✅ ok
step_p50 18.1ms 19.7ms 1.08× ✅ ok
step_search_p50 17.5ms 18.7ms 1.07× ✅ ok
stepMatch_p50 13.3ms 14.0ms 1.05× ✅ ok
commit 4784.9ms 3953.6ms 0.83× ✅ ok

Thresholds: warn ≥ 1.1×, fail ≥ 1.25×. Baseline built from main.

@denolfe
denolfe merged commit 3570bc4 into main Oct 30, 2026
8 checks passed
@denolfe
denolfe deleted the feat/mermaid-intelligent-width branch October 30, 2026 01:37
denolfe added a commit that referenced this pull request Oct 30, 2026
- chore: push branch and tag atomically on release (f7f3e4e)
- chore: always pull main before release (08feae3)
- fix(mermaid): fit wide diagrams, span full width when toc is hidden (#61) (3570bc4)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant