[pull] develop from mermaid-js:develop

.changeset/elk-even-subgraph-frames.md

@@ -0,0 +1,15 @@
+---
+'@mermaid-js/layout-elk': patch
+---
+
+fix: draw ELK subgraph frames an even distance from their contents.
+
+A subgraph could sit 76px from its nodes on one side and 24px on the other, with nothing visible in the gap. ELK sizes a container around everything it put inside, edges included, and an edge that runs against the flow of the layout is routed back around the outside — so a group holding one grew on whichever side that edge left by, and a group without one did not.
+
+The lane is real and the edge still needs it, so the space is not reclaimed. What changes is that the frame is no longer drawn around it: the frame is pulled in to an even distance from the group's own children, and the edge keeps its lane just outside, which is what an edge routed around a group should look like anyway.
+
+The top is left as ELK set it, since it carries the subgraph's title strip and there is no way to tell how much of that padding is the title and how much is spare.
+
+A frame still holds the lanes that genuinely belong to it. An edge with both endpoints inside a group never leaves it, so its lane is part of that group's interior and the frame stays drawn around it — which matters for nested groups, where a lane routed around an inner group sits inside the outer one.
+
+**Subgraphs render tighter, and groups that used to be visibly lopsided are now even.**

.changeset/elk-layout-presets.md

@@ -0,0 +1,29 @@
+---
+'@mermaid-js/layout-elk': minor
+---
+
+feat: `elk.preset` picks a named combination of the options that decide where nodes end up.
+
+Three options settle node positions, and they sit in different phases of the layout: which layer a node lands in, where it goes within that layer, and which edges get reversed to make the graph acyclic. Choosing them well means knowing all three interact; `preset` names the combinations worth using.
+
+- `default` — network simplex layering and placement with depth-first cycle breaking at the top level; subgraph contents are placed with Brandes-Koepf. Depth-first breaking gives shorter back edges on graphs that loop.
+- `legacy` — reproduces what earlier versions actually rendered: Brandes-Koepf placement with ELK's own greedy cycle breaking.
+- `modelOrder` — as `default`, but breaks cycles by greedy model order, which disturbs declaration order least at the cost of longer back edges.
+- `depthFirst` — a name for what `default` already is, so a diagram can say depth-first rather than rely on the default staying put.
+
+```yaml
+---
+config:
+  layout: elk
+  elk:
+    preset: legacy
+---
+```
+
+Setting `layeringStrategy`, `nodePlacementStrategy` or `cycleBreakingStrategy` explicitly overrides the preset for that one option and leaves the rest in place, so a preset is a starting point rather than a lock.
+
+**Node placement changes from `BRANDES_KOEPF` to `NETWORK_SIMPLEX`, so existing ELK diagrams will lay out differently.** `preset: legacy` restores the previous behaviour, and is the single switch for it — this is the net change against the last release, measured from what shipped rather than from any intermediate state.
+
+Subgraph contents keep `BRANDES_KOEPF`, which is deliberately not the root's strategy: network simplex inside a frame produced routes that left the subgraph on its bounding-box corner. The two sides are tuned independently, so `nodePlacementStrategy` set explicitly still applies to both.
+
+Note that `legacy` uses `GREEDY` cycle breaking rather than the `GREEDY_MODEL_ORDER` the schema previously advertised. That default was declared in the schema but never listed in the shipped defaults, so it reached ELK as undefined and ELK's own default applied — `legacy` reproduces what was rendered, not what was documented.

.changeset/elk-line-hops.md

@@ -0,0 +1,20 @@
+---
+'@mermaid-js/layout-elk': minor
+---
+
+feat: draw line hops where ELK edges cross, controlled by `elk.lineHops`.
+
+Where two edges cross, the one that gives way is drawn with a small arc (or a visible gap) so it is clear which line passes over which. On by default; set `elk.lineHops: false` to draw plain crossings, or `'gap'` to use gaps instead of arcs.
+
+```yaml
+---
+config:
+  layout: elk
+  elk:
+    lineHops: gap
+---
+```
+
+The crossing detection and both styles already existed and were used by swimlanes — this registers the `afterPaint` hook that lets ELK use them. An edge that takes a hop loses its corner rounding on that segment, which is the trade for a readable crossing; curved edges are skipped rather than rewritten, to avoid corrupting their geometry.
+
+**Existing ELK diagrams with crossing edges will render differently.**

.changeset/elk-non-rect-attachment.md

@@ -0,0 +1,9 @@
+---
+'@mermaid-js/layout-elk': patch
+---
+
+fix: edges leave diamonds, stadiums and other non-rectangular shapes without kinking.
+
+ELK routes to ports on a node's bounding box and always leaves one perpendicular to the side it sits on. For a rectangle that port is the attachment point; for anything else the outline is inside the box, so the attachment has to move inwards — and the direction it moves in decides whether the edge stays orthogonal.
+
+It used to move along the ray from the node's centre, which lands on the outline at a different offset along the side than the port ELK chose, so the opening segment came out diagonal. The attachment now walks the outline along the edge's own departure axis, staying collinear with ELK's stub: the edge leaves the outline, crosses the box, and carries on in one straight line. Rectangular nodes are unaffected.

.changeset/elk-port-corner-spacing.md

@@ -0,0 +1,21 @@
+---
+'@mermaid-js/layout-elk': patch
+---
+
+fix: an edge no longer leaves a subgraph from the frame's corner.
+
+`elk.spacing.portsSurrounding` was left at ELK's default of `0`, which permits a
+port to sit exactly on a node's corner. A corner is the one boundary point with
+no side to leave from, so the edge came out of the vertex and then ran ALONG the
+frame's own edge before turning away from it. Subgraphs showed it first, because
+an edge that crosses a subgraph boundary attaches to the frame rather than to a
+node inside it, and a frame is large enough for the result to be obvious.
+
+A margin is now reserved at the ends of every side, so ELK keeps ports off the
+corners itself rather than the renderer correcting them afterwards. Over the
+`elk-edge-cases` corpus this takes the fixtures with a corner endpoint from 8 of
+30 down to 3.
+
+The value is 12, chosen by measurement: it is the smallest that clears the
+corner on that corpus. It is not a free parameter — 30 was tried and reorders
+layers.

.changeset/elk-straighten-terminal-jogs.md

@@ -0,0 +1,11 @@
+---
+'@mermaid-js/layout-elk': patch
+---
+
+fix: an edge no longer leaves a node with a tiny kink.
+
+ELK spreads an edge's port evenly along a node's side, then routes the edge down a channel whose row rarely lines up with that port exactly. The leftover is a staircase of a few pixels right at the border: leave the port, run a short distance, step perpendicular onto the channel, carry on. With rounded corners the two micro-bends sit on top of each other and read as a glitch — one edge in the sample corpus stepped 3.25px and rendered as two quadratic curves with a zero-length segment between them.
+
+The step is now removed by moving the channel onto the port's row, so the edge draws as one straight line and **both ports stay exactly where the layout put them** — sliding an attachment along a node's border leaves a node whose other edges are still evenly spread looking lopsided. Only a step next to a node is touched, and only when it is small and the edge continues the same way afterwards, so a real turn is never collapsed. An edge is left alone entirely when moving its run would drag the far port, or would buy a crossing.
+
+Set `elk.straightenEdges: false` to keep the previous behaviour.

.changeset/elk-subgraph-spacing-split.md

@@ -0,0 +1,17 @@
+---
+'@mermaid-js/layout-elk': patch
+---
+
+fix: stop ELK subgraphs padding one side more than the other.
+
+A subgraph could end up with far more space on one side than the other for no reason a reader could see — 74px on the right of one group against 24px everywhere else. The extra space was a routing lane held open for an edge that runs against the flow of the layout and has to be routed back around, and its width came from `spacing.baseValue`.
+
+That base value was doing two jobs at once. Every unset ELK spacing derives from it, so it had to stay large enough that an edge got a straight run before the node it enters — below about 40 the approach came out shorter than the arrowhead and the turn read as happening underneath it. But an edge routed down the inside of a frame claims a lane the same width, so paying for the approach out of the base value also pushed groups clear of their own borders.
+
+The two are now bought separately. The base value drops to 24, and the approach run, node separation and edge separation are set explicitly, so edges keep the run they had without the frame paying for it.
+
+`elk.layered.spacing.edgeNodeBetweenLayers` is the key that buys the approach. An earlier attempt used `elk.layered.spacing.edgeEdgeBetweenLayers`, which is edge-to-edge and a different quantity, and a note in the source concluded from it that ELK ignored edge-node spacing "in every key form". It does not; that note was wrong and is corrected.
+
+Subgraph contents also gain `PORT_POSITION` node flexibility, which lets a node shift so an edge can leave straight rather than bending off the port. (Their placement strategy is covered in the `elk.preset` note.)
+
+**Existing diagrams with subgraphs will render differently** — groups get tighter and more even.

.changeset/er-requirement-palette-css.md

@@ -0,0 +1,11 @@
+---
+'mermaid': patch
+---
+
+fix(er, requirement, timeline): stop the ER, requirement and timeline stylesheets emitting invalid CSS for the colour themes.
+
+All three generate one rule per palette slot, looping to `THEME_COLOR_LIMIT` and indexing the palette by the loop counter. Indexing raw means a palette with fewer entries than that limit emits `stroke: undefined` for the overflow slots; all three now wrap at the palette length, and bail before the loop for an empty palette — wrapping alone is not enough there, because `i % 0` is `NaN` and `[][NaN]` is `undefined`.
+
+`requirement` also emitted `fill: ;` — a property with no value, which is invalid — whenever there was no background palette. That is the live case for `redux-dark-color`, which ships a border palette and no background palette so that it colours outlines only. The declaration is now omitted instead.
+
+None of these raises an error: the browser discards the invalid declaration, so the only symptom is a shape rendering unstyled.

.changeset/export-line-jumps.md

@@ -0,0 +1,9 @@
+---
+'mermaid': minor
+---
+
+feat: export `applyLineJumpsToSvg` so layout packages outside this one can draw line hops.
+
+Line jumps are applied after paint, once every edge has been emitted and the crossings are known. A layout that ships inside this package can reach into `rendering-util` to do that; one that ships separately, like `@mermaid-js/layout-elk`, cannot. Exporting it alongside the other common-renderer pieces lets an external layout register an `afterPaint` hook that draws hops the same way the built-in ones do.
+
+`EdgeGeom` and `LineJumpConfig` are exported with it, since they are the argument types.

.changeset/fix-docs-build-destructive-order.md

@@ -0,0 +1,5 @@
+---
+'mermaid': patch
+---
+
+fix(docs): stop `docs:build` deleting the committed `docs/` directory when a later step fails.

.changeset/intersect-line-half-pixel.md

@@ -0,0 +1,13 @@
+---
+'mermaid': patch
+---
+
+fix: edges attach to non-rectangular shapes on the outline instead of half a pixel off it.
+
+**This is not ELK-specific.** `intersectPolygon` is how every non-rectangular shape finds its edge attachment — diamond, stadium, hexagon, trapezoid, subroutine — in every layout, so a dagre-rendered flowchart with a decision diamond is affected exactly as much as an ELK one.
+
+`intersectLine` comes from Graphics Gems, where the coordinates were integers and the numerator was nudged half a denominator away from zero so the integer division rounded instead of truncating. JavaScript division does neither, so the nudge stopped being a correction and became the whole error: every result came back displaced by `0.5 * sign(num) * sign(denom)`. The magnitude is always exactly half a unit, but the sign is per axis, because the numerator is computed separately for x and y while the denominator is shared — so the two axes could move the same way or opposite ways depending on the geometry, which is why it never looked like a constant offset anyone could spot by eye.
+
+That was enough to give an otherwise orthogonal edge a tiny diagonal opening segment, and to put an attachment just inside the node it was meant to touch.
+
+`question.ts` had been subtracting a flat 0.5 from both axes to compensate for diamonds. That only cancelled the bias when both signs came out positive, and doubled the error to a full unit when they did not — so the compensation goes along with the cause. **Rendered output moves by up to a pixel wherever a polygon shape terminates an edge.**

.changeset/line-hop-corner-clearance.md

@@ -0,0 +1,13 @@
+---
+'mermaid': patch
+---
+
+fix: don't draw a line hop that has no room next to a bend.
+
+A crossing close to a corner used to get a hop squeezed into whatever space was left — as little as 2.9px against a requested 6px, opening exactly on the corner's tangent point. At that size the arc no longer clears the line it is meant to hop, so the two strokes still touch and the corner's curve runs straight into the arc's. It reads as a rendering fault rather than as a crossing.
+
+Hops now keep a straight run clear of the bend, and one that would still have to shrink below 60% of the requested radius is dropped instead of drawn. An undrawn hop is an ordinary crossing, which is a much better failure than a broken-looking one.
+
+**This changes swimlane diagrams as well as ELK ones.** Swimlanes are the existing consumer of line hops and have them on today, so a swimlane with a crossing near a bend will render differently even for someone not using ELK at all. It shows up wherever a layout stacks edges in narrow lanes: ELK routes subgraph-internal edges 10px apart, and 10px does not hold a 7.07px corner cut plus a 6px hop.
+
+A crossing is also ignored now when it lands inside the stretch where either edge is rounding a bend. Crossings are found on polylines, but a rounded edge is not drawn as its polyline — it leaves the line up to 7.07px before each bend and rejoins it that far after. A crossing found inside that stretch is somewhere the stroke never goes, so the hop was arching over blank paper while the two lines carried on touching beside it.

.changeset/redux-color-theme-superset.md

@@ -0,0 +1,5 @@
+---
+'mermaid': patch
+---
+
+fix(themes): `redux-color` and `redux-dark-color` now define every variable their base themes define, instead of silently falling back to untuned values for `primaryBorderColor`, `clusterBkg`, `clusterBorder`, `altBackground`, `compositeTitleBackground` and the state and requirement edge-label backgrounds. Pie, gantt and user-journey also read the theme palette rather than a single pale tint, so pie slices are distinguishable and gantt sections are visibly banded.

.changeset/sequence-palette-indexing.md

@@ -0,0 +1,9 @@
+---
+'mermaid': patch
+---
+
+fix(sequence): index each actor colour palette by its own length.
+
+Every actor-drawing call site read `bkgColorArray[actorCount % borderColorArray.length]` — one palette indexed by the other's length. Under `redux-color` both palettes have twelve entries, so the wrong length happens to give the right answer and nothing is visibly broken today. It goes wrong as soon as the two differ in length: the overflow actors resolve to `undefined`, and d3 then strips the inline fill for some actors and not others.
+
+Both palettes now cycle within their own length, via a shared helper. An absent or empty palette still yields `undefined` rather than a substitute colour, which is what `redux-dark-color` relies on: it ships a border palette and an empty background palette so actors are outlined but not filled.

.cspell/code-terms.txt

@@ -53,6 +53,7 @@ DOUBLECIRCLEEND
 DOUBLECIRCLESTART
 DQUOTE
 DSTART
+DUMMYNODE
 EBNF
 edgesep
 Eiglsperger
@@ -101,6 +102,8 @@ minlen
 Mstartx
 MULT
 Naur
+NIKOLOV
+NODECOUNT
 NODIR
 nonterminal
 NSTR

.github/workflows/e2e-applitools.yml

@@ -49,7 +49,7 @@ jobs:
         env:
           MERMAID_PORT: 9000
           APPLITOOLS_API_KEY: ${{ secrets.APPLITOOLS_API_KEY }}
-          APPLITOOLS_BATCH_ID: ${{ github.sha }}
+          APPLITOOLS_BATCH_ID: ${{ github.sha }}-${{ github.run_id }}
           # e.g. mermaid-js/mermaid/my-branch
           APPLITOOLS_BRANCH: ${{ github.repository }}/${{ github.ref_name }}
           APPLITOOLS_PARENT_BRANCH: ${{ github.event.inputs.parent_branch }}

.github/workflows/e2e.yml

@@ -304,7 +304,6 @@ jobs:
         id: playwright
         env:
           MERMAID_PORT: 9000
-          PLAYWRIGHT_COMMIT: ${{ github.sha }}
           # Enables native V8 coverage collection (page.coverage) on coverage runs.
           E2E_COVERAGE: ${{ (github.event_name == 'pull_request' || github.ref == 'refs/heads/develop') && 'true' || '' }}
           # Job output via env — never interpolate spec globs into the shell via ${{ }}.

.github/workflows/refresh-sheet-order.yml

@@ -56,7 +56,6 @@ jobs:
         env:
           MERMAID_PORT: 9000
           RUN_VISUAL_TEST: 'true'
-          PLAYWRIGHT_COMMIT: ${{ github.sha }}
 
       - name: Regenerate sheet order
         run: pnpm run screenshots:order

docs/config/setup/defaultConfig/variables/configKeys.md

@@ -12,4 +12,4 @@
 
 > `const` **configKeys**: `Set`<`string`>
 
-Defined in: [packages/mermaid/src/defaultConfig.ts:343](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L343)
+Defined in: [packages/mermaid/src/defaultConfig.ts:354](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L354)

docs/config/setup/mermaid/README.md

@@ -18,9 +18,11 @@
 - [CommonLayoutRenderContext](interfaces/CommonLayoutRenderContext.md)
 - [CommonLayoutRendererDefinition](interfaces/CommonLayoutRendererDefinition.md)
 - [DetailedError](interfaces/DetailedError.md)
+- [EdgeGeom](interfaces/EdgeGeom.md)
 - [ExternalDiagramDefinition](interfaces/ExternalDiagramDefinition.md)
 - [LayoutData](interfaces/LayoutData.md)
 - [LayoutLoaderDefinition](interfaces/LayoutLoaderDefinition.md)
+- [LineJumpConfig](interfaces/LineJumpConfig.md)
 - [Mermaid](interfaces/Mermaid.md)
 - [MermaidConfig](interfaces/MermaidConfig.md)
 - [ParseOptions](interfaces/ParseOptions.md)
@@ -46,6 +48,7 @@
 
 ## Functions
 
+- [applyLineJumpsToSvg](functions/applyLineJumpsToSvg.md)
 - [clearLayoutRenderState](functions/clearLayoutRenderState.md)
 - [createCommonLayoutRenderer](functions/createCommonLayoutRenderer.md)
 - [defaultMeasureLayout](functions/defaultMeasureLayout.md)

docs/config/setup/mermaid/functions/applyLineJumpsToSvg.md

@@ -0,0 +1,39 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/config/setup/mermaid/functions/applyLineJumpsToSvg.md](../../../../../packages/mermaid/src/docs/config/setup/mermaid/functions/applyLineJumpsToSvg.md).
+
+[**mermaid**](../../README.md)
+
+---
+
+# Function: applyLineJumpsToSvg()
+
+> **applyLineJumpsToSvg**(`edgePathsGroup`, `edges`, `config`): `void`
+
+Defined in: [packages/mermaid/src/rendering-util/rendering-elements/lineJump.ts:646](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/rendering-util/rendering-elements/lineJump.ts#L646)
+
+Patches the rendered SVG paths in `edgePathsGroup` for any edges that
+cross. The true geometry is read from each path's `data-points` attribute
+(written by edges.js at render time) so the rewrite's endpoints match
+exactly what was originally rendered. Edges whose curve is a true
+smoothing curve (`basis`, `monotoneX`, …) are skipped.
+
+## Parameters
+
+### edgePathsGroup
+
+`D3Selection`<`SVGGElement`>
+
+### edges
+
+[`EdgeGeom`](../interfaces/EdgeGeom.md)\[]
+
+### config
+
+[`LineJumpConfig`](../interfaces/LineJumpConfig.md)
+
+## Returns
+
+`void`