@djangocfg/ui-tools 2.1.404 → 2.1.408

package/src/tools/Mermaid/hooks/useMermaidRenderer.ts

@@ -1,10 +1,21 @@
 /**
- * Hook for rendering Mermaid diagrams with debounce and validation
+ * Hook for rendering Mermaid diagrams with debounced, race-safe rendering.
+ *
+ * Mermaid (~800KB) is imported eagerly here because the whole component
+ * tree is already lazy-loaded behind `Mermaid.client` — splitting again
+ * would just add a second waterfall for no win.
  */
 
 import mermaid from 'mermaid';
 import { useEffect, useRef, useState } from 'react';
 
+import {
+    applyMermaidErRowColors,
+    applyMermaidTextColors,
+    getThemeColor,
+    getTextColor,
+    isVerticalDiagram,
+} from '../utils/mermaid-helpers';
 import { useMermaidCleanup } from './useMermaidCleanup';
 import { useMermaidValidation } from './useMermaidValidation';
 
@@ -12,6 +23,8 @@ interface UseMermaidRendererProps {
     chart: string;
     theme: string;
     isCompact?: boolean;
+    /** Debounce window in ms before (re)rendering. Default 300. */
+    debounceMs?: number;
 }
 
 interface MermaidRenderResult {
@@ -19,215 +32,298 @@ interface MermaidRenderResult {
     svgContent: string;
     isVertical: boolean;
     isRendering: boolean;
+    /** Set when the last render failed with a syntax / parse error. */
+    error: string | null;
 }
 
-// Utility function to apply text colors to Mermaid SVG
-const applyMermaidTextColors = (container: HTMLElement, textColor: string) => {
-    const svgElement = container.querySelector('svg');
-    if (svgElement) {
-        // SVG text elements use 'fill'
-        svgElement.querySelectorAll('text').forEach((el) => {
-            (el as SVGElement).style.fill = textColor;
-        });
-
-        // HTML elements inside foreignObject use 'color'
-        svgElement.querySelectorAll('.nodeLabel, .edgeLabel').forEach((el) => {
-            (el as HTMLElement).style.color = textColor;
-        });
-    }
-};
-
-// Detect if diagram is vertical (tall and narrow)
-const isVerticalDiagram = (svgElement: SVGSVGElement): boolean => {
-    const viewBox = svgElement.getAttribute('viewBox');
-    if (viewBox) {
-        const [, , width, height] = viewBox.split(' ').map(Number);
-        if (width === undefined || height === undefined) return false;
-        return height > width * 1.5;
-    }
-    const bbox = svgElement.getBBox?.();
-    if (bbox) {
-        return bbox.height > bbox.width * 1.5;
-    }
-    return false;
-};
-
-export function useMermaidRenderer({ chart, theme, isCompact = false }: UseMermaidRendererProps): MermaidRenderResult {
+/**
+ * Section color scales for timeline / journey / mindmap / pie diagrams.
+ *
+ * These diagram types do NOT use `mainBkg` for their boxes — they cycle
+ * through `cScale0..N` (and `pie1..N`) instead. Mermaid's `base` theme
+ * derives those scales from `primaryColor`, which lands far too dark in
+ * light mode (dark box) while the section label still inherits the
+ * default dark `textColor` — i.e. dark text on a dark box.
+ *
+ * We pin an explicit, theme-aware palette: mid-saturation backgrounds
+ * that read on either page background, each paired with an explicit
+ * contrasting label color via `cScaleLabel*`. `cScalePeer*` colors the
+ * sub-task boxes that sit under a section.
+ */
+const SECTION_SCALES = {
+    light: [
+        { bg: '#1f6f8b', label: '#ffffff', peer: '#3a8ba6' },
+        { bg: '#7b5ea7', label: '#ffffff', peer: '#977dc0' },
+        { bg: '#2e8b57', label: '#ffffff', peer: '#4caf7d' },
+        { bg: '#c25a3a', label: '#ffffff', peer: '#d6805f' },
+        { bg: '#3a6ea5', label: '#ffffff', peer: '#5d8cc0' },
+        { bg: '#a8456b', label: '#ffffff', peer: '#c06b8b' },
+        { bg: '#5f8f3a', label: '#ffffff', peer: '#80aa5d' },
+        { bg: '#9a7d2e', label: '#ffffff', peer: '#b89c50' },
+    ],
+    dark: [
+        { bg: '#3aa6c9', label: '#0b1620', peer: '#2b7d99' },
+        { bg: '#b39ddb', label: '#1a142b', peer: '#8a72b5' },
+        { bg: '#66c990', label: '#0c1f15', peer: '#479a6b' },
+        { bg: '#e8956f', label: '#2a1409', peer: '#bd6f4c' },
+        { bg: '#79a8d9', label: '#0d1726', peer: '#577fad' },
+        { bg: '#d987a8', label: '#2a0f1b', peer: '#ad6082' },
+        { bg: '#a4cf7a', label: '#142008', peer: '#7da352' },
+        { bg: '#d4bb6e', label: '#241c08', peer: '#a8924c' },
+    ],
+} as const;
+
+/**
+ * Build Mermaid `themeVariables` from our semantic tokens.
+ *
+ * Tokens are read live from the DOM so the diagram tracks light/dark
+ * without a hard-coded palette. Fallbacks only fire during SSR or before
+ * stylesheets load.
+ */
+function buildThemeVariables(theme: string, fontSize: string) {
+    const isDark = theme === 'dark';
+    const fg = getThemeColor('--foreground', isDark ? 'hsl(0 0% 98%)' : 'hsl(0 0% 9%)');
+    const card = getThemeColor('--card', isDark ? 'hsl(0 0% 8%)' : 'hsl(0 0% 100%)');
+    const muted = getThemeColor('--muted', isDark ? 'hsl(0 0% 15%)' : 'hsl(0 0% 96%)');
+    const border = getThemeColor('--border', isDark ? 'hsl(0 0% 15%)' : 'hsl(0 0% 90%)');
+    const primary = getThemeColor('--primary', isDark ? 'hsl(189 100% 50%)' : 'hsl(192 90% 35%)');
+    const accent = getThemeColor('--accent', muted);
+    const secondary = getThemeColor('--secondary', muted);
+    const background = getThemeColor('--background', isDark ? 'hsl(0 0% 4%)' : 'hsl(0 0% 94%)');
+    const destructive = getThemeColor('--destructive', 'hsl(0 84% 60%)');
+    const destructiveFg = getThemeColor('--destructive-foreground', 'hsl(0 0% 98%)');
+
+    const scales = SECTION_SCALES[isDark ? 'dark' : 'light'];
+    // `cScale*` / `pie*` / `fillType*` are flat keys (cScale0, pie1, ...).
+    //
+    // `fillType*` is what the **journey** diagram actually paints its
+    // section / task rects with. Left unset, Mermaid derives it by
+    // rotating the hue of `cScale*` and forcing odd indexes to
+    // `hsl(H, 0%, 9%)` — a near-black box. Pinning `fillType*` to our
+    // explicit palette kills the dark-on-dark sections.
+    const sectionVars: Record<string, string> = {};
+    scales.forEach((s, i) => {
+        sectionVars[`cScale${i}`] = s.bg;
+        sectionVars[`cScaleLabel${i}`] = s.label;
+        sectionVars[`cScaleInv${i}`] = s.label;
+        sectionVars[`cScalePeer${i}`] = s.peer;
+        sectionVars[`fillType${i}`] = s.bg;
+        sectionVars[`surface${i}`] = s.bg;
+        // Pie slices are 1-indexed and have no separate label var — the
+        // slice text color is global (`pieSectionTextColor`).
+        sectionVars[`pie${i + 1}`] = s.bg;
+    });
+
+    return {
+        primaryColor: primary,
+        primaryTextColor: fg,
+        primaryBorderColor: primary,
+        secondaryColor: secondary,
+        secondaryTextColor: fg,
+        secondaryBorderColor: border,
+        tertiaryColor: accent,
+        tertiaryTextColor: fg,
+        tertiaryBorderColor: border,
+        mainBkg: card,
+        textColor: fg,
+        nodeBorder: border,
+        nodeTextColor: fg,
+        secondBkg: muted,
+        lineColor: primary,
+        edgeLabelBackground: card,
+        clusterBkg: muted,
+        clusterBorder: primary,
+        background,
+        labelBackground: card,
+        labelTextColor: fg,
+        errorBkgColor: destructive,
+        errorTextColor: destructiveFg,
+
+        // --- ER diagram ---
+        // ER attribute-row zebra fills are derived from `mainBkg` by
+        // Mermaid and ignore `themeVariables` — they are re-asserted
+        // post-render via `applyMermaidErRowColors`.
+
+        // --- Section-colored diagrams (timeline / journey / mindmap) ---
+        ...sectionVars,
+        // Timeline / journey section title bars + the global label fallback.
+        cScaleLabel0: scales[0]?.label ?? fg,
+        // Journey actor faces / labels in the legend.
+        actorBkg: card,
+        actorBorder: border,
+        actorTextColor: fg,
+        actorLineColor: border,
+        // Mindmap nodes inherit `cScale*`; their text uses `nodeTextColor`
+        // on the outer ring — keep it readable on the page background.
+
+        // --- Pie chart ---
+        pieTitleTextColor: fg,
+        pieSectionTextColor: isDark ? '#0b1620' : '#ffffff',
+        pieSectionTextSize: '13px',
+        pieLegendTextColor: fg,
+        pieLegendTextSize: '13px',
+        pieStrokeColor: background,
+        pieStrokeWidth: '2px',
+        pieOuterStrokeColor: border,
+        pieOuterStrokeWidth: '1px',
+        pieOpacity: '1',
+
+        // --- Git graph ---
+        git0: scales[0]?.bg ?? primary,
+        git1: scales[1]?.bg ?? secondary,
+        git2: scales[2]?.bg ?? accent,
+        git3: scales[3]?.bg ?? primary,
+        git4: scales[4]?.bg ?? secondary,
+        git5: scales[5]?.bg ?? accent,
+        git6: scales[6]?.bg ?? primary,
+        git7: scales[7]?.bg ?? secondary,
+        gitBranchLabel0: scales[0]?.label ?? fg,
+        gitBranchLabel1: scales[1]?.label ?? fg,
+        gitBranchLabel2: scales[2]?.label ?? fg,
+        gitBranchLabel3: scales[3]?.label ?? fg,
+        gitBranchLabel4: scales[4]?.label ?? fg,
+        gitBranchLabel5: scales[5]?.label ?? fg,
+        gitBranchLabel6: scales[6]?.label ?? fg,
+        gitBranchLabel7: scales[7]?.label ?? fg,
+        gitInv0: scales[0]?.label ?? fg,
+        commitLabelColor: fg,
+        commitLabelBackground: card,
+        tagLabelColor: fg,
+        tagLabelBackground: muted,
+        tagLabelBorder: border,
+
+        fontSize,
+        fontFamily: 'Inter, system-ui, sans-serif',
+    };
+}
+
+export function useMermaidRenderer({
+    chart,
+    theme,
+    isCompact = false,
+    debounceMs = 300,
+}: UseMermaidRendererProps): MermaidRenderResult {
     const mermaidRef = useRef<HTMLDivElement>(null);
-    const renderTimerRef = useRef<NodeJS.Timeout | null>(null);
+    const renderTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    // Monotonic token: every effect run bumps it, and an in-flight async
+    // render checks it before touching the DOM. Guards against a stale
+    // chart's `mermaid.render` resolving after a newer one started.
+    const renderSeqRef = useRef(0);
+
     const [svgContent, setSvgContent] = useState<string>('');
     const [isVertical, setIsVertical] = useState(false);
     const [isRendering, setIsRendering] = useState(false);
+    const [error, setError] = useState<string | null>(null);
 
     const { isMermaidCodeComplete } = useMermaidValidation();
     const { cleanupMermaidErrors } = useMermaidCleanup();
 
     useEffect(() => {
-        // Get CSS variables for semantic colors
-        const getCSSVariable = (variable: string) => {
-            if (typeof document === 'undefined') return '';
-            const value = getComputedStyle(document.documentElement).getPropertyValue(variable).trim();
-            if (!value) return '';
-            // If value is already a complete color (hex, rgb, hsl with parentheses), return as-is
-            if (value.startsWith('#') || value.startsWith('rgb') || value.startsWith('hsl(')) {
-                return value;
-            }
-            // Otherwise assume it's HSL components and wrap in hsl()
-            return `hsl(${value})`;
-        };
-
-        const diagramFontSize = isCompact ? '12px' : '14px';
-
-        const themeVariables = theme === 'dark' ? {
-            primaryColor: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            primaryTextColor: getCSSVariable('--foreground') || 'hsl(210 40% 98%)',
-            primaryBorderColor: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            secondaryColor: getCSSVariable('--muted') || 'hsl(217.2 32.6% 17.5%)',
-            secondaryTextColor: getCSSVariable('--foreground') || 'hsl(210 40% 98%)',
-            secondaryBorderColor: getCSSVariable('--border') || 'hsl(217.2 32.6% 27.5%)',
-            tertiaryColor: getCSSVariable('--accent') || 'hsl(217.2 32.6% 20%)',
-            tertiaryTextColor: getCSSVariable('--foreground') || 'hsl(210 40% 98%)',
-            tertiaryBorderColor: getCSSVariable('--border') || 'hsl(217.2 32.6% 27.5%)',
-            mainBkg: getCSSVariable('--card') || 'hsl(222.2 84% 8%)',
-            textColor: getCSSVariable('--foreground') || 'hsl(210 40% 98%)',
-            nodeBorder: getCSSVariable('--border') || 'hsl(217.2 32.6% 27.5%)',
-            nodeTextColor: getCSSVariable('--foreground') || 'hsl(210 40% 98%)',
-            secondBkg: getCSSVariable('--muted') || 'hsl(217.2 32.6% 17.5%)',
-            lineColor: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            edgeLabelBackground: getCSSVariable('--card') || 'hsl(222.2 84% 8%)',
-            clusterBkg: getCSSVariable('--muted') || 'hsl(217.2 32.6% 12%)',
-            clusterBorder: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            background: getCSSVariable('--background') || 'hsl(222.2 84% 4.9%)',
-            labelBackground: getCSSVariable('--card') || 'hsl(222.2 84% 8%)',
-            labelTextColor: getCSSVariable('--foreground') || 'hsl(210 40% 98%)',
-            errorBkgColor: getCSSVariable('--destructive') || 'hsl(0 62.8% 30.6%)',
-            errorTextColor: 'hsl(210 40% 98%)',
-            fontSize: diagramFontSize,
-            fontFamily: 'Inter, system-ui, sans-serif',
-        } : {
-            primaryColor: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            primaryTextColor: getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)',
-            primaryBorderColor: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            secondaryColor: getCSSVariable('--secondary') || 'hsl(210 40% 96.1%)',
-            secondaryTextColor: getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)',
-            secondaryBorderColor: getCSSVariable('--border') || 'hsl(214.3 31.8% 91.4%)',
-            tertiaryColor: getCSSVariable('--muted') || 'hsl(210 40% 96.1%)',
-            tertiaryTextColor: getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)',
-            tertiaryBorderColor: getCSSVariable('--border') || 'hsl(214.3 31.8% 91.4%)',
-            mainBkg: getCSSVariable('--card') || 'hsl(0 0% 100%)',
-            textColor: getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)',
-            nodeBorder: getCSSVariable('--border') || 'hsl(214.3 31.8% 91.4%)',
-            nodeTextColor: getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)',
-            secondBkg: getCSSVariable('--muted') || 'hsl(210 40% 96.1%)',
-            lineColor: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            edgeLabelBackground: getCSSVariable('--card') || 'hsl(0 0% 100%)',
-            clusterBkg: getCSSVariable('--accent') || 'hsl(210 40% 98%)',
-            clusterBorder: getCSSVariable('--primary') || 'hsl(221.2 83.2% 53.3%)',
-            background: getCSSVariable('--background') || 'hsl(0 0% 100%)',
-            labelBackground: getCSSVariable('--card') || 'hsl(0 0% 100%)',
-            labelTextColor: getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)',
-            errorBkgColor: getCSSVariable('--destructive') || 'hsl(0 84.2% 60.2%)',
-            errorTextColor: 'hsl(210 40% 98%)',
-            fontSize: diagramFontSize,
-            fontFamily: 'Inter, system-ui, sans-serif',
-        };
+        const seq = ++renderSeqRef.current;
+        const isStale = () => seq !== renderSeqRef.current;
 
-        mermaid.initialize({
-            startOnLoad: false,
-            theme: 'base',
-            securityLevel: 'loose',
-            suppressErrorRendering: true, // Prevent mermaid from appending errors to body
-            fontFamily: 'Inter, system-ui, sans-serif',
-            flowchart: {
-                useMaxWidth: true,
-                htmlLabels: true,
-                curve: 'basis',
-            },
-            themeVariables,
-        });
+        const fontSize = isCompact ? '12px' : '14px';
 
         const renderChart = async () => {
-            if (!mermaidRef.current || !chart) return;
+            const host = mermaidRef.current;
+            if (!host || !chart) {
+                setIsRendering(false);
+                return;
+            }
 
-            // Validate code completeness
+            // Streaming guard: an incomplete diagram (still being typed /
+            // streamed) would throw a parse error. Keep the previous SVG
+            // visible and just show the spinner — don't flash an error.
             if (!isMermaidCodeComplete(chart)) {
                 setIsRendering(true);
                 return;
             }
 
-            try {
-                setIsRendering(true);
+            setIsRendering(true);
+            setError(null);
 
-                // Clear container
-                if (mermaidRef.current) {
-                    mermaidRef.current.innerHTML = '';
-                }
+            // `mermaid.initialize` is global + idempotent; re-running it
+            // per render keeps `themeVariables` in sync with the live
+            // light/dark tokens (cheap, no library reload).
+            mermaid.initialize({
+                startOnLoad: false,
+                theme: 'base',
+                securityLevel: 'loose',
+                suppressErrorRendering: true,
+                fontFamily: 'Inter, system-ui, sans-serif',
+                flowchart: { useMaxWidth: true, htmlLabels: true, curve: 'basis' },
+                themeVariables: buildThemeVariables(theme, fontSize),
+            });
 
-                const id = `mermaid-${Math.random().toString(36).substring(2, 9)}`;
+            const id = `mermaid-${Math.random().toString(36).slice(2, 9)}`;
+
+            try {
+                // `mermaid.parse` validates without mutating the DOM —
+                // catches syntax errors before `render` appends anything.
+                await mermaid.parse(chart);
                 const { svg } = await mermaid.render(id, chart);
 
-                if (mermaidRef.current) {
-                    const textColor = theme === 'dark'
-                        ? getCSSVariable('--foreground') || 'hsl(0 0% 90%)'
-                        : getCSSVariable('--foreground') || 'hsl(222.2 84% 4.9%)';
-
-                    const processedSvg = svg.replace(
-                        /<svg /,
-                        `<svg style="--mermaid-text-color: ${textColor};" `
-                    );
-
-                    mermaidRef.current.innerHTML = processedSvg;
-                    setSvgContent(processedSvg);
-
-                    applyMermaidTextColors(mermaidRef.current, textColor);
-
-                    const svgElement = mermaidRef.current.querySelector('svg');
-                    if (svgElement) {
-                        svgElement.style.maxWidth = '100%';
-                        svgElement.style.height = 'auto';
-                        svgElement.style.display = 'block';
-                        setIsVertical(isVerticalDiagram(svgElement));
-                    }
+                if (isStale() || !mermaidRef.current) return;
+
+                const textColor = getTextColor(theme);
+                const processedSvg = svg.replace(
+                    /<svg /,
+                    `<svg style="--mermaid-text-color: ${textColor};" `,
+                );
+
+                mermaidRef.current.innerHTML = processedSvg;
+                applyMermaidTextColors(mermaidRef.current, textColor);
+                // ER attribute rows zebra-stripe off `mainBkg` and ignore
+                // `themeVariables` — re-assert themed, contrasting fills.
+                applyMermaidErRowColors(
+                    mermaidRef.current,
+                    getThemeColor('--card', theme === 'dark' ? 'hsl(0 0% 8%)' : 'hsl(0 0% 100%)'),
+                    getThemeColor('--muted', theme === 'dark' ? 'hsl(0 0% 15%)' : 'hsl(0 0% 96%)'),
+                );
+
+                const svgElement = mermaidRef.current.querySelector('svg');
+                if (svgElement) {
+                    svgElement.style.maxWidth = '100%';
+                    svgElement.style.height = 'auto';
+                    svgElement.style.display = 'block';
+                    setIsVertical(isVerticalDiagram(svgElement));
                 }
 
+                setSvgContent(processedSvg);
+                setError(null);
                 setIsRendering(false);
-            } catch (error) {
-                console.error('Mermaid rendering error:', error);
-                setIsRendering(false);
+            } catch (err) {
+                // `render` may still have appended an orphan node to
+                // <body> despite `suppressErrorRendering` — sweep it.
                 cleanupMermaidErrors();
+                if (isStale()) return;
 
+                const message =
+                    err instanceof Error ? err.message : 'Failed to render diagram';
+                setError(message);
+                setSvgContent('');
+                setIsVertical(false);
+                setIsRendering(false);
                 if (mermaidRef.current) {
-                    mermaidRef.current.innerHTML = `
-                        <div class="p-4 text-destructive bg-destructive/10 border border-destructive/20 rounded-sm">
-                            <p class="font-semibold">Mermaid Diagram Error</p>
-                            <p class="text-sm">${error instanceof Error ? error.message : 'Unknown error'}</p>
-                        </div>
-                    `;
+                    mermaidRef.current.innerHTML = '';
                 }
             }
         };
 
-        // Clear previous timer
         if (renderTimerRef.current) {
             clearTimeout(renderTimerRef.current);
         }
-
-        // Debounce: wait 500ms after last update
-        renderTimerRef.current = setTimeout(() => {
-            renderChart();
-        }, 500);
+        renderTimerRef.current = setTimeout(renderChart, debounceMs);
 
         return () => {
+            // Invalidate any in-flight async render from this effect run.
+            renderSeqRef.current++;
             if (renderTimerRef.current) {
                 clearTimeout(renderTimerRef.current);
+                renderTimerRef.current = null;
             }
         };
-    }, [chart, theme, isCompact, isMermaidCodeComplete, cleanupMermaidErrors]);
+    }, [chart, theme, isCompact, debounceMs, isMermaidCodeComplete, cleanupMermaidErrors]);
 
-    return {
-        mermaidRef,
-        svgContent,
-        isVertical,
-        isRendering,
-    };
+    return { mermaidRef, svgContent, isVertical, isRendering, error };
 }

package/src/tools/Mermaid/hooks/useMermaidValidation.ts

@@ -1,28 +1,94 @@
 /**
- * Hook for validating Mermaid code completeness
+ * Hook for validating Mermaid code completeness.
+ *
+ * Purpose: while a diagram is being *streamed* (token by token from an
+ * LLM, or typed) the source is briefly invalid. Rendering it would throw
+ * a parse error and flash an error panel on every keystroke. This
+ * heuristic detects "obviously still-being-written" source so the
+ * renderer can wait instead. It is intentionally conservative — false
+ * "complete" is fine (the real parser catches it), false "incomplete"
+ * just delays a render.
  */
 
 import { useCallback } from 'react';
 
+/** Diagram keywords that, alone, are a valid first line. */
+const DIAGRAM_KEYWORDS = [
+    'graph',
+    'flowchart',
+    'sequenceDiagram',
+    'classDiagram',
+    'stateDiagram',
+    'stateDiagram-v2',
+    'erDiagram',
+    'journey',
+    'gantt',
+    'pie',
+    'mindmap',
+    'timeline',
+    'gitGraph',
+    'quadrantChart',
+    'requirementDiagram',
+    'C4Context',
+    'sankey-beta',
+    'xychart-beta',
+    'block-beta',
+];
+
+/** Count occurrences of a character that are not inside a quoted string. */
+function countUnquoted(text: string, open: string, close: string): number {
+    let depth = 0;
+    let inQuote = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '"') {
+            inQuote = !inQuote;
+            continue;
+        }
+        if (inQuote) continue;
+        if (ch === open) depth++;
+        else if (ch === close) depth--;
+    }
+    return depth;
+}
+
 export function useMermaidValidation() {
     const isMermaidCodeComplete = useCallback((code: string): boolean => {
         if (!code || code.trim().length === 0) return false;
 
         const trimmed = code.trim();
 
-        // Check if code has basic structure
-        const lines = trimmed.split('\n');
-        if (lines.length < 2) return false; // Need at least diagram type + one element
+        // Must start with a recognised diagram keyword. During streaming
+        // the very first tokens may be a partial keyword — wait for it.
+        const firstToken = trimmed.split(/[\s\n;]/)[0] ?? '';
+        const hasKnownType = DIAGRAM_KEYWORDS.some(
+            (kw) => firstToken === kw || trimmed.startsWith(kw),
+        );
+        if (!hasKnownType) return false;
 
-        // Check for common incomplete patterns
+        const lines = trimmed.split('\n');
         const lastLine = (lines[lines.length - 1] ?? '').trim();
 
-        // Incomplete if last line ends with arrow without destination
-        if (lastLine.match(/-->?\s*$/)) return false;
-        if (lastLine.match(/-->\|[^|]*\|\s*$/)) return false;
+        // Trailing edge with no destination: `A -->` / `A --` / `A -.->`.
+        if (/(-{1,3}>?|={1,3}>?|-\.->?|\.\.>?|--[ox])\s*$/.test(lastLine)) {
+            return false;
+        }
+        // Trailing edge label still open: `A -->|label` (no closing `|`).
+        if (/-{1,3}>?\s*\|[^|]*$/.test(lastLine)) return false;
+
+        // Unbalanced shape brackets across the whole source (open > close).
+        if (countUnquoted(trimmed, '[', ']') > 0) return false;
+        if (countUnquoted(trimmed, '(', ')') > 0) return false;
+        // ER diagrams use `{` / `}` for crow's-foot cardinality
+        // (`||--o{`, `}|--||`) — those braces are deliberately unbalanced
+        // and must not be counted, or the diagram never renders.
+        if (!trimmed.startsWith('erDiagram') && countUnquoted(trimmed, '{', '}') > 0) {
+            return false;
+        }
 
-        // Incomplete if last line ends with opening bracket/parenthesis
-        if (lastLine.match(/[\[({]\s*$/)) return false;
+        // Odd number of double quotes — an unterminated string literal.
+        const quoteCount = (trimmed.match(/"/g) ?? []).length;
+        if (quoteCount % 2 !== 0) return false;
 
         return true;
     }, []);

package/src/tools/Mermaid/index.tsx

@@ -32,6 +32,12 @@ export interface MermaidProps {
    * Mermaid.client implementation for the full rationale.
    */
   scrollIsolation?: boolean;
+  /**
+   * Debounce window (ms) before (re)rendering after `chart` changes.
+   * Lower feels snappier for static charts; higher reduces churn while
+   * a diagram is streamed in. Default 300.
+   */
+  debounceMs?: number;
 }
 
 const Mermaid: React.FC<MermaidProps> = (props) => {