@graph-artifact/core 0.1.7 → 0.1.10

package/dist/ThemeContext.d.ts

@@ -2,6 +2,8 @@ import type { ReactNode } from 'react';
 import type { ThemeOverride } from './types.js';
 import type { ThemeTokens } from './theme/index.js';
 export interface Theme {
+    /** Theme mode used for host integration (React Flow colorMode, etc.). */
+    mode: 'dark' | 'light';
     color: Record<string, string>;
     font: {
         family: string;
@@ -39,9 +41,11 @@ export interface Theme {
 }
 export declare const defaultTheme: Theme;
 interface ThemeProviderProps {
+    /** Override the base theme used ('dark' | 'light' | custom registered theme). */
+    baseTheme?: string;
     overrides?: ThemeOverride;
     children: ReactNode;
 }
-export declare function ThemeProvider({ overrides, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ThemeProvider({ baseTheme, overrides, children }: ThemeProviderProps): import("react/jsx-runtime").JSX.Element;
 export declare function useTheme(): Theme;
 export {};

package/dist/ThemeContext.js

@@ -5,6 +5,8 @@ import { getThemeTokens } from './theme/index.js';
 // ─── Build Theme from Tokens ──────────────────────────────────────────────────
 function buildTheme(tokens) {
     return {
+        // Most consumers only ship dark + light. Treat unknown themes as dark by default.
+        mode: tokens.color.darkBg2 === '#ffffff' ? 'light' : 'dark',
         color: { ...tokens.color },
         font: {
             family: tokens.font.family,
@@ -72,8 +74,21 @@ function resolveTheme(instanceOverrides) {
 }
 // ─── Context & Provider ───────────────────────────────────────────────────────
 const ThemeContext = createContext(defaultTheme);
-export function ThemeProvider({ overrides, children }) {
-    const theme = useMemo(() => resolveTheme(overrides), [overrides]);
+export function ThemeProvider({ baseTheme, overrides, children }) {
+    const theme = useMemo(() => {
+        if (!baseTheme)
+            return resolveTheme(overrides);
+        const tokens = getThemeTokens(baseTheme);
+        let resolved = buildTheme(tokens);
+        const { theme: configOverrides } = getConfig();
+        if (configOverrides && Object.keys(configOverrides).length > 0) {
+            resolved = deepMerge(resolved, configOverrides);
+        }
+        if (overrides && Object.keys(overrides).length > 0) {
+            resolved = deepMerge(resolved, overrides);
+        }
+        return resolved;
+    }, [baseTheme, overrides]);
     return _jsx(ThemeContext.Provider, { value: theme, children: children });
 }
 export function useTheme() {

package/dist/components/DiagramCanvas.d.ts

@@ -6,6 +6,8 @@ interface DiagramCanvasProps {
     onNodeClick: (nodeId: string, nodeLabel: string) => void;
     canvasOverrides?: Partial<GraphConfig['canvas']>;
     hideAttribution?: boolean;
+    relayoutOnMeasure?: boolean;
+    onLayoutStable?: () => void;
 }
-export declare function DiagramCanvas({ parsed, metadata, onNodeClick, canvasOverrides, hideAttribution }: DiagramCanvasProps): import("react/jsx-runtime").JSX.Element;
+export declare function DiagramCanvas({ parsed, metadata, onNodeClick, canvasOverrides, hideAttribution, relayoutOnMeasure, onLayoutStable }: DiagramCanvasProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/DiagramCanvas.js

@@ -11,9 +11,9 @@ function UnsupportedCustomDiagram({ parsed }) {
             fontSize: 14,
         }, children: `Diagram type '${parsed.diagramType}' is detected but custom rendering is not implemented yet.` }));
 }
-export function DiagramCanvas({ parsed, metadata, onNodeClick, canvasOverrides, hideAttribution }) {
+export function DiagramCanvas({ parsed, metadata, onNodeClick, canvasOverrides, hideAttribution, relayoutOnMeasure, onLayoutStable }) {
     if (parsed.kind === 'graph') {
-        return (_jsx(GraphCanvas, { parsed: parsed, metadata: metadata, onNodeClick: onNodeClick, canvasOverrides: canvasOverrides, hideAttribution: hideAttribution }));
+        return (_jsx(GraphCanvas, { parsed: parsed, metadata: metadata, onNodeClick: onNodeClick, canvasOverrides: canvasOverrides, hideAttribution: hideAttribution, relayoutOnMeasure: relayoutOnMeasure, onLayoutStable: onLayoutStable }));
     }
     return _jsx(UnsupportedCustomDiagram, { parsed: parsed });
 }

package/dist/components/GraphCanvas.d.ts

@@ -7,6 +7,16 @@ interface GraphCanvasProps {
     onNodeClick: (nodeId: string, nodeLabel: string) => void;
     canvasOverrides?: Partial<GraphConfig['canvas']>;
     hideAttribution?: boolean;
+    /**
+     * If true, reruns dagre after React Flow measures node DOM sizes so
+     * layout reflects actual rendered content (auto-sized text/markdown).
+     */
+    relayoutOnMeasure?: boolean;
+    /**
+     * Called once when layout is stable and fitView has been applied (if enabled).
+     * Useful for host apps that need to know when the diagram is "ready".
+     */
+    onLayoutStable?: () => void;
 }
 export declare function GraphCanvas(props: GraphCanvasProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/GraphCanvas.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useCallback, useState, useEffect, useRef } from 'react';
-import { ReactFlow, Background, Controls, MiniMap, ReactFlowProvider, useNodesInitialized, useStore, useStoreApi, } from '@xyflow/react';
+import { ReactFlow, Background, Controls, MiniMap, ReactFlowProvider, useReactFlow, useNodesInitialized, useStore, useStoreApi, } from '@xyflow/react';
 import '@xyflow/react/dist/style.css';
 import { layoutNodes, buildLayoutEdges } from '../layout/index.js';
 import { getConfig, getNodeTypes } from '../config.js';
@@ -8,12 +8,13 @@ import { useTheme } from '../ThemeContext.js';
 import { RoutedEdge } from './edges/RoutedEdge.js';
 // Stable reference — must be outside the component to avoid infinite re-renders
 const edgeTypes = { routed: RoutedEdge };
-function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hideAttribution }) {
+function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hideAttribution, relayoutOnMeasure, onLayoutStable, }) {
     const theme = useTheme();
     const { canvas: baseCanvas } = getConfig();
     const canvas = useMemo(() => ({ ...baseCanvas, ...(canvasOverrides ?? {}) }), [baseCanvas, canvasOverrides]);
     const resolvedNodeTypes = getNodeTypes();
     const storeApi = useStoreApi();
+    const reactFlow = useReactFlow();
     const nodesInitialized = useNodesInitialized();
     const measuredSignature = useStore((s) => Array.from(s.nodeLookup.values()).reduce((hash, n) => {
         const w = Math.round(n.measured?.width ?? n.width ?? 0);
@@ -26,8 +27,15 @@ function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hide
         hash = ((hash << 5) - hash + h) | 0;
         return hash;
     }, 0));
-    // Phase 1: Layout nodes with dagre + initial edges with estimated dimensions
-    const layoutState = useMemo(() => {
+    const defaultRelayout = parsed.diagramType === 'flowchart' ||
+        parsed.diagramType === 'er' ||
+        parsed.diagramType === 'class' ||
+        parsed.diagramType === 'gitGraph';
+    const shouldRelayoutOnMeasure = Boolean(relayoutOnMeasure ?? defaultRelayout) &&
+        parsed.diagramType !== 'sequence' &&
+        parsed.diagramType !== 'mindmap';
+    // Initial layout (dagre estimates).
+    const initialLayoutState = useMemo(() => {
         try {
             return {
                 result: layoutNodes(parsed, { theme, metadata }),
@@ -39,21 +47,134 @@ function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hide
             return { result: null, error: message };
         }
     }, [parsed, theme, metadata]);
-    const layoutResult = layoutState.result;
-    const nodes = layoutResult?.nodes ?? [];
-    const context = layoutResult?.context ?? undefined;
-    // Edges with estimated dimensions — always available immediately
-    const estimatedEdges = useMemo(() => context
-        ? buildLayoutEdges(context, theme)
-        : (layoutResult?.edges ?? []), [context, theme, layoutResult]);
-    // Start with estimated edges so something is always visible
-    const [edges, setEdges] = useState(estimatedEdges);
+    const [layoutError, setLayoutError] = useState(initialLayoutState.error);
+    const [nodes, setNodes] = useState(initialLayoutState.result?.nodes ?? []);
+    const [context, setContext] = useState(initialLayoutState.result?.context ?? undefined);
+    const [edges, setEdges] = useState(() => {
+        const r = initialLayoutState.result;
+        const c = r?.context ?? undefined;
+        return c
+            ? buildLayoutEdges(c, theme)
+            : (r?.edges ?? []);
+    });
     const contextRef = useRef(context);
     contextRef.current = context;
-    // When diagram changes, immediately show estimated edges
+    // Apply fitView once per diagram after node measurement stabilizes.
+    const didInitialFit = useRef(false);
+    const didStableCallback = useRef(false);
     useEffect(() => {
-        setEdges(estimatedEdges);
-    }, [estimatedEdges]);
+        didInitialFit.current = false;
+        didStableCallback.current = false;
+    }, [parsed]);
+    useEffect(() => {
+        if (!nodesInitialized)
+            return;
+        if (layoutError)
+            return;
+        if (nodes.length === 0)
+            return;
+        // Wait until after relayout pass completes (if enabled).
+        if (shouldRelayoutOnMeasure && relayoutPass.current > 0 && relayoutPass.current < 2) {
+            // allow another pass to settle
+        }
+        // Always try to fitView once if enabled; React Flow's declarative fitView
+        // runs early and can miss when sizes change post-measurement.
+        if (canvas.fitView && !didInitialFit.current) {
+            didInitialFit.current = true;
+            // Double rAF to ensure DOM + measured sizes are committed.
+            requestAnimationFrame(() => {
+                requestAnimationFrame(() => {
+                    try {
+                        reactFlow.fitView({ padding: 0.2, maxZoom: 1, duration: 250 });
+                    }
+                    catch {
+                        // ignore fitView errors (unmounted / not ready)
+                    }
+                });
+            });
+        }
+        if (onLayoutStable && !didStableCallback.current) {
+            didStableCallback.current = true;
+            onLayoutStable();
+        }
+    }, [
+        nodesInitialized,
+        measuredSignature,
+        layoutError,
+        nodes.length,
+        canvas.fitView,
+        reactFlow,
+        onLayoutStable,
+        shouldRelayoutOnMeasure,
+    ]);
+    // Reset to initial layout when input diagram changes.
+    useEffect(() => {
+        setLayoutError(initialLayoutState.error);
+        if (!initialLayoutState.result) {
+            setNodes([]);
+            setContext(undefined);
+            setEdges([]);
+            return;
+        }
+        const r = initialLayoutState.result;
+        const c = r.context ?? undefined;
+        setNodes(r.nodes);
+        setContext(c);
+        setEdges(c ? buildLayoutEdges(c, theme) : (r.edges ?? []));
+    }, [initialLayoutState, theme]);
+    // If we enable measured relayout, allow a couple of passes until stable.
+    const relayoutPass = useRef(0);
+    useEffect(() => {
+        relayoutPass.current = 0;
+    }, [parsed, theme, metadata, shouldRelayoutOnMeasure]);
+    useEffect(() => {
+        if (!shouldRelayoutOnMeasure)
+            return;
+        if (!nodesInitialized || !contextRef.current)
+            return;
+        if (relayoutPass.current >= 2)
+            return;
+        const nodeLookup = storeApi.getState().nodeLookup;
+        const overrides = new Map();
+        let anyDiff = false;
+        for (const internalNode of nodeLookup.values()) {
+            const estimated = contextRef.current.estimatedPositions.get(internalNode.id);
+            if (!estimated)
+                continue; // ignore subgraph containers and unknown nodes
+            const measuredW = internalNode.measured?.width ?? internalNode.width ?? estimated.width;
+            const measuredH = internalNode.measured?.height ?? internalNode.height ?? estimated.height;
+            if (!Number.isFinite(measuredW) || !Number.isFinite(measuredH) || measuredW <= 0 || measuredH <= 0)
+                continue;
+            overrides.set(internalNode.id, { width: measuredW, height: measuredH });
+            if (Math.abs(measuredW - estimated.width) > 2 || Math.abs(measuredH - estimated.height) > 2) {
+                anyDiff = true;
+            }
+        }
+        if (!anyDiff)
+            return;
+        try {
+            const next = layoutNodes(parsed, { theme, metadata }, overrides);
+            if (!next.context)
+                return; // sequence/custom returns edges directly
+            relayoutPass.current += 1;
+            setNodes(next.nodes);
+            setContext(next.context);
+            setEdges(buildLayoutEdges(next.context, theme));
+            setLayoutError(null);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            setLayoutError(message);
+        }
+    }, [
+        shouldRelayoutOnMeasure,
+        nodesInitialized,
+        measuredSignature,
+        parsed,
+        theme,
+        metadata,
+        storeApi,
+    ]);
     // Phase 2: Recompute when React Flow measurements change so intersections
     // always use actual rendered node dimensions.
     useEffect(() => {
@@ -61,12 +182,13 @@ function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hide
             return;
         const nodeLookup = storeApi.getState().nodeLookup;
         const measuredPositions = new Map();
+        const subgraphIds = new Set((parsed.subgraphs ?? []).map((s) => s.id));
         for (const internalNode of nodeLookup.values()) {
             const estimated = contextRef.current.estimatedPositions.get(internalNode.id);
-            if (!estimated)
+            if (!estimated && !subgraphIds.has(internalNode.id))
                 continue;
-            const measuredW = internalNode.measured?.width ?? internalNode.width ?? estimated.width;
-            const measuredH = internalNode.measured?.height ?? internalNode.height ?? estimated.height;
+            const measuredW = internalNode.measured?.width ?? internalNode.width ?? estimated?.width ?? 0;
+            const measuredH = internalNode.measured?.height ?? internalNode.height ?? estimated?.height ?? 0;
             const abs = internalNode.internals.positionAbsolute;
             measuredPositions.set(internalNode.id, {
                 x: abs.x,
@@ -77,6 +199,64 @@ function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hide
         }
         setEdges(buildLayoutEdges(contextRef.current, theme, measuredPositions));
     }, [nodesInitialized, measuredSignature, theme, storeApi]);
+    // Subgraph boxes are visual annotations; compute their bounds from measured
+    // child node DOM dimensions so they never drift due to sizing changes.
+    useEffect(() => {
+        if (!nodesInitialized)
+            return;
+        if (!parsed.subgraphs || parsed.subgraphs.length === 0)
+            return;
+        const { layout } = getConfig();
+        const nodeLookup = storeApi.getState().nodeLookup;
+        // Include extra pad so node shadows/rounded corners don't peek outside.
+        // We intentionally over-pad here; subgraphs are visual groupings, not tight boxes.
+        const pad = layout.subgraphPadding + 16;
+        const labelOffset = theme.nodeStyles.subgraph.labelOffset;
+        const boundsById = new Map();
+        for (const sg of parsed.subgraphs) {
+            let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+            for (const nid of sg.nodeIds) {
+                const internal = nodeLookup.get(nid);
+                if (!internal)
+                    continue;
+                const abs = internal.internals.positionAbsolute;
+                const w = internal.measured?.width ?? internal.width ?? 0;
+                const h = internal.measured?.height ?? internal.height ?? 0;
+                if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0)
+                    continue;
+                minX = Math.min(minX, abs.x);
+                minY = Math.min(minY, abs.y);
+                maxX = Math.max(maxX, abs.x + w);
+                maxY = Math.max(maxY, abs.y + h);
+            }
+            if (!isFinite(minX))
+                continue;
+            const next = {
+                x: minX - pad,
+                y: minY - pad - labelOffset,
+                width: maxX - minX + pad * 2,
+                height: maxY - minY + pad * 2 + labelOffset,
+            };
+            boundsById.set(sg.id, next);
+        }
+        if (boundsById.size === 0)
+            return;
+        setNodes((prev) => prev.map((n) => {
+            const b = boundsById.get(n.id);
+            if (b) {
+                return {
+                    ...n,
+                    position: { x: b.x, y: b.y },
+                    style: {
+                        ...(n.style ?? {}),
+                        width: b.width,
+                        height: b.height,
+                    },
+                };
+            }
+            return n;
+        }));
+    }, [nodesInitialized, measuredSignature, parsed.subgraphs, storeApi, theme.nodeStyles.subgraph.labelOffset]);
     const handleNodeClick = useCallback((_event, node) => {
         const label = String(node.data?.label ?? node.id);
         onNodeClick(node.id, label);
@@ -84,7 +264,7 @@ function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hide
     const defaultEdgeOptions = useMemo(() => ({ animated: false, style: theme.edgeDefaults.style }), [theme.edgeDefaults.style]);
     const miniMapNodeColor = useCallback(() => theme.color.orange1, [theme.color.orange1]);
     const miniMapMaskColor = useMemo(() => `${theme.color.gray1}cc`, [theme.color.gray1]);
-    if (layoutState.error || !layoutState.result) {
+    if (layoutError) {
         return (_jsx("div", { style: {
                 width: '100%',
                 height: '100%',
@@ -96,9 +276,26 @@ function GraphCanvasInner({ parsed, metadata, onNodeClick, canvasOverrides, hide
                 fontFamily: theme.font.family,
                 fontSize: 13,
                 textAlign: 'center',
-            }, children: `Diagram syntax/layout error: ${layoutState.error ?? 'Unknown layout failure'}` }));
+            }, children: `Diagram syntax/layout error: ${layoutError}` }));
     }
-    return (_jsx("div", { style: { width: '100%', height: '100%' }, children: _jsxs(ReactFlow, { nodes: nodes, edges: edges, nodeTypes: resolvedNodeTypes, edgeTypes: edgeTypes, onNodeClick: handleNodeClick, fitView: canvas.fitView, minZoom: canvas.minZoom, maxZoom: canvas.maxZoom, defaultEdgeOptions: defaultEdgeOptions, proOptions: hideAttribution ? { hideAttribution: true } : undefined, children: [canvas.showBackground && (_jsx(Background, { color: theme.color.gray2, gap: canvas.backgroundGap, size: canvas.backgroundSize })), canvas.showControls && _jsx(Controls, {}), canvas.showMiniMap && (_jsx(MiniMap, { nodeColor: miniMapNodeColor, maskColor: miniMapMaskColor }))] }) }));
+    return (_jsxs("div", { style: { width: '100%', height: '100%' }, children: [_jsx("style", { children: `
+        /* Theme React Flow chrome (controls/minimap) to match our tokens. */
+        .react-flow__controls-button {
+          background: ${theme.mode === 'dark' ? theme.color.darkBg3 : theme.color.white};
+          color: ${theme.mode === 'dark' ? theme.color.gray4 : theme.color.gray4};
+          border: 1px solid ${theme.color.gray2};
+        }
+        .react-flow__controls-button:hover {
+          background: ${theme.mode === 'dark' ? theme.color.gray1 : theme.color.gray1};
+        }
+        .react-flow__controls-button svg {
+          fill: currentColor;
+        }
+        .react-flow__minimap {
+          background: ${theme.mode === 'dark' ? theme.color.darkBg2 : theme.color.white};
+          border: 1px solid ${theme.color.gray2};
+        }
+      ` }), _jsxs(ReactFlow, { nodes: nodes, edges: edges, nodeTypes: resolvedNodeTypes, edgeTypes: edgeTypes, onNodeClick: handleNodeClick, fitView: canvas.fitView, minZoom: canvas.minZoom, maxZoom: canvas.maxZoom, defaultEdgeOptions: defaultEdgeOptions, zIndexMode: "manual", colorMode: theme.mode, proOptions: hideAttribution ? { hideAttribution: true } : undefined, children: [canvas.showBackground && (_jsx(Background, { color: theme.color.gray2, gap: canvas.backgroundGap, size: canvas.backgroundSize })), canvas.showControls && _jsx(Controls, {}), canvas.showMiniMap && (_jsx(MiniMap, { nodeColor: miniMapNodeColor, maskColor: miniMapMaskColor }))] })] }));
 }
 export function GraphCanvas(props) {
     return (_jsx(ReactFlowProvider, { children: _jsx(GraphCanvasInner, { ...props }) }));

package/dist/components/nodes/FlowNode.js

@@ -37,12 +37,9 @@ function htmlSubsetToMarkdown(src) {
 }
 function normalizeLabelMarkdown(label) {
     // Mermaid treats "\n" inside labels as a hard line break.
-    // react-markdown doesn't always preserve raw newlines, so force
-    // CommonMark hard-breaks by adding two trailing spaces.
     return htmlSubsetToMarkdown(label)
         .replace(/\\n/g, '\n')
-        .trim()
-        .replace(/\n/g, '  \n');
+        .trim();
 }
 /**
  * Generates evenly-spaced handle positions across a face.
@@ -161,13 +158,19 @@ export const FlowNode = memo(function FlowNode({ data }) {
     return (_jsxs("div", { style: {
             backgroundColor: nodeBgColor, borderRadius: br,
             padding: `${theme.space[3]} ${theme.space[5]}`,
-            width: layoutWidth, height: layoutHeight,
+            width: layoutWidth,
+            // Allow content-driven height. Dagre supplies an initial estimate;
+            // GraphCanvas can relayout using measured dimensions.
+            minHeight: layoutHeight,
             boxSizing: 'border-box',
             display: 'flex', alignItems: 'center', justifyContent: 'center',
             fontFamily: theme.font.family, cursor: 'pointer',
         }, children: [_jsx("div", { style: {
                     color: nodeTextColor, fontSize: theme.font.size.lg, fontWeight: theme.font.weight.bold,
                     textAlign: 'center', lineHeight: theme.lineHeight.normal,
-                    whiteSpace: 'normal', overflowWrap: 'break-word', width: '100%',
+                    whiteSpace: 'normal',
+                    overflowWrap: 'anywhere',
+                    wordBreak: 'break-word',
+                    width: '100%',
                 }, children: _jsx(ReactMarkdown, { components: markdownComponents, children: labelMarkdown }) }), ChildComponent && (_jsx(ChildComponent, { nodeId: String(data.id ?? ''), label: label, componentProps: meta?.componentProps })), _jsx(NodeHandles, { fwIn: fwIn, fwOut: fwOut })] }));
 });

package/dist/components/nodes/SequenceNodes.js

@@ -80,7 +80,7 @@ export const SequenceNoteNode = memo(function SequenceNoteNode({ data }) {
     const ns = theme.nodeStyles.sequence;
     return (_jsx("div", { style: {
             width: w,
-            backgroundColor: theme.color.darkBg3,
+            backgroundColor: ns.note.backgroundColor,
             border: `${ns.note.borderWidth} solid ${theme.color.gray2}`,
             borderRadius: theme.radius.sm,
             display: 'flex',
@@ -90,7 +90,7 @@ export const SequenceNoteNode = memo(function SequenceNoteNode({ data }) {
             pointerEvents: 'none',
             boxSizing: 'border-box',
         }, children: _jsx("span", { style: {
-                color: theme.color.gray4,
+                color: ns.note.textColor,
                 fontSize: theme.font.size.sm,
                 fontFamily: theme.font.family,
                 textAlign: 'center',

package/dist/components/nodes/StateNode.js

@@ -38,7 +38,7 @@ export const StateNode = memo(function StateNode({ data }) {
     if (shape === 'circle') {
         return (_jsx("div", { style: {
                 width: layoutWidth, height: layoutHeight,
-                backgroundColor: theme.color.gray5, borderRadius: theme.radius.full,
+                backgroundColor: theme.color.orange1, borderRadius: theme.radius.full,
             }, children: _jsx(StateHandles, { fwIn: fwIn, fwOut: fwOut }) }));
     }
     // End state: bullseye (outer ring + inner filled dot).
@@ -49,23 +49,26 @@ export const StateNode = memo(function StateNode({ data }) {
                 width: layoutWidth, height: layoutHeight,
                 boxSizing: 'border-box',
                 borderRadius: theme.radius.full,
-                border: `${theme.borderWidth.md} solid ${theme.color.gray5}`,
+                border: `${theme.borderWidth.md} solid ${theme.color.orange1}`,
                 display: 'flex', alignItems: 'center', justifyContent: 'center',
             }, children: [_jsx("div", { style: {
                         width: innerSize, height: innerSize,
-                        backgroundColor: theme.color.gray5, borderRadius: theme.radius.full,
+                        // Inner fill: dark in dark mode, dark gray in light mode.
+                        backgroundColor: theme.mode === 'dark' ? theme.color.darkBg2 : theme.color.gray5,
+                        borderRadius: theme.radius.full,
                     } }), _jsx(StateHandles, { fwIn: fwIn, fwOut: fwOut })] }));
     }
     return (_jsxs("div", { style: {
-            backgroundColor: theme.color.darkBg2, border: `${theme.borderWidth.sm} solid ${theme.color.gray2}`,
-            borderLeft: `${ns.rect.accentWidth} solid ${theme.color.orange1}`, borderRadius: theme.radius.pill,
+            backgroundColor: theme.color.orange1,
+            border: `${theme.borderWidth.sm} solid ${theme.color.orange3}`,
+            borderRadius: theme.radius.pill,
             padding: `${theme.space[3]} ${theme.space[6]}`,
             width: layoutWidth, height: layoutHeight,
             boxSizing: 'border-box',
             fontFamily: theme.font.family, cursor: 'pointer',
             display: 'flex', alignItems: 'center', justifyContent: 'center',
         }, children: [_jsx("div", { style: {
-                    color: theme.color.gray5, fontSize: theme.font.size.lg, fontWeight: theme.font.weight.semibold,
+                    color: theme.color.white, fontSize: theme.font.size.lg, fontWeight: theme.font.weight.semibold,
                     textAlign: 'center', whiteSpace: 'nowrap',
                 }, children: label }), _jsx(StateHandles, { fwIn: fwIn, fwOut: fwOut })] }));
 });

package/dist/config.js

@@ -63,12 +63,15 @@ function createDefaultConfig() {
             },
         },
         canvas: {
-            minZoom: 0.1,
+            // Allow fitView to zoom out far enough for large diagrams.
+            minZoom: 0.02,
             maxZoom: 2,
             fitView: true,
             showBackground: true,
             showControls: true,
-            showMiniMap: true,
+            // MiniMap is useful in dedicated viewers but noisy in embedded contexts (chat, docs).
+            // Host apps can enable it via `canvasOverrides`.
+            showMiniMap: false,
             backgroundGap: 20,
             backgroundSize: 1,
         },

package/dist/layout/dagre/index.d.ts

@@ -18,7 +18,10 @@ export type { NodePosition, HandlePositions, EdgeWaypoints } from '../types.js';
  * Back-edges route to side handles to avoid passing through intermediate nodes.
  */
 export declare function directionToHandles(direction: ParsedGraph['direction']): HandlePositions;
-export declare function createDagreGraph(parsed: ParsedGraph, layoutConfig: GraphConfig['layout']): dagre.graphlib.Graph;
+export declare function createDagreGraph(parsed: ParsedGraph, layoutConfig: GraphConfig['layout'], nodeSizeOverrides?: Map<string, {
+    width: number;
+    height: number;
+}>): dagre.graphlib.Graph;
 /**
  * Extracts top-left positions from dagre's center-based coordinates.
  * Returns a Map of nodeId → { x, y, width, height }.

package/dist/layout/dagre/index.js

@@ -50,7 +50,7 @@ export function directionToHandles(direction) {
     }
 }
 // ─── Dagre Graph Construction ───────────────────────────────────────────────
-export function createDagreGraph(parsed, layoutConfig) {
+export function createDagreGraph(parsed, layoutConfig, nodeSizeOverrides) {
     validateParsedGraph(parsed);
     const g = new dagre.graphlib.Graph({ multigraph: true, compound: true });
     g.setDefaultEdgeLabel(() => ({}));
@@ -81,7 +81,8 @@ export function createDagreGraph(parsed, layoutConfig) {
         ranker: 'network-simplex',
     });
     for (const node of parsed.nodes) {
-        const size = nodeSize(node, parsed.diagramType, layoutConfig.nodeSizing);
+        const override = nodeSizeOverrides?.get(node.id);
+        const size = override ?? nodeSize(node, parsed.diagramType, layoutConfig.nodeSizing);
         g.setNode(node.id, { width: size.width, height: size.height });
     }
     // Defensive: if a parser emits an edge endpoint that is missing from

package/dist/layout/edges/buildEdges.js

@@ -118,8 +118,8 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
     const forwardBySource = new Map();
     const forwardByTarget = new Map();
     parsedEdges.forEach((edge, i) => {
-        const sp = positions.get(edge.source);
-        const tp = positions.get(edge.target);
+        const sp = positions.get(edge.sourceSubgraphId ?? edge.source);
+        const tp = positions.get(edge.targetSubgraphId ?? edge.target);
         if (!sp || !tp)
             return;
         const edgeClass = classifyEdge(sp, tp, direction);
@@ -149,14 +149,14 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
     const backSourceCounters = new Map();
     const backTargetCounters = new Map();
     return parsedEdges.map((edge, i) => {
-        const sourcePos = positions.get(edge.source);
-        const targetPos = positions.get(edge.target);
+        const sourcePos = positions.get(edge.sourceSubgraphId ?? edge.source);
+        const targetPos = positions.get(edge.targetSubgraphId ?? edge.target);
         const edgeClass = sourcePos && targetPos
             ? classifyEdge(sourcePos, targetPos, direction)
             : 'forward';
         const waypoints = edgeWaypoints?.[i];
-        const sourceShape = nodeShapes?.get(edge.source) ?? 'rect';
-        const targetShape = nodeShapes?.get(edge.target) ?? 'rect';
+        const sourceShape = edge.sourceSubgraphId ? 'rect' : (nodeShapes?.get(edge.source) ?? 'rect');
+        const targetShape = edge.targetSubgraphId ? 'rect' : (nodeShapes?.get(edge.target) ?? 'rect');
         // ── Compute path from dagre waypoints ──
         let svgPath = '';
         let labelPos = { x: 0, y: 0 };
@@ -371,7 +371,9 @@ export function buildEdges(parsedEdges, positions, _handles, direction, theme, d
             labelBgBorderRadius: theme.edgeDefaults.labelBgBorderRadius,
             sourceHandle,
             targetHandle,
-            zIndex: isErEdge ? 2 : (edgeClass === 'back' ? 0 : 1),
+            // Keep edges above subgraph backgrounds but below regular nodes.
+            // (Regular nodes set zIndex=10; subgraphs set zIndex=0.)
+            zIndex: 1,
             data: {
                 svgPath,
                 labelX: labelPos.x,

package/dist/layout/index.d.ts

@@ -43,7 +43,10 @@ export interface CustomLayoutResult {
     data: ParsedCustomDiagram['data'];
 }
 export type LayoutResult = GraphLayoutResult | CustomLayoutResult;
-export declare function layoutNodes(parsed: ParsedGraph, options: LayoutOptions): {
+export declare function layoutNodes(parsed: ParsedGraph, options: LayoutOptions, nodeSizeOverrides?: Map<string, {
+    width: number;
+    height: number;
+}>): {
     nodes: Node[];
     context: LayoutContext;
 } | {

package/dist/layout/index.js

@@ -21,7 +21,7 @@ import { computeSubgraphBounds, buildSubgraphNode } from './subgraph.js';
 import { layoutSequenceDiagram } from './sequenceLayout.js';
 import { layoutMindmapGraph } from './mindmapLayout.js';
 // ─── Phase 1: Layout Nodes ──────────────────────────────────────────────────
-export function layoutNodes(parsed, options) {
+export function layoutNodes(parsed, options, nodeSizeOverrides) {
     const { theme, metadata } = options;
     // Mindmap uses dedicated radial layout (not dagre).
     if (parsed.diagramType === 'mindmap') {
@@ -46,7 +46,7 @@ export function layoutNodes(parsed, options) {
     }
     const { layout } = getConfig();
     // 1. Build dagre graph and run layout
-    const graph = createDagreGraph(parsed, layout);
+    const graph = createDagreGraph(parsed, layout, nodeSizeOverrides);
     // 2. Extract positioned coordinates and edge waypoints
     const positions = extractPositions(graph, parsed.nodes);
     const edgeWaypoints = extractEdgeWaypoints(graph, parsed);
@@ -62,6 +62,7 @@ export function layoutNodes(parsed, options) {
         return {
             id: node.id,
             position: { x: pos.x, y: pos.y },
+            zIndex: 10,
             data: {
                 label: node.label,
                 shape: node.shape,
@@ -85,6 +86,14 @@ export function layoutNodes(parsed, options) {
             const bounds = computeSubgraphBounds(subgraph, positions, layout.subgraphPadding, theme.nodeStyles.subgraph.labelOffset, graph);
             if (!bounds)
                 continue;
+            // Make subgraph bounds available to the edge builder so edges that
+            // reference a subgraph id can attach to the subgraph boundary.
+            positions.set(subgraph.id, {
+                x: bounds.x,
+                y: bounds.y,
+                width: bounds.width,
+                height: bounds.height,
+            });
             nodes.unshift(buildSubgraphNode(subgraph, bounds, theme));
         }
     }

package/dist/layout/sequenceLayout.js

@@ -17,6 +17,7 @@
  */
 import { MarkerType } from '@xyflow/react';
 import { getConfig } from '../config.js';
+import { generateRoundedPath } from './edges/paths.js';
 // ─── Layout Constants ──────────────────────────────────────────────────────
 const PARTICIPANT_WIDTH = 150;
 const PARTICIPANT_HEIGHT = 40;
@@ -291,12 +292,11 @@ export function layoutSequenceDiagram(sequence, theme, metadata) {
             selectable: false,
         });
         if (isSelf) {
-            const loopRightX = participantCenterX(fromIdx, seq.leftPadding, seq.participantWidth, seq.participantGap) + 40;
+            const loopWidth = 44;
+            const loopRightX = participantCenterX(fromIdx, seq.leftPadding, seq.participantWidth, seq.participantGap) + loopWidth;
             const loopBottomY = y + seq.selfMessageExtra + 10;
-            const cornerAnchorId = `__anchor_${msg.from}_${mi}_corner`;
             const returnAnchorId = `__anchor_${msg.from}_${mi}_return`;
-            const cornerBottomId = `__anchor_${msg.from}_${mi}_cornerbot`;
-            nodes.push({ id: cornerAnchorId, position: { x: loopRightX - 1, y: y - 1 }, data: { anchor: true }, type: 'sequenceAnchor', draggable: false, selectable: false }, {
+            nodes.push({
                 id: returnAnchorId,
                 position: {
                     x: participantCenterX(fromIdx, seq.leftPadding, seq.participantWidth, seq.participantGap) - 1,
@@ -306,8 +306,16 @@ export function layoutSequenceDiagram(sequence, theme, metadata) {
                 type: 'sequenceAnchor',
                 draggable: false,
                 selectable: false,
-            }, { id: cornerBottomId, position: { x: loopRightX - 1, y: loopBottomY - 1 }, data: { anchor: true }, type: 'sequenceAnchor', draggable: false, selectable: false });
-            edges.push(buildSequenceEdge(`e-self-${mi}-a`, sourceAnchorId, cornerAnchorId, msg.arrowType, theme, false), buildSequenceEdge(`e-self-${mi}-b`, cornerAnchorId, cornerBottomId, msg.arrowType, theme, false), buildSequenceEdge(`e-self-${mi}-c`, cornerBottomId, returnAnchorId, msg.arrowType, theme, true));
+            });
+            // Self-message: draw a single rounded loop-back path (closer to Mermaid).
+            const cx = participantCenterX(fromIdx, seq.leftPadding, seq.participantWidth, seq.participantGap);
+            const routePoints = [
+                { x: cx, y },
+                { x: loopRightX, y },
+                { x: loopRightX, y: loopBottomY },
+                { x: cx, y: loopBottomY },
+            ];
+            edges.push(buildSequenceRoutedEdge(`e-self-${mi}`, sourceAnchorId, returnAnchorId, msg.arrowType, theme, true, routePoints));
             if (label) {
                 nodes.push({
                     id: `__msglabel_${mi}`,
@@ -392,6 +400,7 @@ export function layoutSequenceDiagram(sequence, theme, metadata) {
 function buildSequenceEdge(id, source, target, arrowType, theme, showArrow) {
     const isDashed = arrowType === 'dashed' || arrowType === 'dashed_open';
     const isOpen = arrowType === 'solid_open' || arrowType === 'dashed_open';
+    const markerSize = theme.edgeDefaults.markerSize;
     return {
         id,
         source,
@@ -406,8 +415,34 @@ function buildSequenceEdge(id, source, target, arrowType, theme, showArrow) {
             markerEnd: {
                 type: MarkerType.ArrowClosed,
                 color: theme.color.gray3,
-                width: 10,
-                height: 10,
+                width: markerSize,
+                height: markerSize,
+            },
+        } : {}),
+    };
+}
+function buildSequenceRoutedEdge(id, source, target, arrowType, theme, showArrow, points) {
+    const isDashed = arrowType === 'dashed' || arrowType === 'dashed_open';
+    const isOpen = arrowType === 'solid_open' || arrowType === 'dashed_open';
+    const svgPath = generateRoundedPath(points, 14);
+    const markerSize = theme.edgeDefaults.markerSize;
+    return {
+        id,
+        source,
+        target,
+        type: 'routed',
+        style: {
+            stroke: theme.color.gray3,
+            strokeWidth: 1.5,
+            ...(isDashed ? { strokeDasharray: '6,4' } : {}),
+        },
+        data: { svgPath },
+        ...(showArrow && !isOpen ? {
+            markerEnd: {
+                type: MarkerType.ArrowClosed,
+                color: theme.color.gray3,
+                width: markerSize,
+                height: markerSize,
             },
         } : {}),
     };

package/dist/layout/subgraph.js

@@ -11,7 +11,31 @@
  * Falls back to manual bounding box if dagre cluster data isn't available.
  */
 export function computeSubgraphBounds(subgraph, nodePositions, padding, labelOffset, dagreGraph) {
-    // Try dagre's computed cluster bounds first
+    // Prefer manual bounds derived from child node positions. In practice this
+    // is more reliable than dagre's compound cluster dimensions when node
+    // sizes are overridden post-measurement.
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const nodeId of subgraph.nodeIds) {
+        const pos = nodePositions.get(nodeId);
+        if (!pos)
+            continue;
+        minX = Math.min(minX, pos.x);
+        minY = Math.min(minY, pos.y);
+        maxX = Math.max(maxX, pos.x + pos.width);
+        maxY = Math.max(maxY, pos.y + pos.height);
+    }
+    if (isFinite(minX)) {
+        // Account for node shadows/rounding so children don't "peek" outside.
+        const shadowPad = 4;
+        const pad = padding + shadowPad;
+        return {
+            x: minX - pad,
+            y: minY - pad - labelOffset,
+            width: maxX - minX + pad * 2,
+            height: maxY - minY + pad * 2 + labelOffset,
+        };
+    }
+    // Fallback: use dagre's computed cluster bounds if available.
     if (dagreGraph) {
         const clusterNode = dagreGraph.node(subgraph.id);
         if (clusterNode && clusterNode.width && clusterNode.height) {
@@ -23,25 +47,7 @@ export function computeSubgraphBounds(subgraph, nodePositions, padding, labelOff
             };
         }
     }
-    // Fallback: manual bounding box from child node positions
-    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-    for (const nodeId of subgraph.nodeIds) {
-        const pos = nodePositions.get(nodeId);
-        if (!pos)
-            continue;
-        minX = Math.min(minX, pos.x);
-        minY = Math.min(minY, pos.y);
-        maxX = Math.max(maxX, pos.x + pos.width);
-        maxY = Math.max(maxY, pos.y + pos.height);
-    }
-    if (!isFinite(minX))
-        return null;
-    return {
-        x: minX - padding,
-        y: minY - padding - labelOffset,
-        width: maxX - minX + padding * 2,
-        height: maxY - minY + padding * 2 + labelOffset,
-    };
+    return null;
 }
 // ─── Subgraph Node Builder ──────────────────────────────────────────────────
 export function buildSubgraphNode(subgraph, bounds, theme) {
@@ -51,13 +57,16 @@ export function buildSubgraphNode(subgraph, bounds, theme) {
         position: { x: bounds.x, y: bounds.y },
         data: { label: subgraph.label },
         type: 'subgraph',
+        zIndex: 0,
         style: {
+            boxSizing: 'border-box',
             width: bounds.width,
             height: bounds.height,
             backgroundColor: `${theme.color.darkBg3}${subgraphStyles.bgOpacity}`,
             border: `${subgraphStyles.borderStyle} ${theme.color.gray3}`,
             borderRadius: theme.radius.lg,
             padding: theme.space[2],
+            overflow: 'visible',
         },
     };
 }

package/dist/parsers/flowchart.js

@@ -78,11 +78,17 @@ export function parseFlowchart(syntax) {
     }
     const resolvedEdges = [];
     for (const edge of edges) {
-        const source = resolveFlowEndpoint(edge.source, 'source', nodeMap, subgraphMap);
-        const target = resolveFlowEndpoint(edge.target, 'target', nodeMap, subgraphMap);
-        if (!source || !target)
+        const sourceResolved = resolveFlowEndpoint(edge.source, 'source', nodeMap, subgraphMap);
+        const targetResolved = resolveFlowEndpoint(edge.target, 'target', nodeMap, subgraphMap);
+        if (!sourceResolved || !targetResolved)
             continue;
-        resolvedEdges.push({ ...edge, source, target });
+        resolvedEdges.push({
+            ...edge,
+            source: sourceResolved.nodeId,
+            target: targetResolved.nodeId,
+            sourceSubgraphId: sourceResolved.subgraphId,
+            targetSubgraphId: targetResolved.subgraphId,
+        });
     }
     return {
         kind: 'graph',
@@ -99,12 +105,15 @@ function resolveFlowEndpoint(endpoint, role, nodeMap, subgraphMap) {
         // Heuristic anchor selection:
         // - source endpoint (subgraph -> node): use the last member encountered
         // - target endpoint (node -> subgraph): use the first member encountered
-        return role === 'source'
-            ? sg.nodeIds[sg.nodeIds.length - 1]
-            : sg.nodeIds[0];
+        return {
+            nodeId: role === 'source'
+                ? sg.nodeIds[sg.nodeIds.length - 1]
+                : sg.nodeIds[0],
+            subgraphId: endpoint,
+        };
     }
     if (nodeMap.has(endpoint))
-        return endpoint;
+        return { nodeId: endpoint };
     return null;
 }
 // ─── Arrow Classification ─────────────────────────────────────────────────────

package/dist/theme/dark.js

@@ -107,7 +107,7 @@ const edgeDefaults = {
     labelBgBorderRadius: 4,
     dashedPattern: '5,5',
     thickWidth: 3,
-    markerSize: 12,
+    markerSize: 14,
 };
 // ─── Shared Node Base Styles ────────────────────────────────────────────────
 const nodeBase = {
@@ -160,7 +160,7 @@ const nodeStyles = {
     sequence: {
         number: { size: 22, fontSize: font.size.xs, borderWidth: '1.5px' },
         block: { borderWidth: borderWidth.sm, dividerWidth: borderWidth.sm, labelCharWidth: 8, labelOffsetBase: 24 },
-        note: { borderWidth: borderWidth.sm, paddingY: space[1] },
+        note: { borderWidth: borderWidth.sm, paddingY: space[1], backgroundColor: color.darkBg3, textColor: color.gray4 },
     },
     subgraph: {
         pointerEvents: 'none',

package/dist/theme/light.js

@@ -107,7 +107,7 @@ const edgeDefaults = {
     labelBgBorderRadius: 4,
     dashedPattern: '5,5',
     thickWidth: 3,
-    markerSize: 12,
+    markerSize: 14,
 };
 // ─── Shared Node Base Styles ────────────────────────────────────────────────
 const nodeBase = {
@@ -160,7 +160,8 @@ const nodeStyles = {
     sequence: {
         number: { size: 22, fontSize: font.size.xs, borderWidth: '1.5px' },
         block: { borderWidth: borderWidth.sm, dividerWidth: borderWidth.sm, labelCharWidth: 8, labelOffsetBase: 24 },
-        note: { borderWidth: borderWidth.sm, paddingY: space[1] },
+        // Light mode notes: use a darker neutral so they don't disappear on white backgrounds.
+        note: { borderWidth: borderWidth.sm, paddingY: space[1], backgroundColor: color.gray2, textColor: color.gray5 },
     },
     subgraph: {
         pointerEvents: 'none',

package/dist/theme/types.d.ts

@@ -81,6 +81,8 @@ export interface ThemeTokens {
             note: {
                 borderWidth: string;
                 paddingY: string;
+                backgroundColor: string;
+                textColor: string;
             };
         };
         subgraph: {

package/dist/types.d.ts

@@ -141,6 +141,18 @@ export type Cardinality = 'ONLY_ONE' | 'ZERO_OR_ONE' | 'ZERO_OR_MORE' | 'ONE_OR_
 export interface ParsedEdge {
     source: string;
     target: string;
+    /**
+     * If the original Mermaid syntax referenced a subgraph id as an endpoint,
+     * we resolve it to a representative member node for layout, but keep the
+     * subgraph id here so edge rendering can attach to the subgraph boundary.
+     */
+    sourceSubgraphId?: string;
+    /**
+     * If the original Mermaid syntax referenced a subgraph id as an endpoint,
+     * we resolve it to a representative member node for layout, but keep the
+     * subgraph id here so edge rendering can attach to the subgraph boundary.
+     */
+    targetSubgraphId?: string;
     label?: string;
     edgeType?: EdgeType;
     /** Render edge line without arrowhead marker (used by mindmap-like links). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graph-artifact/core",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "Composable Mermaid-like parser, layout engine, and React renderer for interactive diagram artifacts.",
   "license": "MIT",
   "repository": {