Split out of #790, where it degraded the demo reel's sendfile beat badly enough that the caption "diagrams, documents, code" stopped being true. It is a product bug, not a pipeline one, so it should not be fixed in scripts/demo-gif/.
Symptom
A rendered Mermaid diagram in a transcript has an intrinsic width of 1244.75px inside a 542px container, so it is downscaled to 41%. Labels are illegible at that size, and the diagram consumes enough vertical space to push the neighbouring markdown card out of view.
It is NOT a timing race — measured, not assumed
The obvious theory is that Mermaid renders asynchronously and the new @font-face declarations (added for runtime theming) delay page-idle, so the diagram is captured mid-render. That theory is disproven. The rendered pixel size was byte-identical at 0 ms, 1.2 s and 5.2 s after the SVG existed. Waiting longer changes nothing.
It is a sizing problem: the diagram's intrinsic width grew because its text metrics come from the new font stack, and nothing constrains the SVG to its container.
⚠️ A curated note in CLAUDE.md still describes this as an async/page-idle timing interaction. That note is stale and should be corrected when this is fixed — the measurement above supersedes it.
Where to look
packages/web/src/components/Mermaid.tsx. The component's own min-h/h- values were unchanged by the design work; only colour tokens changed on that branch, which is what points at intrinsic sizing rather than a regression in layout code.
Likely shapes of a fix (unranked, none validated):
- constrain the SVG to the container width and let it scale down with a floor, rather than scaling to fit unconditionally;
- allow horizontal scroll / click-to-expand for diagrams past a width threshold, so detail survives at reading size;
- pin Mermaid's font stack so its text metrics do not follow the active theme.
Acceptance
A wide diagram in a 542px transcript column stays legible at reading size, and does not evict the content next to it. Verify by sampling the rendered SVG's box, not by reading component props.
Split out of #790, where it degraded the demo reel's
sendfilebeat badly enough that the caption "diagrams, documents, code" stopped being true. It is a product bug, not a pipeline one, so it should not be fixed inscripts/demo-gif/.Symptom
A rendered Mermaid diagram in a transcript has an intrinsic width of 1244.75px inside a 542px container, so it is downscaled to 41%. Labels are illegible at that size, and the diagram consumes enough vertical space to push the neighbouring markdown card out of view.
It is NOT a timing race — measured, not assumed
The obvious theory is that Mermaid renders asynchronously and the new
@font-facedeclarations (added for runtime theming) delay page-idle, so the diagram is captured mid-render. That theory is disproven. The rendered pixel size was byte-identical at 0 ms, 1.2 s and 5.2 s after the SVG existed. Waiting longer changes nothing.It is a sizing problem: the diagram's intrinsic width grew because its text metrics come from the new font stack, and nothing constrains the SVG to its container.
Where to look
packages/web/src/components/Mermaid.tsx. The component's ownmin-h/h-values were unchanged by the design work; only colour tokens changed on that branch, which is what points at intrinsic sizing rather than a regression in layout code.Likely shapes of a fix (unranked, none validated):
Acceptance
A wide diagram in a 542px transcript column stays legible at reading size, and does not evict the content next to it. Verify by sampling the rendered SVG's box, not by reading component props.