pbrolin47 · Jun 10, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 5, 2026 · Jun 9, 2026
diff --git a/.changeset/class-default-unified-renderer.md b/.changeset/class-default-unified-renderer.md
@@ -0,0 +1,12 @@
+---
+'mermaid': minor
+---
+
+feat: route `classDiagram` to the unified (v2) renderer by default
+
+`class.defaultRenderer` now defaults to `dagre-wrapper`, so plain `classDiagram`
+documents (without the `-v2` suffix) render through the unified renderer and the
+shared dagre layout/paint pipeline instead of the legacy class renderer. Set
+`class: { defaultRenderer: 'dagre-d3' }` in the config to restore the legacy
+renderer. Self-referential edges in class and ER diagrams now render as compact
+merged self-loops.
diff --git a/cypress/integration/rendering/class/classDiagram-handDrawn-v3.spec.js b/cypress/integration/rendering/class/classDiagram-handDrawn-v3.spec.js
@@ -1137,4 +1137,19 @@ class C13["With Città foreign language"]
       { class: { hierarchicalNamespaces: false } }
     );
   });
+
+  it('HD: should render a self-referential class diagram with multiplicity labels', () => {
+    imgSnapshotTest(
+      `
+      classDiagram
+      class SelfReferential{
+          +int id
+          +int self_referential_id
+          +SelfReferential referenced
+      }
+      SelfReferential "1" --> "0..1" SelfReferential : referenced
+      `,
+      { logLevel: 1, htmlLabels: true, look: 'handDrawn' }
+    );
+  });
 });
diff --git a/docs/config/setup/defaultConfig/variables/configKeys.md b/docs/config/setup/defaultConfig/variables/configKeys.md
@@ -12,4 +12,4 @@
 
 > `const` **configKeys**: `Set`<`string`>
 
-Defined in: [packages/mermaid/src/defaultConfig.ts:335](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L335)
+Defined in: [packages/mermaid/src/defaultConfig.ts:339](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L339)
diff --git a/docs/config/setup/mermaid/functions/clearLayoutRenderState.md b/docs/config/setup/mermaid/functions/clearLayoutRenderState.md
@@ -12,7 +12,7 @@
 
 > **clearLayoutRenderState**(): `void`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:145](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L145)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:164](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L164)
 
 ## Returns
 

diff --git a/docs/config/setup/mermaid/functions/createCommonLayoutRenderer.md b/docs/config/setup/mermaid/functions/createCommonLayoutRenderer.md
@@ -12,7 +12,7 @@
 
 > **createCommonLayoutRenderer**<`CoreResult`, `PreparedLayout`, `MeasureResult`>(`__namedParameters`): (`data4Layout`, `svg`, `helpers?`, `options?`, `positions?`) => `Promise`<`void`>
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:88](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L88)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:107](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L107)
 
 ## Type Parameters
 

diff --git a/docs/config/setup/mermaid/functions/defaultMeasureLayout.md b/docs/config/setup/mermaid/functions/defaultMeasureLayout.md
@@ -12,7 +12,7 @@
 
 > **defaultMeasureLayout**(`data4Layout`, `__namedParameters`): `Promise`<{ `graph`: `Graph`; `groups`: { `clusters`: `D3Selection`<`SVGGElement`>; `edgeLabels`: `D3Selection`<`SVGGElement`>; `edgePaths`: `D3Selection`<`SVGGElement`>; `nodes`: `D3Selection`<`SVGGElement`>; `rootGroups`: `D3Selection`<`SVGGElement`>; }; `nodeElements`: `Map`<`string`, `D3Selection`<`SVGElement` | `SVGGElement`>>; }>
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:152](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L152)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:171](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L171)
 
 ## Parameters
 

diff --git a/docs/config/setup/mermaid/functions/paintLayoutData.md b/docs/config/setup/mermaid/functions/paintLayoutData.md
@@ -10,17 +10,17 @@
 
 # Function: paintLayoutData()
 
-> **paintLayoutData**(`data4Layout`, `__namedParameters`, `options`): `Promise`<`void`>
+> **paintLayoutData**(`data4Layout`, `context`, `options`): `Promise`<`void`>
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:159](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L159)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:178](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L178)
 
 ## Parameters
 
 ### data4Layout
 
 [`LayoutData`](../interfaces/LayoutData.md)
 
-### \_\_namedParameters
+### context
 
 [`CommonLayoutPaintContext`](../interfaces/CommonLayoutPaintContext.md)<`unknown`, { `graph`: `Graph`; `groups`: { `clusters`: `D3Selection`<`SVGGElement`>; `edgeLabels`: `D3Selection`<`SVGGElement`>; `edgePaths`: `D3Selection`<`SVGGElement`>; `nodes`: `D3Selection`<`SVGGElement`>; `rootGroups`: `D3Selection`<`SVGGElement`>; }; `nodeElements`: `Map`<`string`, `D3Selection`<`SVGElement` | `SVGGElement`>>; }>
 

diff --git a/docs/config/setup/mermaid/interfaces/CommonLayoutPaintContext.md b/docs/config/setup/mermaid/interfaces/CommonLayoutPaintContext.md
@@ -10,7 +10,7 @@
 
 # Interface: CommonLayoutPaintContext\<PreparedLayout, MeasureResult>
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:46](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L46)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:47](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L47)
 
 ## Extends
 
@@ -32,7 +32,7 @@ Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.
 
 > **element**: `D3Selection`<`SVGElement`>
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:39](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L39)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:40](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L40)
 
 #### Inherited from
 
@@ -44,7 +44,7 @@ Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.
 
 > `optional` **helpers**: `object`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:40](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L40)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:41](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L41)
 
 #### common
 
@@ -492,15 +492,15 @@ The curve factory to use
 
 > **measure**: `MeasureResult`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:50](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L50)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:51](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L51)
 
 ---
 
 ### options?
 
 > `optional` **options**: [`RenderOptions`](RenderOptions.md)
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:41](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L41)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:42](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L42)
 
 #### Inherited from
 
@@ -512,7 +512,7 @@ Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.
 
 > `optional` **positions**: `Positions`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:42](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L42)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:43](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L43)
 
 #### Inherited from
 
@@ -524,7 +524,7 @@ Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.
 
 > `optional` **preparedLayout**: `PreparedLayout`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:43](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L43)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:44](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L44)
 
 #### Inherited from
 

diff --git a/docs/config/setup/mermaid/interfaces/CommonLayoutPaintOptions.md b/docs/config/setup/mermaid/interfaces/CommonLayoutPaintOptions.md
@@ -10,15 +10,93 @@
 
 # Interface: CommonLayoutPaintOptions
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:53](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L53)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:54](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L54)
 
 ## Properties
 
+### clusterDb?
+
+> `optional` **clusterDb**: `ClusterDb`
+
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:55](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L55)
+
+---
+
+### getEdgeNode()?
+
+> `optional` **getEdgeNode**: (`id`, `edge`, `context`) => `object` | `Node` | `undefined`
+
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:60](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L60)
+
+#### Parameters
+
+##### id
+
+`string` | `undefined`
+
+##### edge
+
+`Edge`
+
+##### context
+
+[`CommonLayoutPaintContext`](CommonLayoutPaintContext.md)<`unknown`, { `graph`: `Graph`; `groups`: { `clusters`: `D3Selection`<`SVGGElement`>; `edgeLabels`: `D3Selection`<`SVGGElement`>; `edgePaths`: `D3Selection`<`SVGGElement`>; `nodes`: `D3Selection`<`SVGGElement`>; `rootGroups`: `D3Selection`<`SVGGElement`>; }; `nodeElements`: `Map`<`string`, `D3Selection`<`SVGElement` | `SVGGElement`>>; }>
+
+#### Returns
+
+`object` | `Node` | `undefined`
+
+---
+
+### getNodes()?
+
+> `optional` **getNodes**: (`data4Layout`, `context`) => `Iterable`<`Node`>
+
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:56](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L56)
+
+#### Parameters
+
+##### data4Layout
+
+[`LayoutData`](LayoutData.md)
+
+##### context
+
+[`CommonLayoutPaintContext`](CommonLayoutPaintContext.md)<`unknown`, { `graph`: `Graph`; `groups`: { `clusters`: `D3Selection`<`SVGGElement`>; `edgeLabels`: `D3Selection`<`SVGGElement`>; `edgePaths`: `D3Selection`<`SVGGElement`>; `nodes`: `D3Selection`<`SVGGElement`>; `rootGroups`: `D3Selection`<`SVGGElement`>; }; `nodeElements`: `Map`<`string`, `D3Selection`<`SVGElement` | `SVGGElement`>>; }>
+
+#### Returns
+
+`Iterable`<`Node`>
+
+---
+
+### isCluster()?
+
+> `optional` **isCluster**: (`node`, `context`) => `boolean`
+
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:69](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L69)
+
+#### Parameters
+
+##### node
+
+`Node`
+
+##### context
+
+[`CommonLayoutPaintContext`](CommonLayoutPaintContext.md)<`unknown`, { `graph`: `Graph`; `groups`: { `clusters`: `D3Selection`<`SVGGElement`>; `edgeLabels`: `D3Selection`<`SVGGElement`>; `edgePaths`: `D3Selection`<`SVGGElement`>; `nodes`: `D3Selection`<`SVGGElement`>; `rootGroups`: `D3Selection`<`SVGGElement`>; }; `nodeElements`: `Map`<`string`, `D3Selection`<`SVGElement` | `SVGGElement`>>; }>
+
+#### Returns
+
+`boolean`
+
+---
+
 ### skipEdge()?
 
 > `optional` **skipEdge**: (`edge`) => `boolean`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:54](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L54)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:73](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L73)
 
 #### Parameters
 
@@ -36,4 +114,26 @@ Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.
 
 > `optional` **skipIntersect**: `boolean` | (`edge`) => `boolean`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:55](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L55)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:74](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L74)
+
+---
+
+### skipNode()?
+
+> `optional` **skipNode**: (`node`, `context`) => `boolean`
+
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:65](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L65)
+
+#### Parameters
+
+##### node
+
+`Node`
+
+##### context
+
+[`CommonLayoutPaintContext`](CommonLayoutPaintContext.md)<`unknown`, { `graph`: `Graph`; `groups`: { `clusters`: `D3Selection`<`SVGGElement`>; `edgeLabels`: `D3Selection`<`SVGGElement`>; `edgePaths`: `D3Selection`<`SVGGElement`>; `nodes`: `D3Selection`<`SVGGElement`>; `rootGroups`: `D3Selection`<`SVGGElement`>; }; `nodeElements`: `Map`<`string`, `D3Selection`<`SVGElement` | `SVGGElement`>>; }>
+
+#### Returns
+
+`boolean`
diff --git a/docs/config/setup/mermaid/interfaces/CommonLayoutRenderContext.md b/docs/config/setup/mermaid/interfaces/CommonLayoutRenderContext.md
@@ -10,7 +10,7 @@
 
 # Interface: CommonLayoutRenderContext\<PreparedLayout>
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:38](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L38)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:39](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L39)
 
 ## Extended by
 
@@ -28,15 +28,15 @@ Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.
 
 > **element**: `D3Selection`<`SVGElement`>
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:39](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L39)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:40](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L40)
 
 ---
 
 ### helpers?
 
 > `optional` **helpers**: `object`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:40](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L40)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:41](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L41)
 
 #### common
 
@@ -480,20 +480,20 @@ The curve factory to use
 
 > `optional` **options**: [`RenderOptions`](RenderOptions.md)
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:41](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L41)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:42](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L42)
 
 ---
 
 ### positions?
 
 > `optional` **positions**: `Positions`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:42](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L42)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:43](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L43)
 
 ---
 
 ### preparedLayout?
 
 > `optional` **preparedLayout**: `PreparedLayout`
 
-Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:43](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L43)
+Defined in: [packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts:44](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/layout-algorithms/common/index.ts#L44)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,4 +12,4 @@

		> `const` configKeys: `Set`<`string`>

		Defined in: [packages/mermaid/src/defaultConfig.ts:335](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L335)
		Defined in: [packages/mermaid/src/defaultConfig.ts:339](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L339)