zombie-mermaid 2.2.2 → 2.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zombie-mermaid",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "license": "MIT",
   "description": "Render Mermaid diagrams as beautiful SVGs or ASCII art. Ultra-fast, fully themeable, zero DOM dependencies. Maintained fork of beautiful-mermaid.",
   "type": "module",
@@ -129,8 +129,8 @@
     "@zombie-mermaid/ascii-renderer": "2.2.0",
     "@zombie-mermaid/core": "2.2.0",
     "@zombie-mermaid/mcp": "2.2.0",
-    "@zombie-mermaid/mermaid-parser": "2.2.0",
-    "@zombie-mermaid/svg-renderer": "2.2.0"
+    "@zombie-mermaid/svg-renderer": "2.2.0",
+    "@zombie-mermaid/mermaid-parser": "2.2.0"
   },
   "optionalDependencies": {
     "@resvg/resvg-js": "^2.6.2"

package/packages/ascii-renderer/src/class-diagram.ts

@@ -563,35 +563,215 @@ export function renderClassAscii(
     const group = levelGroups[lv]!
     if (group.length === 0) continue
 
+    // --- #970's block-based x-assignment (issues #971, #972) ---
+    // docs/decisions/ascii-class-diagram-x-coordinate-assignment-970.md.
+    // Alignment blocks group classes at this level sharing the exact same
+    // parent-id set, processed as a unit. A block's *qualifying* parents
+    // are the subset strictly shallower than this level — a parent at the
+    // same level (a rootless relationship cycle, whose members still
+    // record each other as "parents" in `parents` even though nothing
+    // above them ever resolves) never qualifies. A block with zero
+    // qualifying parents has "no resolvable parents" and every member
+    // keeps its plain left-to-right baseline position, computed
+    // individually (not as a joint unit — #971's exact per-class
+    // behavior, preserved verbatim for this shape, including when a
+    // no-resolvable-parents block's members happen not to be declaration-
+    // adjacent). A block with at least one qualifying parent computes a
+    // real desired center: the mean of its qualifying parents' own,
+    // already-placed box centers (a single qualifying parent's mean is
+    // just that parent's center — the #964 repro exactly, #971's case; a
+    // block of more than one class sharing that parent set spreads evenly
+    // by centering the block's *total* width on that shared center, #972's
+    // "multiple children of one parent" case; more than one qualifying
+    // parent averages their centers, #972's "converging edges" case).
+    // Either way, the block's desired *left* edge (its slot-space left,
+    // matching `currentX`'s role below) is `desiredCenter -
+    // floor(totalWidth / 2)` — floor chosen only for determinism. A single
+    // left-to-right compaction pass then resolves any collision between
+    // *any* two blocks' desired positions — universal across every block
+    // shape, not just multi-parent ones, since two independently-aligned
+    // singleton blocks can still want overlapping positions (#971) — by
+    // only ever pushing a block right of its desired position, never left,
+    // and never reordering blocks relative to each other.
+    //
+    // A class with no parents at all is always its own singleton block —
+    // two unrelated roots must never be merged into one block just because
+    // both happen to have an empty parent set; there is nothing shared to
+    // align them around.
+    const blockKeyOf = (id: string): string => {
+      const pset = parents.get(id)
+      return pset && pset.size > 0 ? [...pset].sort().join(',') : `root:${id}`
+    }
+    // Every member sharing a given block key, regardless of adjacency in
+    // `group` — looked up once a block is actually confirmed to have a
+    // shared center to align around (see the main loop below). Building
+    // this eagerly for every id up front, and processing every block's
+    // *entire* membership together the moment its first (in declaration
+    // order) member is reached — even for a block with no resolvable
+    // parents — used to silently reorder an unrelated class that was
+    // declared between two same-parent-set siblings ahead of it, moving it
+    // visually later than its own declaration position (caught in review
+    // on #972). The main loop below only merges members into one placement
+    // unit for a block that actually resolves to a shared center; a
+    // no-resolvable-parents "block" is never merged, so it can't reorder
+    // anything.
+    const blockMembers = new Map<string, string[]>()
+    for (const id of group) {
+      const key = blockKeyOf(id)
+      let members = blockMembers.get(key)
+      if (!members) {
+        members = []
+        blockMembers.set(key, members)
+      }
+      members.push(id)
+    }
+
+    // Baseline: today's plain left-to-right slot position for every class
+    // in this level, computed exactly as the pre-#971 algorithm did — the
+    // fallback position for a no-resolvable-parents block's members, and
+    // the starting point the compaction step below can only ever push
+    // right of, never left.
+    const baselineSlotLeft = new Map<string, number>()
+    const slotWidthOf = new Map<string, number>()
+    const leftPadOf = new Map<string, number>()
+    {
+      let x = 0
+      for (const id of group) {
+        const w = classBoxW.get(id)!
+        // The box's center column sits `floor(w / 2)` cells from its left
+        // edge (the same arithmetic `connectionColumns` uses), so anything
+        // reaching further than that past the center overhangs the box.
+        const reach = columnReach.get(id)!
+        const leftPad = Math.max(0, reach.left - Math.floor(w / 2))
+        const rightPad = Math.max(0, reach.right - (w - 1 - Math.floor(w / 2)))
+        baselineSlotLeft.set(id, x)
+        slotWidthOf.set(id, leftPad + w + rightPad)
+        leftPadOf.set(id, leftPad)
+        x += leftPad + w + rightPad + hGap
+      }
+    }
+
     let currentX = 0
     let maxH = 0
 
-    for (const id of group) {
+    /** Places one class's box at slot-left `slotLeft`, advancing `currentX`/`maxH`/`maxSlotEnd`. */
+    const placeAt = (id: string, slotLeft: number): void => {
       const cls = classById.get(id)!
       const w = classBoxW.get(id)!
       const h = classBoxH.get(id)!
-      // The box's center column sits `floor(w / 2)` cells from its left
-      // edge (the same arithmetic `connectionColumns` uses), so anything
-      // reaching further than that past the center overhangs the box.
-      const reach = columnReach.get(id)!
-      const leftPad = Math.max(0, reach.left - Math.floor(w / 2))
-      const rightPad = Math.max(0, reach.right - (w - 1 - Math.floor(w / 2)))
+      const leftPad = leftPadOf.get(id)!
+      const slotWidth = slotWidthOf.get(id)!
       placed.set(id, {
         cls,
         sections: classSections.get(id)!,
         // Shifted right only by the left overhang, so a box with nothing
-        // reaching past its left edge lands exactly where it always has.
-        x: currentX + leftPad,
+        // reaching past its left edge lands exactly where its slot does.
+        x: slotLeft + leftPad,
         y: currentY,
         width: w,
         height: h,
       })
-      const slotWidth = leftPad + w + rightPad
-      maxSlotEnd = Math.max(maxSlotEnd, currentX + slotWidth)
-      currentX += slotWidth + hGap
+      maxSlotEnd = Math.max(maxSlotEnd, slotLeft + slotWidth)
+      currentX = slotLeft + slotWidth + hGap
       maxH = Math.max(maxH, h)
     }
 
+    const placedThisLevel = new Set<string>()
+    for (const id of group) {
+      // Already placed as part of an earlier qualifying block's joint
+      // placement below (never true for a no-resolvable-parents id, which
+      // is always placed the moment the loop reaches it, in its own true
+      // declaration-order turn).
+      if (placedThisLevel.has(id)) continue
+
+      const key = blockKeyOf(id)
+      const pset = parents.get(id)
+      // `level.get(pid)!`: every relationship endpoint is guaranteed a
+      // `classById`/`level` entry (the parser's `ensureClass` auto-creates
+      // an implicit class for any id used only as a relationship endpoint,
+      // never just a dangling reference — see `classById.has(...)`'s own
+      // guards elsewhere in this file, which protect a *different* case),
+      // so this is never actually missing.
+      const qualifying = pset
+        ? [...pset].filter((pid) => level.get(pid)! < lv)
+        : []
+
+      if (qualifying.length === 0) {
+        // No resolvable parents: this id has no shared center to align
+        // around, so it is never merged into a joint block with the other
+        // members `blockKeyOf` groups it with — only *this* id is placed
+        // here, in its own true position in `group`'s declaration order,
+        // exactly matching #971's per-class behavior for this shape. Any
+        // other same-key member is placed independently, on its own later
+        // turn through this same loop — merging them together here would
+        // reorder whatever was declared between them ahead of its own
+        // declaration position (issue caught in #972's review).
+        const slotLeft = Math.max(baselineSlotLeft.get(id)!, currentX, 0)
+        placeAt(id, slotLeft)
+        placedThisLevel.add(id)
+        continue
+      }
+
+      // A block with a real shared center to align around *is* placed as
+      // a joint unit, gathering every member `blockKeyOf` groups with it
+      // regardless of adjacency in `group` — the whole reason to group
+      // same-parent-set siblings together in the first place.
+      const members = blockMembers.get(key)!
+
+      // `placed.get(...)!`: every id in `qualifying` has a strictly-
+      // shallower level than `lv`, and this loop places every class of a
+      // level before moving to the next, so a strictly-shallower class is
+      // always already placed by the time this level is processed.
+      // "Center column" is always a box's own rendered center, never the
+      // reach-padded slot's — aligning to the slot center instead would
+      // visually misalign the boxes whenever a relationship's label
+      // overhang is asymmetric.
+      const parentCenters = qualifying.map((pid) => {
+        const p = placed.get(pid)!
+        return p.x + Math.floor(p.width / 2)
+      })
+      const desiredCenter = Math.round(
+        parentCenters.reduce((sum, c) => sum + c, 0) / parentCenters.length,
+      )
+
+      let totalWidth = 0
+      for (let i = 0; i < members.length; i++) {
+        totalWidth += slotWidthOf.get(members[i]!)!
+        if (i < members.length - 1) totalWidth += hGap
+      }
+      // `totalWidth` is the *slot* span (every member's own reach padding
+      // included at both ends), but the thing that must visually center on
+      // `desiredCenter` is the *rendered box* span — from the first
+      // member's own box left edge to the last member's own box right
+      // edge, which excludes the outermost reach padding at each end (that
+      // padding only ever separates a box from a *neighbor*; at the
+      // block's own two ends there is no neighbor to separate from, so it
+      // just becomes asymmetric dead space that would otherwise skew the
+      // visible boxes off `desiredCenter` whenever the first member's
+      // leftPad differs from the last member's rightPad — e.g. one child
+      // has a long incoming label reserving room on its own left, the
+      // other has none). Subtracting them back out here, once, is cheaper
+      // than threading a separate "visible width" accumulator through the
+      // loop above (caught in #972's review).
+      const firstLeftPad = leftPadOf.get(members[0]!)!
+      const lastMember = members[members.length - 1]!
+      const lastRightPad =
+        slotWidthOf.get(lastMember)! -
+        leftPadOf.get(lastMember)! -
+        classBoxW.get(lastMember)!
+      const visibleWidth = totalWidth - firstLeftPad - lastRightPad
+      const blockDesiredLeft =
+        desiredCenter - firstLeftPad - Math.floor(visibleWidth / 2)
+      const blockActualLeft = Math.max(blockDesiredLeft, currentX, 0)
+
+      let memberX = blockActualLeft
+      for (const memberId of members) {
+        placeAt(memberId, memberX)
+        placedThisLevel.add(memberId)
+        memberX = currentX
+      }
+    }
+
     currentY += maxH + vGap
   }
 

package/packages/ascii-renderer/src/sequence.ts

@@ -276,14 +276,33 @@ export function renderSequenceAscii(
   // message-label sizing happened to leave).
   const leftNoteWidth: number[] = new Array(diagram.actors.length).fill(0)
   const rightNoteWidth: number[] = new Array(diagram.actors.length).fill(0)
+  // A single-actor `over` note draws centered on that actor's own lifeline
+  // (see the note-x calculation below): `Math.floor(w / 2)` columns land to
+  // its left, the rest to its right. Neither half was reserved during gap
+  // sizing before this fix, so a note wider than the actor's own column
+  // silently spilled into whichever neighbour was closer (issue #992) — the
+  // same problem left/rightNoteWidth above already solved for `left`/
+  // `right` notes, just for the two halves of a centered one instead. A
+  // multi-actor `over` note (`Note over Alice,Bob`) is excluded on purpose:
+  // spanning both actors' columns is its intended shape, not a collision.
+  const overNoteHalfLeft: number[] = new Array(diagram.actors.length).fill(0)
+  const overNoteHalfRight: number[] = new Array(diagram.actors.length).fill(0)
   for (const note of diagram.notes) {
-    if (note.position !== 'left' && note.position !== 'right') continue
-    const aIdx = actorIdx.get(note.actorIds[0]!) ?? 0
-    const w = noteBoxWidth(note)
-    if (note.position === 'left') {
-      leftNoteWidth[aIdx] = Math.max(leftNoteWidth[aIdx]!, w)
-    } else {
-      rightNoteWidth[aIdx] = Math.max(rightNoteWidth[aIdx]!, w)
+    if (note.position === 'left' || note.position === 'right') {
+      const aIdx = actorIndexOf(note.actorIds[0]!)
+      const w = noteBoxWidth(note)
+      if (note.position === 'left') {
+        leftNoteWidth[aIdx] = Math.max(leftNoteWidth[aIdx]!, w)
+      } else {
+        rightNoteWidth[aIdx] = Math.max(rightNoteWidth[aIdx]!, w)
+      }
+    } else if (note.position === 'over' && note.actorIds.length === 1) {
+      const aIdx = actorIndexOf(note.actorIds[0]!)
+      const w = noteBoxWidth(note)
+      const halfLeft = Math.floor(w / 2)
+      const halfRight = w - halfLeft
+      overNoteHalfLeft[aIdx] = Math.max(overNoteHalfLeft[aIdx]!, halfLeft)
+      overNoteHalfRight[aIdx] = Math.max(overNoteHalfRight[aIdx]!, halfRight)
     }
   }
 
@@ -312,6 +331,11 @@ export function renderSequenceAscii(
     Math.max(
       halfBox[0]! + (boxSpanOf[0] === -1 ? 0 : BRACKET_GAP + 1),
       leftNoteWidth[0]! + 1,
+      // A single-actor `over` note on the leftmost actor has no left
+      // neighbour either — same reasoning as the `left`-note case just
+      // above, but for the note's own left half (`nx = llX[0] -
+      // overNoteHalfLeft[0]` must stay >= 0; issue #992).
+      overNoteHalfLeft[0]!,
     ),
   ]
   for (let i = 1; i < diagram.actors.length; i++) {
@@ -329,7 +353,17 @@ export function renderSequenceAscii(
     // so a wide note doesn't overflow into the neighbouring lifeline. The
     // `+2` mirrors adjMaxWidth's own margin below and matches the 1-column
     // clearance the note-x calculation already leaves on the lifeline side.
-    const noteGapNeed = Math.max(rightNoteWidth[i - 1]!, leftNoteWidth[i]!) + 2
+    // A single-actor `over` note on either actor reaches into this same gap
+    // from its own side (its right half from i-1, its left half from i) —
+    // issue #992, folded into the same max() rather than summed, matching
+    // how the left/right pair above is already handled.
+    const noteGapNeed =
+      Math.max(
+        rightNoteWidth[i - 1]!,
+        leftNoteWidth[i]!,
+        overNoteHalfRight[i - 1]!,
+        overNoteHalfLeft[i]!,
+      ) + 2
     const gap = Math.max(
       halfBox[i - 1]! + halfBox[i]! + 2 + wallExtra,
       adjMaxWidth[i - 1]! + 2,

package/src/__tests__/ascii-class-box-occupancy.test.ts

@@ -137,70 +137,109 @@ ${manyAttrs('b', 6)}
   // pair via the level-BFS (Root has no parent, Kid is its level-1 child),
   // placed on a different row from the Alpha/Mid/Charlie cycle.
   //
-  // Two orderings of the same Root/Kid pair are compared: declaring Root
-  // first places Kid's column off to the side, outside the Alpha-to-Charlie
-  // detour span; declaring Root between Alpha and Mid places Kid's column
-  // so it overlaps Alpha's own range instead (confirmed below via
-  // `findBoxRect`). If the different-row filter worked, both orderings
+  // Two variants of the same Root/Kid pair are compared: a narrow `Kid`
+  // never reaches the cycle's column span (baseline); a `Kid` wide enough
+  // to need real space, with `Root` declared right after `Alpha`, overlaps
+  // Alpha's (and Mid's) column range instead (confirmed below via
+  // `findBoxRect`). If the different-row filter worked, both variants
   // render the cycle identically — Root/Kid's actual row is irrelevant to
-  // it either way. A test that only used the non-overlapping ordering would
+  // it either way. A test that only used the non-overlapping variant would
   // pass even with the filter deleted (verified: an earlier version of this
   // test did exactly that, and CodeRabbit correctly flagged it as not
-  // actually exercising the filter — see the PR discussion). Sabotage-
-  // verified: deleting the filter leaves both orderings' `+ bN: String`
-  // lines intact but makes the overlapping ordering one row taller than the
-  // non-overlapping one (19 vs. 18), which the equality assertion below
+  // actually exercising the filter — see the PR discussion).
+  //
+  // Declaration order alone no longer controls Kid's column (issue #971:
+  // `Kid`, as the sole occupant of its level with exactly one qualifying
+  // parent, now aligns under Root's own — already-placed — column instead
+  // of always landing at the leftmost slot). This test used to force the
+  // overlapping/non-overlapping split by moving `Root`/`Kid`'s declaration
+  // point around the cycle alone; that no longer produces reliably
+  // different geometry, since Kid's position now tracks wherever Root
+  // ends up rather than its own declaration slot. Widening `Kid` (so its
+  // box needs more room than the gap next to Root provides) is what
+  // reliably produces a real overlap now, confirmed empirically against
+  // the current renderer rather than assumed.
+  //
+  // Sabotage-verified: deleting the filter leaves both variants' `+ bN:
+  // String` lines intact but makes the overlapping variant one row taller
+  // than the baseline (19 vs. 18), which the equality assertion below
   // catches.
   it('3-node cycle, unrelated Root->Kid pair on a different level: obstruction search ignores it regardless of whether it overlaps the detour span', () => {
-    function withRootKid(rootDeclaredBetweenAlphaAndMid: boolean): string {
-      const rootAndKid = `  class Root
+    // Baseline: Root/Kid declared after the whole cycle, Kid narrow enough
+    // to never need more room than the gap next to Root provides.
+    const nonOverlapping = renderMermaidASCII(
+      `classDiagram
+  class Alpha
+  class Mid {
+${manyAttrs('b', 6)}
+  }
+  class Charlie
+  class Root
   class Kid
-`
-      return `classDiagram
-${rootDeclaredBetweenAlphaAndMid ? '' : rootAndKid}  class Alpha
-${rootDeclaredBetweenAlphaAndMid ? rootAndKid : ''}  class Mid {
+  Alpha --> Mid
+  Mid --> Charlie
+  Charlie --> Alpha
+  Root --> Kid`,
+      { useAscii: true },
+    )
+    // Overlapping: Root declared immediately after Alpha, Kid wide enough
+    // that centering it under Root's (narrow) column reaches into Alpha's.
+    const overlapping = renderMermaidASCII(
+      `classDiagram
+  class Alpha
+  class Root
+  class VeryLongKidName
+  class Mid {
 ${manyAttrs('b', 6)}
   }
   class Charlie
   Alpha --> Mid
   Mid --> Charlie
   Charlie --> Alpha
-  Root --> Kid`
-    }
-
-    const nonOverlapping = renderMermaidASCII(withRootKid(false), {
-      useAscii: true,
-    })
-    const overlapping = renderMermaidASCII(withRootKid(true), {
-      useAscii: true,
-    })
+  Root --> VeryLongKidName`,
+      { useAscii: true },
+    )
 
     // Confirms the geometry this test relies on: in the "overlapping"
-    // ordering, Kid really does sit on a different row from the cycle, and
+    // variant, Kid really does sit on a different row from the cycle, and
     // really does overlap Alpha's own column range (i.e. the obstruction
     // search has something to incorrectly notice if the different-row
-    // filter is missing); in the "non-overlapping" ordering, it doesn't.
+    // filter is missing); in the baseline, it doesn't.
     const overlappingAlphaRect = findBoxRect(overlapping, 'Alpha')
-    const overlappingKidRect = findBoxRect(overlapping, 'Kid')
+    const overlappingKidRect = findBoxRect(overlapping, 'VeryLongKidName')
     expect(overlappingKidRect.y0).toBeGreaterThan(overlappingAlphaRect.y1)
-    expect(overlappingKidRect.x0).toBeLessThan(overlappingAlphaRect.x1)
+    expect(overlappingKidRect.x0).toBeLessThanOrEqual(overlappingAlphaRect.x1)
     const nonOverlappingAlphaRect = findBoxRect(nonOverlapping, 'Alpha')
     const nonOverlappingKidRect = findBoxRect(nonOverlapping, 'Kid')
-    expect(nonOverlappingKidRect.x1).toBeLessThanOrEqual(
-      nonOverlappingAlphaRect.x0,
-    )
+    expect(
+      nonOverlappingKidRect.x1 < nonOverlappingAlphaRect.x0 ||
+        nonOverlappingKidRect.x0 > nonOverlappingAlphaRect.x1,
+    ).toBe(true)
 
-    for (const ascii of [nonOverlapping, overlapping]) {
-      expectAllPresentOnce(ascii, [
-        '+ b0: String',
-        '+ b1: String',
-        '+ b2: String',
-        '+ b3: String',
-        '+ b4: String',
-        '+ b5: String',
-      ])
-      expectNoBoxOverlap(ascii, ['Alpha', 'Mid', 'Charlie', 'Root', 'Kid'])
-    }
+    expectAllPresentOnce(nonOverlapping, [
+      '+ b0: String',
+      '+ b1: String',
+      '+ b2: String',
+      '+ b3: String',
+      '+ b4: String',
+      '+ b5: String',
+    ])
+    expectNoBoxOverlap(nonOverlapping, [
+      'Alpha',
+      'Mid',
+      'Charlie',
+      'Root',
+      'Kid',
+    ])
+    expectAllPresentOnce(overlapping, [
+      '+ b0: String',
+      '+ b1: String',
+      '+ b2: String',
+      '+ b3: String',
+      '+ b4: String',
+      '+ b5: String',
+    ])
+    expectNoBoxOverlap(overlapping, ['Alpha', 'Mid', 'Charlie', 'Root'])
 
     // The real check: Kid overlapping the detour span must not change the
     // cycle's own rendered height compared to Kid sitting clear of it.

package/src/__tests__/ascii-class-detour-label-routing-487.test.ts

@@ -26,6 +26,7 @@
 
 import { describe, it, expect } from 'vitest'
 import { renderMermaidASCII } from '@zombie-mermaid/ascii-renderer'
+import { findBoxRect } from './helpers/ascii-form.ts'
 
 const MVC_SOURCE = `classDiagram
   class Model {
@@ -85,17 +86,16 @@ describe('ASCII class diagram — detour-aware relationship label placement (iss
     const ascii = renderMermaidASCII(MVC_SOURCE, { colorMode: 'none' })
     const lines = ascii.split('\n')
 
-    // Model's top border row (e.g. "┌───────────────────────────┐│") gives
-    // its right-edge column directly. `refreshes` — the label for the
+    // Model's box right edge (column-based, not a literal-column-0
+    // assumption — issue #971 can legitimately shift Model's own column
+    // when it has a real single qualifying parent to align under, same as
+    // it does here against Controller). `refreshes` — the label for the
     // relationship that detours around Model to reach View — must land
-    // strictly to the right of that border on every row it occupies, never
+    // strictly to the right of that edge on every row it occupies, never
     // overlapping Model's own footprint the way the straight-line midpoint
     // used to (issue #487).
-    const modelTopRow = lines.findIndex(
-      (l, i) => /^┌─+┐/.test(l) && (lines[i + 1]?.includes('Model') ?? false),
-    )
-    expect(modelTopRow).toBeGreaterThanOrEqual(0)
-    const modelRightBorder = lines[modelTopRow]!.indexOf('┐')
+    const modelRect = findBoxRect(ascii, 'Model')
+    const modelRightBorder = modelRect.x1
     expect(modelRightBorder).toBeGreaterThan(0)
 
     const refreshesRow = lines.findIndex((l) => l.includes('refreshes'))

package/src/__tests__/ascii-class-parent-alignment-971.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Regression tests for issue #971 — "ASCII class-diagram layout: single-
+ * parent x-alignment," the first implementation stage of #964's fix
+ * (docs/decisions/ascii-class-diagram-x-coordinate-assignment-970.md).
+ *
+ * Before this fix, `class-diagram.ts` packed each level's classes strictly
+ * left-to-right in declaration order, with no reference to any parent's
+ * column — a level with exactly one occupant always landed at column 0,
+ * even when its real parent sat far to the right. This fix aligns a
+ * "singleton block" (no sibling at its level shares its exact parent-id
+ * set) with exactly one qualifying (strictly-shallower) parent under that
+ * parent's own box center instead. Every other shape (no parents, an
+ * all-same-level/rootless-cycle parent set, or more than one class sharing
+ * a parent set) is out of scope here — it keeps its pre-fix left-to-right
+ * position, tracked separately by issue #972.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { renderMermaidASCII } from '@zombie-mermaid/ascii-renderer'
+import { findBoxRect } from './helpers/ascii-form.ts'
+
+describe('ASCII class diagram — single-parent x-alignment (issue #971)', () => {
+  it("#964's exact repro: a lone child aligns under its real parent's center, not the leftmost column", () => {
+    const src = `classDiagram
+  class Left
+  class TallMid {
+    +String b0
+    +String b1
+    +String b2
+    +String b3
+    +String b4
+    +String b5
+  }
+  class RightSrc
+  class Kid
+  RightSrc --> Kid`
+    const ascii = renderMermaidASCII(src, { useAscii: true })
+
+    const rightSrc = findBoxRect(ascii, 'RightSrc')
+    const kid = findBoxRect(ascii, 'Kid')
+    const rightSrcCenter =
+      rightSrc.x0 + Math.floor((rightSrc.x1 - rightSrc.x0) / 2)
+    const kidCenter = kid.x0 + Math.floor((kid.x1 - kid.x0) / 2)
+
+    // Kid's box center lands on (or within 1 cell of, for odd-width
+    // rounding) RightSrc's box center -- not at column 0, where every
+    // sole-occupant level used to land regardless of its real parent.
+    expect(Math.abs(kidCenter - rightSrcCenter)).toBeLessThanOrEqual(1)
+    expect(kid.x0).toBeGreaterThan(0)
+
+    // Left is the leftmost root and must stay exactly where declaration
+    // order has always put it -- this fix only ever moves a class that has
+    // a real single parent to align to.
+    const left = findBoxRect(ascii, 'Left')
+    expect(left.x0).toBe(0)
+  })
+
+  it('a root class with no parent at all is unaffected', () => {
+    const src = `classDiagram
+  class Lonely`
+    const ascii = renderMermaidASCII(src, { useAscii: true })
+    const lonely = findBoxRect(ascii, 'Lonely')
+    expect(lonely.x0).toBe(0)
+  })
+
+  it('a class whose only parent edges are same-level (a rootless relationship cycle) is unaffected', () => {
+    // A -> B -> C -> A has no external root: the level-BFS puts every
+    // member at level 0 together, but the `parents` map still records
+    // each one's in-cycle predecessor. That predecessor is same-level, not
+    // strictly shallower, so it doesn't qualify -- every member keeps its
+    // plain declaration-order position, same as before this fix.
+    const src = `classDiagram
+  class A
+  class B
+  class C
+  A --> B
+  B --> C
+  C --> A`
+    const ascii = renderMermaidASCII(src, { useAscii: true })
+    const a = findBoxRect(ascii, 'A')
+    const b = findBoxRect(ascii, 'B')
+    const c = findBoxRect(ascii, 'C')
+    expect(a.x0).toBe(0)
+    expect(a.x0).toBeLessThan(b.x0)
+    expect(b.x0).toBeLessThan(c.x0)
+  })
+
+  // Two children sharing the exact same single parent are a *multi-member*
+  // block -- explicitly out of #971's scope (see #972) -- so this sample
+  // must render byte-for-byte the way it always has. Chosen because
+  // docs/decisions/ascii-class-diagram-x-coordinate-assignment-970.md
+  // names this exact samples-data.ts sample ("Class: Inheritance (<|--)")
+  // as one it verified stays unchanged.
+  it('an existing catalog sample with a multi-child parent (Class: Inheritance) keeps its exact current positions', () => {
+    const src = `classDiagram
+  class Animal {
+    +String name
+    +eat() void
+  }
+  class Dog {
+    +String breed
+    +bark() void
+  }
+  class Cat {
+    +bool isIndoor
+    +meow() void
+  }
+  Animal <|-- Dog
+  Animal <|-- Cat`
+    const ascii = renderMermaidASCII(src, { useAscii: true })
+    const animal = findBoxRect(ascii, 'Animal')
+    const dog = findBoxRect(ascii, 'Dog')
+    const cat = findBoxRect(ascii, 'Cat')
+    expect(animal).toEqual({ x0: 0, x1: 17, y0: 0, y1: 6 })
+    expect(dog).toEqual({ x0: 0, x1: 18, y0: 10, y1: 16 })
+    expect(cat).toEqual({ x0: 23, x1: 42, y0: 10, y1: 16 })
+  })
+
+  it('two independent single-parent children at the same level both align, and compaction keeps them from overlapping', () => {
+    // ParentA and ParentB are both roots; KidA is ParentA's only child,
+    // KidB is ParentB's only child. Each is its own singleton block with
+    // exactly one qualifying parent, so both get a real desired center --
+    // this exercises the compaction pass itself (#971 must implement it
+    // for every block shape, not just multi-parent ones): two different
+    // singleton blocks can still want colliding desired positions.
+    const src = `classDiagram
+  class ParentA
+  class ParentB
+  class KidA
+  class KidB
+  ParentA --> KidA
+  ParentB --> KidB`
+    const ascii = renderMermaidASCII(src, { useAscii: true })
+    const kidA = findBoxRect(ascii, 'KidA')
+    const kidB = findBoxRect(ascii, 'KidB')
+    // Declaration order is preserved -- KidA never lands right of KidB.
+    expect(kidA.x1).toBeLessThan(kidB.x0)
+  })
+})