@diagrammo/dgmo 0.8.20 → 0.8.22

package/src/sequence/renderer.ts

@@ -28,7 +28,11 @@ import type { ResolvedTagMap } from './tag-resolution';
 import { resolveActiveTagGroup } from '../utils/tag-groups';
 import { LEGEND_HEIGHT } from '../utils/legend-constants';
 import { renderLegendD3 } from '../utils/legend-d3';
-import type { LegendConfig, LegendState } from '../utils/legend-types';
+import type {
+  LegendCallbacks,
+  LegendConfig,
+  LegendState,
+} from '../utils/legend-types';
 import { TITLE_FONT_SIZE, TITLE_FONT_WEIGHT } from '../utils/title-constants';
 
 // ============================================================
@@ -60,6 +64,11 @@ const NOTE_CHARS_PER_LINE = Math.floor(
 );
 const COLLAPSED_NOTE_H = 20;
 const COLLAPSED_NOTE_W = 40;
+const ACTIVATION_WIDTH = 10;
+const SELF_CALL_HEIGHT = 25;
+const SELF_CALL_WIDTH = 30;
+// Max note width that keeps a note within one participant lane
+const NOTE_LANE_MAX = PARTICIPANT_GAP - ACTIVATION_WIDTH - NOTE_GAP; // 135px
 
 function wrapTextLines(text: string, maxChars: number): string[] {
   const rawLines = text.split('\n');
@@ -68,14 +77,26 @@ function wrapTextLines(text: string, maxChars: number): string[] {
     if (line.length <= maxChars) {
       wrapped.push(line);
     } else {
-      const words = line.split(' ');
-      let current = '';
+      // Preserve bullet prefix: keep "- " glued to the first content word
+      // so wrapping never produces a bare "-" line.
+      const bulletPrefix = line.startsWith('- ') ? '- ' : '';
+      const content = bulletPrefix ? line.slice(2) : line;
+      const words = content.split(' ');
+      let current = bulletPrefix;
       for (const word of words) {
-        if (current && (current + ' ' + word).length > maxChars) {
+        const candidate = current ? current + ' ' + word : word;
+        if (
+          current &&
+          current !== bulletPrefix &&
+          candidate.length > maxChars
+        ) {
           wrapped.push(current);
           current = word;
         } else {
-          current = current ? current + ' ' + word : word;
+          current =
+            current && current !== bulletPrefix
+              ? current + ' ' + word
+              : current + word;
         }
       }
       if (current) wrapped.push(current);
@@ -539,6 +560,10 @@ export interface SequenceRenderOptions {
   expandedNoteLines?: Set<number>; // keyed by note lineNumber; undefined = all expanded (CLI default)
   exportWidth?: number; // Explicit width for CLI/export rendering (bypasses getBoundingClientRect)
   activeTagGroup?: string | null; // Active tag group name for tag-driven recoloring; null = explicitly none
+  expandAllNotes?: boolean; // Whether the "Expand Notes" toggle is active
+  onExpandAllNotes?: (expand: boolean) => void; // Toggle all notes expanded/collapsed
+  controlsExpanded?: boolean; // Controls group expanded state (managed by React)
+  onToggleControlsExpand?: () => void; // Callback to toggle controls group
 }
 
 /**
@@ -953,6 +978,37 @@ export function renderSequenceDiagram(
   );
   if (participants.length === 0) return;
 
+  // Participant index lookup — used to clamp note width within one lane
+  const participantIndexMap = new Map<string, number>();
+  participants.forEach((p, i) => participantIndexMap.set(p.id, i));
+
+  // Extra X shift for notes after self-calls
+  const SELF_CALL_NOTE_X_SHIFT =
+    ACTIVATION_WIDTH / 2 +
+    SELF_CALL_WIDTH +
+    NOTE_GAP -
+    (ACTIVATION_WIDTH + NOTE_GAP); // 25px
+
+  const noteEffectiveMaxW = (
+    participantId: string,
+    position: 'right' | 'left',
+    afterSelfCall = false
+  ): number => {
+    const idx = participantIndexMap.get(participantId);
+    if (idx === undefined) return NOTE_MAX_W;
+    const hasNeighbor =
+      position === 'right' ? idx < participants.length - 1 : idx > 0;
+    if (!hasNeighbor) return NOTE_MAX_W;
+    const laneMax =
+      afterSelfCall && position === 'right'
+        ? NOTE_LANE_MAX - SELF_CALL_NOTE_X_SHIFT
+        : NOTE_LANE_MAX;
+    return Math.min(NOTE_MAX_W, laneMax);
+  };
+
+  const charsForWidth = (maxW: number): number =>
+    Math.floor((maxW - NOTE_PAD_H * 2 - NOTE_FOLD) / NOTE_CHAR_W);
+
   const activationsOff = parsedOptions.activations?.toLowerCase() === 'off';
 
   // Tag resolution — shared utility handles priority chain:
@@ -1049,7 +1105,39 @@ export function renderSequenceDiagram(
     return msgToLastStep.get(closestMsgIndex) ?? -1;
   };
 
-  // Find the first visible message index in an element subtree
+  // Check whether a note's preceding message is a self-call.
+  // Self-call loopback arrows extend SELF_CALL_HEIGHT below the step Y,
+  // so notes after self-calls need a larger vertical offset.
+  const isNoteAfterSelfCall = (note: SequenceNote): boolean => {
+    let closestMsgIndex = -1;
+    let closestLine = -1;
+    for (let mi = 0; mi < messages.length; mi++) {
+      if (
+        messages[mi].lineNumber < note.lineNumber &&
+        messages[mi].lineNumber > closestLine
+      ) {
+        closestLine = messages[mi].lineNumber;
+        closestMsgIndex = mi;
+      }
+    }
+    if (closestMsgIndex < 0) return false;
+    const msg = messages[closestMsgIndex];
+    return msg.from === msg.to;
+  };
+
+  // Extra gap below self-call loop before note starts
+  const SELF_CALL_NOTE_GAP = 8;
+  const noteOffsetBelow = (note: SequenceNote): number =>
+    isNoteAfterSelfCall(note)
+      ? SELF_CALL_HEIGHT + NOTE_OFFSET_BELOW + SELF_CALL_NOTE_GAP
+      : NOTE_OFFSET_BELOW;
+
+  // Find the first visible message index in an element subtree.
+  // Use lineNumber lookup instead of indexOf — collapse projection creates
+  // separate spread copies for messages[] and elements[], breaking reference equality.
+  const msgLineToIdx = new Map<number, number>();
+  messages.forEach((m, i) => msgLineToIdx.set(m.lineNumber, i));
+
   const findFirstMsgIndex = (els: SequenceElement[]): number => {
     for (const el of els) {
       if (isSequenceBlock(el)) {
@@ -1064,7 +1152,7 @@ export function renderSequenceDiagram(
         const elseIdx = findFirstMsgIndex(el.elseChildren);
         if (elseIdx >= 0) return elseIdx;
       } else if (!isSequenceSection(el) && !isSequenceNote(el)) {
-        const idx = messages.indexOf(el as SequenceMessage);
+        const idx = msgLineToIdx.get(el.lineNumber) ?? -1;
         if (idx >= 0 && !hiddenMsgIndices.has(idx)) return idx;
       }
     }
@@ -1121,8 +1209,11 @@ export function renderSequenceDiagram(
   // When notes share horizontal space with subsequent arrows, generous vertical clearance
   // is needed so note boxes don't visually cover message labels.
   const NOTE_TRAILING_GAP = 35;
-  const computeNoteHeight = (text: string): number => {
-    const lines = wrapTextLines(text, NOTE_CHARS_PER_LINE);
+  const computeNoteHeight = (
+    text: string,
+    maxChars: number = NOTE_CHARS_PER_LINE
+  ): number => {
+    const lines = wrapTextLines(text, maxChars);
     return lines.length * NOTE_LINE_H + NOTE_PAD_V * 2;
   };
   let trailingNoteSpace = 0; // extra space for notes at the end with no following message
@@ -1131,15 +1222,18 @@ export function renderSequenceDiagram(
       const el = els[i];
       if (isSequenceNote(el)) {
         // Total vertical extent of notes from the message arrow:
-        //   NOTE_OFFSET_BELOW (gap above first note)
+        //   offset (gap above first note — larger after self-calls)
         //   + each note's height + NOTE_OFFSET_BELOW (inter-note gap)
         //   + NOTE_TRAILING_GAP (gap below last note — clears next message label)
-        let totalExtent = NOTE_OFFSET_BELOW;
+        const firstOffset = noteOffsetBelow(el as SequenceNote);
+        let totalExtent = firstOffset;
         let j = i;
         while (j < els.length && isSequenceNote(els[j])) {
           const note = els[j] as SequenceNote;
+          const sc = isNoteAfterSelfCall(note);
+          const maxW = noteEffectiveMaxW(note.participantId, note.position, sc);
           const noteH = isNoteExpanded(note)
-            ? computeNoteHeight(note.text)
+            ? computeNoteHeight(note.text, charsForWidth(maxW))
             : COLLAPSED_NOTE_H;
           totalExtent += noteH + NOTE_OFFSET_BELOW;
           j++;
@@ -1401,13 +1495,18 @@ export function renderSequenceDiagram(
           let noteTopY: number;
           if (prevNoteY !== undefined && prevNote) {
             // Stack below previous note
+            const prevMaxW = noteEffectiveMaxW(
+              prevNote.participantId,
+              prevNote.position,
+              isNoteAfterSelfCall(prevNote)
+            );
             const prevNoteH = isNoteExpanded(prevNote)
-              ? computeNoteHeight(prevNote.text)
+              ? computeNoteHeight(prevNote.text, charsForWidth(prevMaxW))
               : COLLAPSED_NOTE_H;
             noteTopY = prevNoteY + prevNoteH + NOTE_OFFSET_BELOW;
           } else {
-            // First note after a message
-            noteTopY = stepY(si) + NOTE_OFFSET_BELOW;
+            // First note after a message — use larger offset after self-calls
+            noteTopY = stepY(si) + noteOffsetBelow(el);
           }
           noteYMap.set(el, noteTopY);
         } else if (isSequenceBlock(el)) {
@@ -1435,8 +1534,13 @@ export function renderSequenceDiagram(
         )
       : layoutEndY;
   for (const [note, noteTopY] of noteYMap) {
+    const maxW = noteEffectiveMaxW(
+      note.participantId,
+      note.position,
+      isNoteAfterSelfCall(note)
+    );
     const noteH = isNoteExpanded(note)
-      ? computeNoteHeight(note.text)
+      ? computeNoteHeight(note.text, charsForWidth(maxW))
       : COLLAPSED_NOTE_H;
     contentBottomY = Math.max(
       contentBottomY,
@@ -1632,39 +1736,33 @@ export function renderSequenceDiagram(
     }
   }
 
-  // Render legend pills for tag groups
-  if (parsed.tagGroups.length > 0) {
-    const legendY = TOP_MARGIN + titleOffset;
-    // Resolve tag colors for legend entries
-    const resolvedGroups = parsed.tagGroups
-      .filter((tg) => tg.entries.length > 0)
-      .map((tg) => ({
-        name: tg.name,
-        entries: tg.entries.map((e) => ({
-          value: e.value,
-          color: e.color,
-        })),
-      }));
-    const legendConfig: LegendConfig = {
-      groups: resolvedGroups,
-      position: { placement: 'top-center', titleRelation: 'below-title' },
-      mode: 'fixed',
-    };
-    const legendState: LegendState = { activeGroup: activeTagGroup ?? null };
-    const legendG = svg
-      .append('g')
-      .attr('class', 'sequence-legend')
-      .attr('transform', `translate(0,${legendY})`);
-    renderLegendD3(
-      legendG,
-      legendConfig,
-      legendState,
-      palette,
-      isDark,
-      undefined,
-      svgWidth
-    );
-  }
+  // Collect all note line numbers (for controls group visibility + "all expanded" check)
+  const allNoteLineNumbers: number[] = [];
+  const collectNoteLines = (els: SequenceElement[]): void => {
+    for (const el of els) {
+      if (isSequenceNote(el)) {
+        allNoteLineNumbers.push(el.lineNumber);
+      } else if (isSequenceBlock(el)) {
+        collectNoteLines(el.children);
+        if ('elseChildren' in el) collectNoteLines(el.elseChildren);
+        if ('branches' in el && Array.isArray(el.branches)) {
+          for (const branch of el.branches) {
+            collectNoteLines(branch.children);
+          }
+        }
+      }
+    }
+  };
+  collectNoteLines(elements);
+
+  // Show controls group only in interactive mode (expandedNoteLines defined)
+  // when notes exist and collapse-notes is not disabled
+  const showNotesControl =
+    allNoteLineNumbers.length > 0 &&
+    !collapseNotesDisabled &&
+    expandedNoteLines !== undefined;
+
+  const hasTagGroups = parsed.tagGroups.length > 0;
 
   // Build set of collapsed group names for drill-bar rendering
   const collapsedGroupNames = new Set<string>();
@@ -2093,7 +2191,6 @@ export function renderSequenceDiagram(
   }
 
   // Render activation rectangles (behind arrows)
-  const ACTIVATION_WIDTH = 10;
   const ACTIVATION_NEST_OFFSET = 6;
   activations.forEach((act) => {
     const px = participantX.get(act.participantId);
@@ -2285,8 +2382,7 @@ export function renderSequenceDiagram(
   }
 
   // Render steps (calls and returns in stack-inferred order)
-  const SELF_CALL_WIDTH = 30;
-  const SELF_CALL_HEIGHT = 25;
+  // SELF_CALL_WIDTH is now a module-level constant
   renderSteps.forEach((step, i) => {
     const fromX = participantX.get(step.from);
     const toX = participantX.get(step.to);
@@ -2354,6 +2450,10 @@ export function renderSequenceDiagram(
             .attr('y', y + SELF_CALL_HEIGHT / 2 + 4)
             .attr('text-anchor', 'start')
             .attr('fill', arrowColor)
+            .attr('paint-order', 'stroke fill')
+            .attr('stroke', palette.bg)
+            .attr('stroke-width', 4)
+            .attr('stroke-linejoin', 'round')
             .attr('font-size', 12)
             .attr('class', 'message-label')
             .attr(
@@ -2424,6 +2524,10 @@ export function renderSequenceDiagram(
             .attr('y', y - 8)
             .attr('text-anchor', 'middle')
             .attr('fill', arrowColor)
+            .attr('paint-order', 'stroke fill')
+            .attr('stroke', palette.bg)
+            .attr('stroke-width', 4)
+            .attr('stroke-linejoin', 'round')
             .attr('font-size', 12)
             .attr('class', 'message-label')
             .attr(
@@ -2498,6 +2602,10 @@ export function renderSequenceDiagram(
           .attr('y', y - 6)
           .attr('text-anchor', 'middle')
           .attr('fill', returnColor)
+          .attr('paint-order', 'stroke fill')
+          .attr('stroke', palette.bg)
+          .attr('stroke-width', 4)
+          .attr('stroke-linejoin', 'round')
           .attr('font-size', 11)
           .attr('class', 'message-label')
           .attr(
@@ -2539,15 +2647,27 @@ export function renderSequenceDiagram(
 
         if (expanded) {
           // --- Expanded note: full folded-corner box with wrapped text ---
-          const wrappedLines = wrapTextLines(el.text, NOTE_CHARS_PER_LINE);
+          const afterSelfCall = isNoteAfterSelfCall(el);
+          const maxW = noteEffectiveMaxW(
+            el.participantId,
+            el.position,
+            afterSelfCall
+          );
+          const maxChars = charsForWidth(maxW);
+          const wrappedLines = wrapTextLines(el.text, maxChars);
           const noteH = wrappedLines.length * NOTE_LINE_H + NOTE_PAD_V * 2;
           const maxLineLen = Math.max(...wrappedLines.map((l) => l.length));
           const noteW = Math.min(
-            NOTE_MAX_W,
+            maxW,
             Math.max(80, maxLineLen * NOTE_CHAR_W + NOTE_PAD_H * 2 + NOTE_FOLD)
           );
+          // Shift notes past self-call loopback when applicable
+          const rightOffset =
+            afterSelfCall && isRight
+              ? ACTIVATION_WIDTH / 2 + SELF_CALL_WIDTH + NOTE_GAP
+              : ACTIVATION_WIDTH + NOTE_GAP;
           const noteX = isRight
-            ? px + ACTIVATION_WIDTH + NOTE_GAP
+            ? px + rightOffset
             : px - ACTIVATION_WIDTH - NOTE_GAP - noteW;
 
           const noteG = svg
@@ -2621,8 +2741,13 @@ export function renderSequenceDiagram(
         } else {
           // --- Collapsed note: compact indicator ---
           const cFold = 6;
+          const afterSelfCallC = isNoteAfterSelfCall(el);
+          const rightOffsetC =
+            afterSelfCallC && isRight
+              ? ACTIVATION_WIDTH / 2 + SELF_CALL_WIDTH + NOTE_GAP
+              : ACTIVATION_WIDTH + NOTE_GAP;
           const noteX = isRight
-            ? px + ACTIVATION_WIDTH + NOTE_GAP
+            ? px + rightOffsetC
             : px - ACTIVATION_WIDTH - NOTE_GAP - COLLAPSED_NOTE_W;
 
           const noteG = svg
@@ -2694,6 +2819,73 @@ export function renderSequenceDiagram(
   if (elements && elements.length > 0) {
     renderNoteElements(elements);
   }
+
+  // Render legend LAST so it sits on top of all other SVG elements
+  // (group boxes, lifelines, participants, etc.) and can receive clicks.
+  if (hasTagGroups || showNotesControl) {
+    const controlsExpanded = options?.controlsExpanded ?? false;
+
+    const legendY = TOP_MARGIN + titleOffset;
+    const resolvedGroups = parsed.tagGroups
+      .filter((tg) => tg.entries.length > 0)
+      .map((tg) => ({
+        name: tg.name,
+        entries: tg.entries.map((e) => ({
+          value: e.value,
+          color: e.color,
+        })),
+      }));
+
+    const allExpanded = showNotesControl && (options?.expandAllNotes ?? false);
+
+    const controlsGroup = showNotesControl
+      ? {
+          toggles: [
+            {
+              id: 'expand-all-notes',
+              type: 'toggle' as const,
+              label: 'Expand Notes',
+              active: allExpanded,
+              onToggle: () => {},
+            },
+          ],
+        }
+      : undefined;
+
+    const legendConfig: LegendConfig = {
+      groups: resolvedGroups,
+      position: { placement: 'top-center', titleRelation: 'below-title' },
+      mode: 'fixed',
+      controlsGroup,
+    };
+    const legendState: LegendState = {
+      activeGroup: activeTagGroup ?? null,
+      controlsExpanded,
+    };
+
+    const legendCallbacks: LegendCallbacks = {
+      onControlsExpand: () => {
+        options?.onToggleControlsExpand?.();
+      },
+      onControlsToggle: (_toggleId: string, active: boolean) => {
+        options?.onExpandAllNotes?.(active);
+      },
+    };
+
+    const legendG = svg
+      .append('g')
+      .attr('class', 'sequence-legend')
+      .attr('transform', `translate(0,${legendY})`);
+    renderLegendD3(
+      legendG,
+      legendConfig,
+      legendState,
+      palette,
+      isDark,
+      legendCallbacks,
+      svgWidth
+    );
+  }
 }
 
 /**
@@ -2732,6 +2924,31 @@ export function buildNoteMessageMap(
   return map;
 }
 
+/**
+ * Collect all note line numbers from a sequence diagram's elements.
+ * Used by the app to compute the "expand all" set.
+ */
+export function collectNoteLineNumbers(elements: SequenceElement[]): number[] {
+  const result: number[] = [];
+  const walk = (els: SequenceElement[]): void => {
+    for (const el of els) {
+      if (isSequenceNote(el)) {
+        result.push(el.lineNumber);
+      } else if (isSequenceBlock(el)) {
+        walk(el.children);
+        if (el.elseIfBranches) {
+          for (const branch of el.elseIfBranches) {
+            walk(branch.children);
+          }
+        }
+        walk(el.elseChildren);
+      }
+    }
+  };
+  walk(elements);
+  return result;
+}
+
 function renderParticipant(
   svg: d3Selection.Selection<SVGSVGElement, unknown, null, undefined>,
   participant: SequenceParticipant,

package/src/sharing.ts

@@ -30,6 +30,9 @@ export interface CompactViewState {
   rps?: number; // RPS multiplier (infra)
   spd?: number; // playback speed (infra)
   io?: Record<string, number>; // instance overrides (infra)
+  hd?: boolean; // hide descriptions (mindmap)
+  cbd?: boolean; // color by depth (mindmap)
+  rq?: string; // radar quadrant focus (tech-radar position)
 }
 
 export interface DecodedDiagramUrl {

package/src/sitemap/layout.ts

@@ -22,6 +22,7 @@ export interface SitemapLayoutNode {
   metadata: Record<string, string>;
   /** Original (unfiltered) metadata for tag-based coloring and hover dimming */
   tagMetadata: Record<string, string>;
+  description?: string[];
   isContainer: boolean;
   lineNumber: number;
   color?: string;
@@ -161,23 +162,36 @@ function filterMetadata(
   return filtered;
 }
 
-function computeCardWidth(label: string, meta: Record<string, string>): number {
+function computeCardWidth(
+  label: string,
+  meta: Record<string, string>,
+  descLines?: string[]
+): number {
   let maxChars = label.length;
   for (const [key, value] of Object.entries(meta)) {
     const lineChars = key.length + 2 + value.length;
     if (lineChars > maxChars) maxChars = lineChars;
   }
+  if (descLines) {
+    for (const dl of descLines) {
+      if (dl.length > maxChars) maxChars = dl.length;
+    }
+  }
   return Math.max(
     MIN_CARD_WIDTH,
     Math.ceil(maxChars * CHAR_WIDTH) + CARD_H_PAD * 2
   );
 }
 
-function computeCardHeight(meta: Record<string, string>): number {
+function computeCardHeight(
+  meta: Record<string, string>,
+  descLineCount = 0
+): number {
   const metaCount = Object.keys(meta).length;
-  if (metaCount === 0) return HEADER_HEIGHT + CARD_V_PAD;
+  const contentCount = metaCount + descLineCount;
+  if (contentCount === 0) return HEADER_HEIGHT + CARD_V_PAD;
   return (
-    HEADER_HEIGHT + SEPARATOR_GAP + metaCount * META_LINE_HEIGHT + CARD_V_PAD
+    HEADER_HEIGHT + SEPARATOR_GAP + contentCount * META_LINE_HEIGHT + CARD_V_PAD
   );
 }
 
@@ -307,8 +321,8 @@ function flattenNodes(
         parentPageId,
         meta,
         fullMeta: { ...node.metadata },
-        width: computeCardWidth(node.label, meta),
-        height: computeCardHeight(meta),
+        width: computeCardWidth(node.label, meta, node.description),
+        height: computeCardHeight(meta, node.description?.length ?? 0),
       });
       // Pages can have children too (nested pages) — this page becomes the parentPageId
       if (node.children.length > 0) {
@@ -396,15 +410,15 @@ export function layoutSitemap(
   const pageNodeIds = new Set<string>();
   const collapsedContainerIds = new Set<string>();
 
-  // Identify containers vs pages, and detect collapsed (empty) containers
+  // Identify containers vs pages, and detect collapsed containers.
+  // A container is collapsed iff hiddenCounts records it with a positive count
+  // (meaning collapseSitemapTree pruned its descendants). Source-level empty
+  // containers (never had children) are NOT treated as collapsed.
   for (const flat of flatNodes) {
     if (flat.sitemapNode.isContainer) {
       containerIds.add(flat.sitemapNode.id);
-      // A container is "collapsed" if it has no children at all in the flat list
-      const hasAnyChild = flatNodes.some(
-        (f) => f.parentContainerId === flat.sitemapNode.id
-      );
-      if (!hasAnyChild) {
+      const hidden = hiddenCounts?.get(flat.sitemapNode.id) ?? 0;
+      if (hidden > 0) {
         collapsedContainerIds.add(flat.sitemapNode.id);
       }
     } else {
@@ -412,16 +426,31 @@ export function layoutSitemap(
     }
   }
 
+  // Sibling-page floor for collapsed containers — prevents collapsed containers
+  // from rendering smaller than meta-rich page cards in the same layout.
+  let pageMaxW = 0;
+  let pageMaxH = 0;
+  for (const f of flatNodes) {
+    if (!f.sitemapNode.isContainer) {
+      if (f.width > pageMaxW) pageMaxW = f.width;
+      if (f.height > pageMaxH) pageMaxH = f.height;
+    }
+  }
+
   // Add nodes to dagre
   for (const flat of flatNodes) {
     const node = flat.sitemapNode;
     if (node.isContainer) {
       if (collapsedContainerIds.has(node.id)) {
-        // Collapsed container — regular node with explicit dimensions
+        // Collapsed container — regular node with explicit dimensions.
+        // Floor to max page-card dims so collapsed containers never look
+        // smaller than sibling page cards.
+        const flooredW = Math.max(flat.width, pageMaxW);
+        const flooredH = Math.max(flat.height, pageMaxH);
         g.setNode(node.id, {
           label: node.label,
-          width: flat.width,
-          height: flat.height,
+          width: flooredW,
+          height: flooredH,
         });
       } else {
         // Regular container — compound node with padding for child layout
@@ -504,6 +533,7 @@ export function layoutSitemap(
       label: node.label,
       metadata: flat.meta,
       tagMetadata: flat.fullMeta,
+      description: node.description,
       isContainer: false,
       lineNumber: node.lineNumber,
       color: resolveNodeColor(node, parsed.tagGroups, activeTagGroup ?? null),
@@ -546,7 +576,15 @@ export function layoutSitemap(
           node.children.length > 0 || (hc != null && hc > 0) || undefined,
       });
     } else {
-      // Fallback
+      // Fallback — still apply the floor for consistency
+      const isCollapsed = collapsedContainerIds.has(node.id);
+      const flooredW = isCollapsed
+        ? Math.max(flat.width, pageMaxW)
+        : flat.width;
+      const fallbackH = isCollapsed
+        ? flat.height
+        : labelHeight + CONTAINER_PAD_BOTTOM;
+      const flooredH = isCollapsed ? Math.max(fallbackH, pageMaxH) : fallbackH;
       layoutContainers.push({
         nodeId: node.id,
         label: node.label,
@@ -556,8 +594,8 @@ export function layoutSitemap(
         tagMetadata: flat.fullMeta,
         x: MARGIN,
         y: MARGIN,
-        width: flat.width,
-        height: labelHeight + CONTAINER_PAD_BOTTOM,
+        width: flooredW,
+        height: flooredH,
         labelHeight,
         hiddenCount: hc,
         hasChildren: