Render log diagrams with @joycostudio/trazo instead of Mermaid

[justkahdri]

What

Replaces every Mermaid diagram in the two diagram-heavy log articles with the @joycostudio/trazo layout engine, authored as DSL string literals through a new <Diagram> MDX component.

<Diagram> takes the DSL source as a template-literal child, auto-detects the language from the first line (flow / sequence / block / git), and runs the matching pure layout server-side — it's a React Server Component, so the diagrams ship zero client JS (unlike the old <Mermaid> which rendered client-side via the mermaid bundle).

Changes

• Add @joycostudio/trazo@^0.2.0
• Add components/flow.tsx exporting <Diagram>, wired into mdx-components.tsx
• 07-nextjs-promises-ppr.mdx — 7 diagrams: flow charts, 2 sequence diagrams, 2 subgraph flows, and the static-shell layout (now flow TD)
• 08-webgl-scroll-sync.mdx — 10 diagrams: flow charts with subgraphs, sequence diagrams, multi-line labels

Conventions

• Flowchart edges use --- (neutral path) and === (colored path) — no arrowheads. Arrowheads appear only on sequence-diagram messages, where direction (->> / -->>) is intrinsic to the diagram.
• Subgraph containers and sequence lifelines/notes are used directly (no flattening into text prefixes).

Verification

• tsc --noEmit — clean
• All 17 DSL blocks parse + lay out standalone (17/17)
• Both pages render on a dev server: 7 + 10 trazo SVGs, subgraph boxes, lifelines, and note boxes all present; no parse/runtime errors, no error overlay

Follow-ups (out of scope here)

• components/mermaid.tsx, the mermaid dependency, and remarkMdxMermaid in source.config.ts are now unused in content but left in place — safe to remove in a separate cleanup.
• components/flow.tsx exports Diagram (not Flow); the filename could be renamed to diagram.tsx later to avoid churn here.

🤖 Generated with Claude Code

Greptile Summary

This PR replaces all Mermaid diagrams in the two diagram-heavy log articles with @joycostudio/trazo DSL via a new <Diagram> RSC, and extends trazo theming to four additional log articles that previously used static images. The <Diagram> component runs layout server-side, ships zero client JS, and wires articleNumber through getMDXComponents for per-article figure numbering.

• components/flow.tsx: new RSC that auto-detects DSL language, dispatches to the matching trazo parser/layout, and renders either a <Graph> SVG or an ASCII <pre> block inside a styled <figure>.
• app/styles/theming.css: adds --chart-N-foreground and --trazo-error-foreground tokens across all four themes so saturated trazo nodes pass contrast checks.
• 17 MDX diagrams across 07-nextjs-promises-ppr.mdx and 08-webgl-scroll-sync.mdx converted from Mermaid fenced blocks to <Diagram> JSX; static images in 11, 12, and 14 also replaced.

Confidence Score: 5/5

Safe to merge; the core component and all diagram conversions are correct. The two style-rule nits are cosmetic and do not affect rendering or behaviour.

The new Diagram RSC is well-structured: server-only, typed, error-throwing on parse failures, and correctly themed. All 17 MDX diagram blocks were converted without data loss. The only findings are em-dash violations in a diagram title and CSS comments, neither of which affects runtime output.

content/logs/12-the-render-pipeline.mdx (em dash in title prop) and app/styles/theming.css (em dashes in comments).

Important Files Changed

Filename	Overview
components/flow.tsx	New RSC Diagram component wrapping @joycostudio/trazo: detects DSL lang, lays out graph server-side, renders via <Graph> or ASCII <pre>. Error handling, theming, and tag generation look correct.
mdx-components.tsx	Adds Diagram to the MDX component map, threaded with articleNumber from the page-level opts. Clean change.
app/(registry)/[[...slug]]/page.tsx	Passes { logNumber } as the second arg to getMDXComponents so Diagram receives articleNumber for per-article numbering tags.
content/logs/07-nextjs-promises-ppr.mdx	7 Mermaid blocks replaced with <Diagram> DSL; edge styles and node roles look consistent with stated conventions.
content/logs/08-webgl-scroll-sync.mdx	10 Mermaid blocks replaced with <Diagram> DSL; bidirectional <==> edge on diagram 3 and arrowhead --> on diagram 11 deviate from the stated no-arrowhead convention but appear intentional.
content/logs/11-wtf-is-layout-thrashing.mdx	Static image replaced with a trazo flow diagram; cry --> layout edge uses --> to emphasise the forced-reflow cycle back to layout.
content/logs/12-the-render-pipeline.mdx	Static image replaced with a trazo diagram; the title prop contains an em dash in violation of the no-em-dash rule.
content/logs/14-phantom-merge-conflicts.mdx	Two ascii diagrams and one flow diagram replace bash code blocks; backslashes correctly escaped in template literals.
app/styles/theming.css	Adds --chart-N-foreground and --trazo-error-foreground tokens for all four themes; three new CSS comments use em dashes in violation of the house style rule.
package.json	Adds @joycostudio/trazo@^0.5.0 dependency.

_{Reviews (2): Last reviewed commit: "chore: remove stray trazo scratch notes ..." | Re-trigger Greptile}

Context used:

• Rule used - Do not use em dashes (—) in prose, frontmatter des... (source)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
joyco-hub	Ready	Preview, Comment	Jul 14, 2026 9:46pm

[greptile-apps]

Em dashes in diagram labels

Diagram labels are rendered as visible SVG text for readers, and the team's style rule prohibits em dashes in any user-visible text, replacing them with a colon, comma, or parentheses instead. Two instances appear here (await getCart() — 200ms, await getFlags() — 150ms), and the pattern repeats elsewhere in this file (Static Shell — built at build time, served from CDN) and in 08-webgl-scroll-sync.mdx (the two edge labels D (delta) — JS animates scrollTop... and D (delta) — JS reads scrollY...).

Rule Used: Do not use em dashes (—) in prose, frontmatter des... (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: content/logs/07-nextjs-promises-ppr.mdx
Line: 383-384

Comment:
**Em dashes in diagram labels**

Diagram labels are rendered as visible SVG text for readers, and the team's style rule prohibits em dashes in any user-visible text, replacing them with a colon, comma, or parentheses instead. Two instances appear here (`await getCart() — 200ms`, `await getFlags() — 150ms`), and the pattern repeats elsewhere in this file (`Static Shell — built at build time, served from CDN`) and in `08-webgl-scroll-sync.mdx` (the two edge labels `D (delta) — JS animates scrollTop...` and `D (delta) — JS reads scrollY...`).

**Rule Used:** Do not use em dashes (—) in prose, frontmatter des... ([source](greptile.json))

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!