@zombie-mermaid/svg-renderer 3.2.0 → 4.0.0

package/src/layout-engine.ts

@@ -35,6 +35,11 @@ import { resolveFontSizes } from './styles.ts'
 import { DEFAULTS } from './layout-engine/constants.ts'
 import { mermaidToElk } from './layout-engine/to-elk.ts'
 import { elkToPositioned } from './layout-engine/from-elk.ts'
+import {
+  canLayOutFlat,
+  layoutCompoundFlat,
+} from './layout-engine/compound-flat.ts'
+import type { LayoutHints } from './layout-engine/layout-hints.ts'
 
 // ============================================================================
 // Public API
@@ -47,17 +52,49 @@ import { elkToPositioned } from './layout-engine/from-elk.ts'
 export function layoutGraphSync(
   graph: MermaidGraph,
   options: FlowchartRenderOptions = {},
+): PositionedGraph {
+  return layoutWithHints(graph, options)
+}
+
+/** One layout run, with the hints the compound layout gives it. */
+function layoutWithHints(
+  graph: MermaidGraph,
+  options: FlowchartRenderOptions,
+  hints?: LayoutHints,
 ): PositionedGraph {
   const opts = {
     ...DEFAULTS,
     ...options,
     fontSizes: resolveFontSizes(options.fontSizes),
   }
-  const elkGraph = mermaidToElk(graph, opts)
+  const elkGraph = mermaidToElk(graph, opts, hints)
   const result = elkLayoutSync(elkGraph, options.layoutCache)
   return elkToPositioned(result, graph, opts.mergeEdges)
 }
 
+/**
+ * Lay out a flowchart, with its subgraphs arranged the way mermaid.js arranges
+ * them (see `layout-engine/compound-flat.ts`). Anything that layout doesn't
+ * handle, or can't make fit, is laid out by `layoutGraphSync`, so this is a
+ * drop-in for it wherever the graph is a flowchart. Other diagram types that
+ * share the engine (state, architecture) keep using `layoutGraphSync`.
+ */
+export function layoutFlowchartSync(
+  graph: MermaidGraph,
+  options: FlowchartRenderOptions = {},
+): PositionedGraph {
+  if (canLayOutFlat(graph)) {
+    const fontSizes = resolveFontSizes(options.fontSizes)
+    const flat = layoutCompoundFlat(
+      graph,
+      (g, hints) => layoutWithHints(g, options, hints),
+      fontSizes,
+    )
+    if (flat) return flat
+  }
+  return layoutGraphSync(graph, options)
+}
+
 /**
  * Convert MermaidGraph to ELK format (for benchmarking conversion overhead).
  */

package/src/registry.ts

@@ -81,7 +81,7 @@ import { layoutClassDiagramSync } from './class/layout.ts'
 import { renderClassSvg } from './class/renderer.ts'
 import { layoutC4DiagramSync } from './c4/layout.ts'
 import { renderC4Svg } from './c4/renderer.ts'
-import { layoutGraphSync } from './layout-engine.ts'
+import { layoutFlowchartSync, layoutGraphSync } from './layout-engine.ts'
 import { renderSvg as renderFlowchartSvg } from './renderer.ts'
 import { parseMermaid } from '../../../src/parser.ts'
 
@@ -309,7 +309,7 @@ const flowchartModule: DiagramModule<MermaidGraph, PositionedFlowchart> = {
     // see the doc comment on `PositionedFlowchart` above.
     const graph = withDirectionOverride(diagram, options.direction)
     return {
-      graph: layoutGraphSync(graph, options),
+      graph: layoutFlowchartSync(graph, options),
       curve: options.curve ?? diagram.initConfig?.curve ?? 'linear',
     }
   },

package/src/renderer.ts

@@ -30,6 +30,7 @@ import {
   ARROW_HEAD,
 } from './styles.ts'
 import { pointsToPath } from './edge-curves.ts'
+import { edgeCrossesTitle, titleGapMask, titleTextBoxes } from './title-gaps.ts'
 
 // ============================================================================
 // SVG renderer — converts a PositionedGraph into an SVG string.
@@ -143,6 +144,19 @@ export function renderSvg(
   for (const color of customStrokeColors) {
     parts.push(arrowMarkerDefsForColor(color))
   }
+  // An edge that crosses a subgraph's title text is not painted over the text
+  // (#1239). The mask is only emitted when some edge does, so a diagram with
+  // no such edge is unchanged.
+  const titleBoxes = titleTextBoxes(graph.groups, fontSizes)
+  const crossingEdges = new Set(
+    graph.edges.filter((e) => edgeCrossesTitle(e, titleBoxes)),
+  )
+  let titleGapMaskId: string | undefined
+  if (crossingEdges.size > 0) {
+    const mask = titleGapMask(titleBoxes, graph.width, graph.height)
+    titleGapMaskId = mask.id
+    parts.push(mask.markup)
+  }
   parts.push('</defs>')
 
   // 1. Subgraph backgrounds (group rectangles with header bands)
@@ -153,7 +167,14 @@ export function renderSvg(
   // 2. Edges (paths — rendered behind nodes)
   // Each edge is a <path> with semantic data-* attributes
   for (const edge of graph.edges) {
-    parts.push(renderEdge(edge, curve, animationEnabled))
+    parts.push(
+      renderEdge(
+        edge,
+        curve,
+        animationEnabled,
+        crossingEdges.has(edge) ? titleGapMaskId : undefined,
+      ),
+    )
   }
 
   // 3. Edge labels (positioned at midpoint of edge)
@@ -315,6 +336,7 @@ function renderEdge(
   edge: PositionedEdge,
   curve: CurveStyle,
   animationEnabled: boolean = true,
+  titleGapMaskId?: string,
 ): string {
   if (edge.points.length < 2) return ''
 
@@ -402,7 +424,9 @@ function renderEdge(
   return (
     f`<${curved ? 'path' : 'polyline'} ${dataAttrs.join(' ')} ${geometry} ` +
     f`fill="none" stroke="${strokeColor}" ` +
-    f`stroke-width="${strokeWidth}"${dashArray}${animatedDash}${markers} />`
+    f`stroke-width="${strokeWidth}"${dashArray}${animatedDash}${markers}` +
+    (titleGapMaskId ? f` mask="url(#${titleGapMaskId})"` : '') +
+    ' />'
   )
 }
 

package/src/sequence/layout.ts

@@ -10,6 +10,7 @@ import type {
   PositionedParticipantBox,
 } from '@zombie-mermaid/mermaid-parser'
 import type { RenderOptions, SequenceRenderOptions } from '@zombie-mermaid/core'
+import { measureMultilineText } from '@zombie-mermaid/core'
 import { estimateTextWidth, FONT_WEIGHTS, resolveFontSizes } from '../styles.ts'
 
 // ============================================================================
@@ -77,6 +78,32 @@ export function boxLabelHeight(labelFontSize: number): number {
   return labelFontSize + 8
 }
 
+/**
+ * Distance from the bottom of a stick-figure (`actor`) icon to the vertical
+ * centre of its label. Shared with the renderer so the label lands where the
+ * layout reserved room for it.
+ */
+export const ACTOR_LABEL_OFFSET = 14
+
+/** Clearance kept between an actor label and what sits below it, in px. */
+const ACTOR_LABEL_CLEARANCE = 4
+
+/**
+ * Distance from the bottom of a stick-figure icon to the bottom of its
+ * (possibly multi-line) label. Only `actor` participants draw a label below
+ * the icon; a `participant` box holds its label inside.
+ */
+function actorLabelBottom(
+  label: string,
+  fontSize: number,
+  fontWeight: number,
+): number {
+  return (
+    ACTOR_LABEL_OFFSET +
+    measureMultilineText(label, fontSize, fontWeight).height / 2
+  )
+}
+
 /** Resolved sequence-layout config — same shape as {@link SEQ} but mutable numbers. */
 type SeqConfig = { [K in keyof typeof SEQ]: number }
 
@@ -194,8 +221,32 @@ export function layoutSequenceDiagram(
     return positioned
   })
 
-  // 3. Stack messages vertically
-  let messageY = actorY + seq.actorHeight + seq.headerGap
+  // 3. Stack messages vertically. A stick-figure actor's label sits below its
+  //    icon, in the gap before the first message; widen the gap so the label
+  //    (and the first message's own label above its arrow) never touch.
+  //    Participants created mid-diagram are placed at their creating message
+  //    instead, so they don't take part in the header.
+  const actorLabelBottoms = diagram.actors.map((a) =>
+    a.type === 'actor'
+      ? actorLabelBottom(a.label, fontSizes.nodeLabel, FONT_WEIGHTS.nodeLabel)
+      : 0,
+  )
+  const headerLabelBottom = Math.max(
+    0,
+    ...diagram.actors.map((a, i) =>
+      a.createdAt === undefined ? actorLabelBottoms[i]! : 0,
+    ),
+  )
+  const firstMessageLabelRoom = fontSizes.edgeLabel + 12
+  let messageY =
+    actorY +
+    seq.actorHeight +
+    Math.max(
+      seq.headerGap,
+      headerLabelBottom > 0
+        ? headerLabelBottom + ACTOR_LABEL_CLEARANCE + firstMessageLabelRoom
+        : 0,
+    )
   const messages: PositionedMessage[] = []
 
   // Pre-scan blocks to determine which message indices need extra vertical
@@ -292,7 +343,9 @@ export function layoutSequenceDiagram(
     { startY: number; depth: number }[]
   >()
   const activations: Activation[] = []
-  const nestingOffset = 4 // Horizontal offset per nesting level
+  // Horizontal offset per nesting level: half a bar, as official Mermaid does,
+  // so a nested bar overlaps its parent by half instead of hiding behind it.
+  const nestingOffset = seq.activationWidth / 2
 
   /** Open an activation bar on `actorId` at row `y` (stacks for nesting). */
   function startActivation(actorId: string, y: number): void {
@@ -320,6 +373,7 @@ export function layoutSequenceDiagram(
       topY: startY,
       bottomY: y,
       width: seq.activationWidth,
+      depth,
     })
   }
 
@@ -488,10 +542,17 @@ export function layoutSequenceDiagram(
         topY: startY,
         bottomY: messageY - seq.messageRowHeight / 2,
         width: seq.activationWidth,
+        depth,
       })
     }
   }
 
+  // Paint outer bars before the bars nested inside them. Bars are pushed in
+  // close order, so an inner one otherwise precedes (and is covered by) its
+  // parent, which closes later. Array#sort is stable, so equal depths keep
+  // their order.
+  activations.sort((a, b) => a.depth - b.depth)
+
   // 4. Position blocks (loop/alt/opt)
   const blocks: PositionedBlock[] = diagram.blocks.map((block) => {
     // Block spans from the Y of startIndex to endIndex messages
@@ -664,7 +725,14 @@ export function layoutSequenceDiagram(
     const lifeline: Lifeline = {
       actorId: a.id,
       x: actorCenterX[i]!,
-      topY: actors[i]!.y + seq.actorHeight,
+      // A stick-figure actor's label sits on the lifeline's axis just below
+      // the icon, so the line starts under it rather than through it.
+      topY:
+        actors[i]!.y +
+        seq.actorHeight +
+        (actorLabelBottoms[i]! > 0
+          ? actorLabelBottoms[i]! + ACTOR_LABEL_CLEARANCE
+          : 0),
       bottomY:
         destroyedAt === undefined
           ? diagramBottom - seq.padding

package/src/sequence/renderer.ts

@@ -8,12 +8,13 @@ import type {
   PositionedNote,
   PositionedParticipantBox,
 } from '@zombie-mermaid/mermaid-parser'
-import { boxLabelHeight } from './layout.ts'
+import { ACTOR_LABEL_OFFSET, boxLabelHeight } from './layout.ts'
 import type { DiagramColors, SvgEmitOptions } from '@zombie-mermaid/core'
 import {
   svgOpenTag,
   buildStyleBlock,
   renderMultilineText,
+  measureMultilineText,
   escapeAttr,
   f,
 } from '@zombie-mermaid/core'
@@ -104,9 +105,11 @@ export function renderSequenceSvg(
     parts.push(renderBlock(block, fontSizes))
   }
 
-  // 2. Lifelines (dashed vertical lines from actor to bottom)
+  // 2. Lifelines (dashed vertical lines from actor to bottom), interrupted
+  //    where a message / block label sits on them so no line runs through text
+  const labelBoxes = collectLabelBoxes(diagram, fontSizes)
   for (const lifeline of diagram.lifelines) {
-    parts.push(renderLifeline(lifeline))
+    parts.push(renderLifeline(lifeline, labelBoxes))
   }
 
   // 3. Activation boxes
@@ -195,7 +198,7 @@ function renderActor(actor: PositionedActor, fontSizes: FontSizes): string {
         renderMultilineText(
           label,
           x,
-          y + height + 14,
+          y + height + ACTOR_LABEL_OFFSET,
           fontSizes.nodeLabel,
           f`font-size="${fontSizes.nodeLabel}" text-anchor="middle" font-weight="${FONT_WEIGHTS.nodeLabel}" fill="var(--_text)"`,
         ),
@@ -223,15 +226,152 @@ function renderActor(actor: PositionedActor, fontSizes: FontSizes): string {
   return parts.join('\n')
 }
 
+/** Self-message loop width, height, and the gap before its label, in px. */
+const SELF_LOOP_WIDTH = 30
+const SELF_LOOP_HEIGHT = 20
+const SELF_LABEL_PADDING = 8
+
+/** How far above its arrow a message label's centre sits, in px. */
+const MESSAGE_LABEL_RISE = 10
+
+/** Height of a block's type-label tab, in px. */
+const BLOCK_TAB_HEIGHT = 18
+
+/** A rectangle some text occupies; lifelines are cut around it. */
+interface LabelBox {
+  x0: number
+  x1: number
+  y0: number
+  y1: number
+}
+
+/** Breathing room kept between a label and the lifeline segments around it. */
+const LIFELINE_LABEL_PAD_X = 3
+const LIFELINE_LABEL_PAD_Y = 2
+
+/** Lifeline fragments shorter than this are dropped rather than drawn as a stub. */
+const LIFELINE_MIN_SEGMENT = 3
+
+/**
+ * Footprints of every text label a lifeline can run through: message labels
+ * (above the arrow, or beside a self-message loop), the block type tab, and
+ * block divider (`else` / `and`) labels. Mirrors the positions
+ * {@link renderMessage} and {@link renderBlock} draw them at (#1242).
+ */
+function collectLabelBoxes(
+  diagram: PositionedSequenceDiagram,
+  fontSizes: FontSizes,
+): LabelBox[] {
+  const boxes: LabelBox[] = []
+  const measure = (text: string) =>
+    measureMultilineText(text, fontSizes.edgeLabel, FONT_WEIGHTS.edgeLabel)
+  const centred = (text: string, cx: number, cy: number) => {
+    const m = measure(text)
+    boxes.push({
+      x0: cx - m.width / 2,
+      x1: cx + m.width / 2,
+      y0: cy - m.height / 2,
+      y1: cy + m.height / 2,
+    })
+  }
+  const startAnchored = (text: string, x: number, cy: number) => {
+    const m = measure(text)
+    boxes.push({
+      x0: x,
+      x1: x + m.width,
+      y0: cy - m.height / 2,
+      y1: cy + m.height / 2,
+    })
+  }
+
+  for (const msg of diagram.messages) {
+    if (!msg.label) continue
+    if (msg.isSelf) {
+      startAnchored(
+        msg.label,
+        msg.x1 + SELF_LOOP_WIDTH + SELF_LABEL_PADDING,
+        msg.y + SELF_LOOP_HEIGHT / 2,
+      )
+    } else {
+      centred(msg.label, (msg.x1 + msg.x2) / 2, msg.y - MESSAGE_LABEL_RISE)
+    }
+  }
+
+  for (const block of diagram.blocks) {
+    const tab = `${block.type}${block.label ? ` [${block.label}]` : ''}`
+    const tabWidth =
+      estimateTextWidth(
+        tab.split('\n')[0] ?? '',
+        fontSizes.edgeLabel,
+        FONT_WEIGHTS.groupHeader,
+      ) + 16
+    boxes.push({
+      x0: block.x,
+      x1: block.x + tabWidth,
+      y0: block.y,
+      y1: block.y + BLOCK_TAB_HEIGHT,
+    })
+    for (const divider of block.dividers) {
+      if (!divider.label) continue
+      startAnchored(`[${divider.label}]`, block.x + 8, divider.y + 14)
+    }
+  }
+  return boxes
+}
+
 /**
- * Render a lifeline (dashed vertical line from actor to bottom).
+ * The y-ranges of `lifeline` left after cutting out every label box it
+ * crosses, as `[y0, y1]` pairs top to bottom.
+ */
+function lifelineSegments(
+  lifeline: Lifeline,
+  labelBoxes: readonly LabelBox[],
+): Array<[number, number]> {
+  const cuts = labelBoxes
+    .filter(
+      (b) =>
+        lifeline.x > b.x0 - LIFELINE_LABEL_PAD_X &&
+        lifeline.x < b.x1 + LIFELINE_LABEL_PAD_X &&
+        b.y1 + LIFELINE_LABEL_PAD_Y > lifeline.topY &&
+        b.y0 - LIFELINE_LABEL_PAD_Y < lifeline.bottomY,
+    )
+    .map((b): [number, number] => [
+      b.y0 - LIFELINE_LABEL_PAD_Y,
+      b.y1 + LIFELINE_LABEL_PAD_Y,
+    ])
+    .sort((a, b) => a[0] - b[0])
+
+  const segments: Array<[number, number]> = []
+  let cursor = lifeline.topY
+  for (const [c0, c1] of cuts) {
+    if (c0 - cursor >= LIFELINE_MIN_SEGMENT) segments.push([cursor, c0])
+    cursor = Math.max(cursor, c1)
+  }
+  if (lifeline.bottomY - cursor >= LIFELINE_MIN_SEGMENT) {
+    segments.push([cursor, lifeline.bottomY])
+  }
+  // A lifeline entirely under a label (or otherwise shorter than a stub)
+  // would vanish; keep it whole rather than drop the participant's line.
+  return segments.length > 0 ? segments : [[lifeline.topY, lifeline.bottomY]]
+}
+
+/**
+ * Render a lifeline (dashed vertical line from actor to bottom), as one
+ * `<line>` per stretch between label boxes it would otherwise pass through.
  * Includes data-actor to link to its actor.
  */
-function renderLifeline(lifeline: Lifeline): string {
-  const line =
-    f`<line class="lifeline" data-actor="${escapeAttr(lifeline.actorId)}" ` +
-    f`x1="${lifeline.x}" y1="${lifeline.topY}" x2="${lifeline.x}" y2="${lifeline.bottomY}" ` +
-    `stroke="var(--_line)" stroke-width="0.75" stroke-dasharray="6 4" />`
+function renderLifeline(
+  lifeline: Lifeline,
+  labelBoxes: readonly LabelBox[],
+): string {
+  const line = lifelineSegments(lifeline, labelBoxes)
+    .map(
+      ([y0, y1]) =>
+        f`<line class="lifeline" data-actor="${escapeAttr(lifeline.actorId)}" ` +
+        f`x1="${lifeline.x}" y1="${y0}" x2="${lifeline.x}" y2="${y1}" ` +
+        `stroke="var(--_line)" stroke-width="0.75" stroke-dasharray="6 4" />`,
+    )
+    .join('\n')
   if (!lifeline.destroyed) return line
   // `destroy X`: the lifeline ends at the destroying message's row, marked
   // with a cross centred on it — the same glyph Mermaid uses. Drawn in the
@@ -287,9 +427,9 @@ function renderMessage(msg: PositionedMessage, fontSizes: FontSizes): string {
   if (msg.isSelf) {
     // Self-message: curved loop going right and back
     // Loop dimensions - loopH is fixed, loopW provides minimum clearance
-    const loopW = 30
-    const loopH = 20
-    const labelPadding = 8 // Space between loop and label
+    const loopW = SELF_LOOP_WIDTH
+    const loopH = SELF_LOOP_HEIGHT
+    const labelPadding = SELF_LABEL_PADDING // Space between loop and label
     parts.push(
       f`  <polyline points="${msg.x1},${msg.y} ${msg.x1 + loopW},${msg.y} ${msg.x1 + loopW},${msg.y + loopH} ${msg.x2},${msg.y + loopH}" ` +
         f`fill="none" stroke="var(--_line)" stroke-width="${STROKE_WIDTHS.connector}"${dashArray} marker-end="url(#${markerId})"${markerStart} />`,
@@ -318,7 +458,7 @@ function renderMessage(msg: PositionedMessage, fontSizes: FontSizes): string {
         renderMultilineText(
           msg.label,
           midX,
-          msg.y - 10,
+          msg.y - MESSAGE_LABEL_RISE,
           fontSizes.edgeLabel,
           f`font-size="${fontSizes.edgeLabel}" text-anchor="middle" font-weight="${FONT_WEIGHTS.edgeLabel}" fill="var(--_text-muted)"`,
         ),
@@ -455,7 +595,7 @@ function renderBlock(block: PositionedBlock, fontSizes: FontSizes): string {
       fontSizes.edgeLabel,
       FONT_WEIGHTS.groupHeader,
     ) + 16
-  const tabHeight = 18
+  const tabHeight = BLOCK_TAB_HEIGHT
 
   parts.push(
     f`  <rect x="${block.x}" y="${block.y}" width="${tabWidth}" height="${tabHeight}" ` +

package/src/title-gaps.ts

@@ -0,0 +1,146 @@
+/**
+ * Break an edge where it crosses a subgraph's title text.
+ *
+ * Layout treats a subgraph's title bar as plain padding, so an edge that
+ * enters a box from above can run straight over the title. mermaid.js draws
+ * such an edge through the text as well; here the edge is simply not painted
+ * over the text itself, and picks up again on the other side. The edge stays
+ * one element with its geometry untouched: a `<mask>` hides the stroke inside
+ * the text box (#1239).
+ */
+
+import { measureMultilineText } from '@zombie-mermaid/core'
+import type {
+  PositionedEdge,
+  PositionedGroup,
+  Point,
+} from '@zombie-mermaid/core'
+import type { FontSizes } from './styles.ts'
+import { FONT_WEIGHTS } from './styles.ts'
+
+/** Left inset of the title text inside the box, matching `renderGroup`. */
+const TITLE_TEXT_INSET = 12
+
+/** Space left clear around the title text, in px. */
+const GAP_PADDING = 2
+
+export interface TitleTextBox {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+function flattenGroups(groups: PositionedGroup[]): PositionedGroup[] {
+  return groups.flatMap((g) => [g, ...flattenGroups(g.children)])
+}
+
+/** The rectangle each subgraph's title text occupies, padded by `GAP_PADDING`. */
+export function titleTextBoxes(
+  groups: PositionedGroup[],
+  fontSizes: FontSizes,
+): TitleTextBox[] {
+  const headerHeight = fontSizes.groupHeader + 16
+  return flattenGroups(groups)
+    .filter((g) => g.label !== '')
+    .map((g) => {
+      const text = measureMultilineText(
+        g.label,
+        fontSizes.groupHeader,
+        FONT_WEIGHTS.groupHeader,
+      )
+      return {
+        x: g.x + TITLE_TEXT_INSET - GAP_PADDING,
+        y: g.y + headerHeight / 2 - text.height / 2 - GAP_PADDING,
+        width: text.width + 2 * GAP_PADDING,
+        height: text.height + 2 * GAP_PADDING,
+      }
+    })
+}
+
+/** Whether the segment a-b touches the rectangle (Liang-Barsky clipping). */
+function segmentHitsBox(a: Point, b: Point, box: TitleTextBox): boolean {
+  const dx = b.x - a.x
+  const dy = b.y - a.y
+  const p = [-dx, dx, -dy, dy]
+  const q = [
+    a.x - box.x,
+    box.x + box.width - a.x,
+    a.y - box.y,
+    box.y + box.height - a.y,
+  ]
+  let t0 = 0
+  let t1 = 1
+  for (let i = 0; i < 4; i++) {
+    const pi = p[i]!
+    const qi = q[i]!
+    if (pi === 0) {
+      if (qi < 0) return false
+    } else {
+      const t = qi / pi
+      if (pi < 0) t0 = Math.max(t0, t)
+      else t1 = Math.min(t1, t)
+      if (t0 > t1) return false
+    }
+  }
+  return true
+}
+
+/** Whether any segment of `edge` passes through any of the `boxes`. */
+export function edgeCrossesTitle(
+  edge: PositionedEdge,
+  boxes: TitleTextBox[],
+): boolean {
+  const pts = edge.points
+  for (let i = 0; i + 1 < pts.length; i++) {
+    if (boxes.some((box) => segmentHitsBox(pts[i]!, pts[i + 1]!, box))) {
+      return true
+    }
+  }
+  return false
+}
+
+/** Small stable hash (FNV-1a) for a mask id that is the same for the same boxes. */
+function hashBoxes(boxes: TitleTextBox[]): string {
+  let h = 0x811c9dc5
+  for (const ch of boxes
+    .map((b) => `${b.x},${b.y},${b.width},${b.height}`)
+    .join(';')) {
+    h = Math.imul(h ^ ch.charCodeAt(0), 0x01000193)
+  }
+  return (h >>> 0).toString(36)
+}
+
+export interface TitleGapMask {
+  id: string
+  /** The `<mask>` element, for `<defs>`. */
+  markup: string
+}
+
+/**
+ * The mask that hides edge strokes inside `boxes`. The id comes from the box
+ * positions, so two inline diagrams never share an id with different content.
+ *
+ * `maskUnits="userSpaceOnUse"` is required: the default bounding-box units
+ * give a straight vertical or horizontal edge a zero-size box, which masks the
+ * whole edge away.
+ */
+export function titleGapMask(
+  boxes: TitleTextBox[],
+  width: number,
+  height: number,
+): TitleGapMask {
+  const id = `zm-title-gap-${hashBoxes(boxes)}`
+  const holes = boxes
+    .map(
+      (b) =>
+        `    <rect x="${b.x}" y="${b.y}" width="${b.width}" height="${b.height}" fill="#000" />`,
+    )
+    .join('\n')
+  const markup =
+    `  <mask id="${id}" maskUnits="userSpaceOnUse" x="0" y="0" width="${width}" height="${height}">\n` +
+    `    <rect x="0" y="0" width="${width}" height="${height}" fill="#fff" />\n` +
+    `${holes}\n` +
+    `  </mask>`
+  return { id, markup }
+}

package/src/xychart/layout.ts

@@ -489,16 +489,45 @@ function getCategoryLabels(chart: XYChart, count: number): string[] {
   return Array.from({ length: count }, (_, i) => String(i + 1))
 }
 
+/** Minimum clear space between two neighbouring x-axis labels. */
+const X_LABEL_MIN_GAP = 8
+
+/**
+ * Step between shown x-axis labels: 1 when every pair of neighbouring labels
+ * keeps `X_LABEL_MIN_GAP` of clear space, otherwise the smallest n for which
+ * every pair of shown (every n-th) labels does. Checked pairwise on the real
+ * widths so one long label doesn't thin out an otherwise roomy axis.
+ */
+export function xLabelStep(labels: string[], bandWidth: number): number {
+  const widths = labels.map((l) =>
+    estimateTextWidth(l, XY.axisLabelFontSize, XY.axisLabelFontWeight),
+  )
+  for (let step = 1; step < labels.length; step++) {
+    let fits = true
+    for (let i = 0; i + step < labels.length; i += step) {
+      const gap = step * bandWidth - (widths[i]! + widths[i + step]!) / 2
+      if (gap < X_LABEL_MIN_GAP) {
+        fits = false
+        break
+      }
+    }
+    if (fits) return step
+  }
+  return Math.max(1, labels.length)
+}
+
 function buildXTicks(
   chart: XYChart,
   xScale: (i: number) => number,
   axisY: number,
-  _bandWidth: number,
+  bandWidth: number,
 ): AxisTick[] {
   const count = getDataCount(chart)
   const labels = getCategoryLabels(chart, count)
+  const step = xLabelStep(labels, bandWidth)
+  // Dropped labels keep their tick mark but render no text.
   return labels.map((label, i) => ({
-    label,
+    label: i % step === 0 ? label : '',
     x: xScale(i),
     y: axisY,
     tx: xScale(i),