@principal-ai/subsystems-react 0.53.3 → 0.53.5

package/src/subsystem/C4NodeCard.tsx

@@ -12,7 +12,6 @@
  * wants it: technology on the top row, description under the label.
  */
 
-import { useLayoutEffect, useRef } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { AppWindow, Component, Database, Maximize2 } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
@@ -76,16 +75,127 @@ export function nodeSize(node: C4Element): { width: number; height: number } {
  */
 const LABEL_SLOT_H = 40;
 
+/**
+ * The technology row's height, pinned for the same reason as the label slot: the
+ * row is a line of text plus an optional 16px brand mark, so its natural height
+ * depends on which of those are present. Pinning it makes the card's chrome a
+ * known quantity, which is what lets `descriptionLineBudget` below say how many
+ * description lines fit — and lets the footer pad and the header pad agree about
+ * where the card's content actually ends.
+ */
+const TECH_SLOT_H = 18;
+
+/** The card's own vertical padding (`padding: '10px 12px'`). */
+const CARD_PAD_Y = 10;
+
+/** The card's flex `gap`, between each of its rows. */
+const CARD_GAP = 3;
+
+/** The description's line height, as a multiple of its font size. */
+const DESC_LINE_HEIGHT = 1.35;
+
+/**
+ * Breathing room between a grown container's own chrome and the components nested
+ * inside it.
+ *
+ * The description is hidden while grown, so the components land where the
+ * description would have been — immediately under the technology row. Without
+ * this the gap is the width of one row gap, which reads as the components being
+ * crowded against the header while the sides and footer sit `OPEN_SIDE_PAD` away.
+ * This is not chrome: nothing is drawn in it.
+ */
+const OPEN_HEADER_AIR = 16;
+
 /**
  * Space a *grown* container reserves above its nested components: the card's own
- * top padding + the label slot + the row gap + the technology row, plus a little
+ * padding, its label slot, its technology row, the gaps between them, and a little
  * air. The description is hidden while grown, so it is not part of this.
  *
+ * Derived from the same constants the card is built from, rather than written as
+ * a literal, so it cannot drift from `descriptionLineBudget` — which subtracts
+ * exactly this chrome (and no air) to decide how much description a closed card
+ * can show. Those two disagreeing is how a card ends up taller than the box ELK
+ * laid out for it.
+ *
  * The graph hands this to ELK as the compound parent's top padding rather than
  * nudging the children down itself — so the parent's size and the children's
  * placement are still one ELK fit, not our arithmetic layered on top of it.
  */
-export const OPEN_HEADER_PAD = 84;
+export const OPEN_HEADER_PAD =
+  CARD_PAD_Y * 2 + LABEL_SLOT_H + CARD_GAP + TECH_SLOT_H + CARD_GAP + OPEN_HEADER_AIR;
+
+/**
+ * How many description lines fit in a card of this height before the drawn box
+ * would grow past the box the layout reserved for it.
+ *
+ * A card's height is a contract with the layout: ELK sized the node, the system
+ * frame and every edge against it. The description is the one part of a card whose
+ * length the layout cannot know, so it is clamped to what fits rather than allowed
+ * to push the border out past the frame drawn around it. Height is a *minimum* on
+ * the card, so without this a long description silently grows the drawn box while
+ * ELK — and therefore the boundary and the edge endpoints — keeps the old size.
+ *
+ * `hasTechRow` matters because an empty technology row is zero-height: a person
+ * card has one more line of room than a container. The row is pinned to
+ * `TECH_SLOT_H` when it has content, so this is exact rather than approximate.
+ */
+export function descriptionLineBudget(opts: {
+  reservedHeight: number;
+  lineHeight: number;
+  /** The card's border, which sits above the content and varies by kind. */
+  borderWidth: number;
+  hasTechRow: boolean;
+  /** Whether a collapse affordance is drawn at the bottom-right. */
+  reservesFooter: boolean;
+}): number {
+  const { reservedHeight, lineHeight, borderWidth, hasTechRow, reservesFooter } = opts;
+  if (lineHeight <= 0) return 0;
+  const topChrome =
+    borderWidth + CARD_PAD_Y + LABEL_SLOT_H + CARD_GAP + (hasTechRow ? TECH_SLOT_H : 0) + CARD_GAP;
+  // Reserving the footer is not the same as the card's own bottom padding. The
+  // toggle is `position: absolute` inset from the *padding* box, so it reaches
+  // `inset + size` up from the content box's bottom edge — and a description that
+  // only cleared the padding would still have its last line drawn through the
+  // button. Measured: the last line lands in the bottom ~26px band, and the toggle
+  // occupies the bottom 28 of it.
+  const bottomChrome = reservesFooter
+    ? Math.max(CARD_PAD_Y, TOGGLE_INSET + TOGGLE_SIZE)
+    : CARD_PAD_Y;
+  return Math.max(0, Math.floor((reservedHeight - topChrome - bottomChrome) / lineHeight));
+}
+
+/**
+ * The drill-down affordance, in the card's own box. Extracted from the button's
+ * style so the reserved footer below cannot drift from the thing it is reserving
+ * for — the two numbers are the same number.
+ */
+const TOGGLE_SIZE = 22;
+const TOGGLE_INSET = 6;
+
+/**
+ * Space a *grown* container reserves below its nested components, so the last row
+ * does not sit under the collapse affordance.
+ *
+ * The toggle is absolutely positioned, so it takes no space in the card's flow and
+ * ELK knows nothing about it: without this the parent is fitted to its children
+ * alone and the final row is drawn straight through the button. Reserving the
+ * toggle's own reach plus a little air keeps that an ELK fit too, rather than
+ * something we nudge afterwards.
+ */
+export const OPEN_FOOTER_PAD = TOGGLE_INSET + TOGGLE_SIZE + 8;
+
+/**
+ * Space a *grown* container reserves to the left and right of its nested
+ * components.
+ *
+ * Deliberately the footer's number rather than its own: the nested cards should
+ * sit in one uniform inset, not a wider one at the bottom than at the sides. Both
+ * are wider than the card's own 12px text inset — the label and technology row are
+ * the container's chrome and sit flush with its padding, while the nested cards
+ * are separate boxes it contains, and at the same inset they read as part of that
+ * chrome rather than held inside it.
+ */
+export const OPEN_SIDE_PAD = OPEN_FOOTER_PAD;
 
 type Theme = ReturnType<typeof useTheme>['theme'];
 
@@ -319,6 +429,22 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
   const subtitle = nodeSubtitle(node);
 
   const size = nodeSize(node);
+  // The height the layout reserved for this card — what the system frame and the
+  // edge endpoints were placed against. Everything below sizes to this, not to
+  // whatever the content would like.
+  const reservedHeight = height ?? size.height;
+  // A container always has a technology row (at minimum the member count); a
+  // person never does.
+  const hasTechRow = !!topLabel || node.kind === 'container';
+  const descLineHeightPx = theme.fontSizes[0] * DESC_LINE_HEIGHT;
+  const descLines = descriptionLineBudget({
+    reservedHeight,
+    lineHeight: descLineHeightPx,
+    borderWidth: style.width,
+    hasTechRow,
+    // The affordance is drawn exactly when the card can be expanded or collapsed.
+    reservesFooter: !!onExpand,
+  });
   const centered = shape.align === 'center';
   // The pill's inset is a separate concern from alignment, and a centred
   // component must not inherit it: 30px of each side would leave a 160-wide box
@@ -326,36 +452,21 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
   // that grow the box past the height the layout reserved.
   const pillInset = shape.kind === 'pill';
 
-  // TEMPORARY diagnostic — remove. The card's height is `minHeight`, so the box
-  // the browser lays out can exceed the nominal size the layout reserved, and
-  // nothing in the type system shows that: `nodeSize` and the drawn box are two
-  // different numbers. `offsetWidth/Height` are the border box, so this reports
-  // what was actually drawn. Logs on change only, so a reflow that does not
-  // resize the card stays quiet.
-  const probeRef = useRef<HTMLDivElement | null>(null);
-  const probeSeen = useRef('');
-  useLayoutEffect(() => {
-    const el = probeRef.current;
-    if (!el || typeof ResizeObserver === 'undefined') return;
-    const ro = new ResizeObserver(() => {
-      const line = `${el.offsetWidth}x${el.offsetHeight} (nominal ${size.width}x${size.height})`;
-      if (line === probeSeen.current) return;
-      probeSeen.current = line;
-      console.log(`[c4-card] ${node.kind} ${node.id} ${line}`);
-    });
-    ro.observe(el);
-    return () => ro.disconnect();
-  }, [node.kind, node.id, size.width, size.height]);
-
   return (
     <div
-      ref={probeRef}
       onClick={onClick}
       style={{
         position: 'relative',
         width: width ?? size.width,
-        minHeight: height ?? size.height,
-        transition: 'width 420ms ease-out, min-height 420ms ease-out',
+        // A hard height, not a minimum. The card *is* the box the layout reserved
+        // — the system frame is fitted around it and every edge endpoint is placed
+        // against it — so it must not be able to grow itself. `overflow: hidden`
+        // makes that structural: if the content ever exceeds the box, it is clipped
+        // rather than drawn outside the boundary. The description is clamped above
+        // so that clipping is never what you actually see.
+        height: reservedHeight,
+        transition: 'width 420ms ease-out, height 420ms ease-out',
+        overflow: 'hidden',
         boxSizing: 'border-box',
         display: 'flex',
         flexDirection: 'column',
@@ -363,7 +474,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
         // marker is conditional), and centring pushes the tag to a different
         // height on every card. In a graph grid that makes the row unscannable.
         justifyContent: 'flex-start',
-        gap: 3,
+        gap: CARD_GAP,
         padding: pillInset ? '10px 30px' : '10px 12px',
         borderRadius: shape.radius,
         background: theme.colors.backgroundSecondary ?? theme.colors.background,
@@ -385,6 +496,10 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           justifyContent: centered ? 'center' : 'space-between',
           gap: 6,
           height: LABEL_SLOT_H,
+          // Without this the slot shrinks when the content exceeds the card's fixed
+          // height, and `descriptionLineBudget`'s chrome stops being the chrome —
+          // measured at 39.11px instead of 40 the moment the description ran long.
+          flexShrink: 0,
           minWidth: 0,
         }}
       >
@@ -437,6 +552,10 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           letterSpacing: 0.5,
           textTransform: 'uppercase',
           minWidth: 0,
+          // Pinned, like the label slot above it: an empty row would otherwise be
+          // zero-height and the description budget would have to guess which cards
+          // have a technology row. Empty stays zero — a person has no technology.
+          ...(hasTechRow ? { height: TECH_SLOT_H, flexShrink: 0 } : {}),
         }}
       >
         {topLabel && (
@@ -470,16 +589,25 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           </span>
         )}
       </span>
-      {showDescription && subtitle && (
+      {showDescription && subtitle && descLines > 0 && (
         <span
           style={{
             fontFamily: theme.fonts.monospace,
             fontSize: theme.fontSizes[0],
             color: muted,
-            lineHeight: 1.35,
+            lineHeight: DESC_LINE_HEIGHT,
             whiteSpace: 'normal',
             overflowWrap: 'anywhere',
             textAlign: centered ? 'center' : 'left',
+            // Clamped to the room the layout left for it. The card's height is a
+            // contract with ELK — the boundary and every edge endpoint are placed
+            // against it — so the description cannot be allowed to grow the box.
+            // Same mechanism the label uses above; the count is derived from the
+            // reserved height rather than tuned by hand.
+            display: '-webkit-box',
+            WebkitLineClamp: descLines,
+            WebkitBoxOrient: 'vertical',
+            overflow: 'hidden',
           }}
         >
           {subtitle}
@@ -498,13 +626,13 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           aria-label="Show components"
           style={{
             position: 'absolute',
-            right: 6,
-            bottom: 6,
+            right: TOGGLE_INSET,
+            bottom: TOGGLE_INSET,
             display: 'inline-flex',
             alignItems: 'center',
             justifyContent: 'center',
-            width: 22,
-            height: 22,
+            width: TOGGLE_SIZE,
+            height: TOGGLE_SIZE,
             padding: 0,
             borderRadius: 4,
             border: `1px solid ${style.color}`,

package/src/subsystem/IssueList.tsx

@@ -30,6 +30,7 @@ import {
   History,
   Link2Off,
   MapPin,
+  Minus,
   Network,
   Route,
   Search,
@@ -657,6 +658,17 @@ export interface SubsystemIssueListProps {
    * honoured without an extra click.
    */
   focusCategory?: SubsystemIssueCategory;
+  /**
+   * Per-layer verification status from the host's lane summary — the same
+   * derivation the maintainer's lane icons use. The list only sees findings,
+   * so without this a layer with nothing to check (no module claims, say)
+   * is indistinguishable from a verified-clean one and renders a green check.
+   * A layer whose status here is `'none'` renders muted instead: not
+   * applicable, nothing was verified.
+   */
+  laneStatus?: Partial<
+    Record<SubsystemIssueCategory, 'verified' | 'partial' | 'issues' | 'blocked' | 'none'>
+  >;
   /**
    * Fires whenever the expanded-layer set changes. Publishers use it to focus
    * the canvas on the layer's findings — dimming everything the expanded
@@ -673,6 +685,7 @@ export function SubsystemIssueList({
   onHoverIssue,
   focusCategory,
   onExpandedCategoriesChange,
+  laneStatus,
 }: SubsystemIssueListProps) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -740,11 +753,18 @@ export function SubsystemIssueList({
     <div style={{ flex: 1, minHeight: 0, overflowY: 'auto' }}>
       {categories.map((category) => {
         // A layer with no findings renders its happy state: a green check in
-        // the header, no count, no cards.
+        // the header, no count, no cards. A layer the host reports as 'none'
+        // had nothing to verify at all (e.g. no module claims) — it renders
+        // muted, same as the maintainer's grey lane icon, because a green
+        // check would claim a verification that never ran.
         const clean = category.count === 0;
-        const accent = category.severity
-          ? severityColor(category.severity, theme.colors)
-          : theme.colors.success;
+        const notApplicable = clean && laneStatus?.[category.category] === 'none';
+        const accent =
+          category.severity
+            ? severityColor(category.severity, theme.colors)
+            : notApplicable
+              ? muted
+              : theme.colors.success;
         const isCollapsed = collapsed.has(category.category);
         const isHovered = hovered === category.category;
         return (
@@ -810,7 +830,12 @@ export function SubsystemIssueList({
                 {category.label}
               </span>
               {clean ? (
-                <CircleCheck size={13} color={accent} style={{ flexShrink: 0 }} />
+                notApplicable ? (
+                  // A muted dash: nothing was checked, so nothing passed.
+                  <Minus size={13} color={accent} style={{ flexShrink: 0 }} />
+                ) : (
+                  <CircleCheck size={13} color={accent} style={{ flexShrink: 0 }} />
+                )
               ) : (
                 <span
                   style={{

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -74,6 +74,7 @@ import {
   issueRung,
   ISSUE_KIND_ICON,
   ISSUE_RUNG_ORDER,
+  type SubsystemIssueListProps,
   type SubsystemIssue,
   type SubsystemIssueCategory,
 } from './IssueList';
@@ -354,6 +355,13 @@ export interface SubsystemComponentGraphProps {
    * plain issues view expands everything.
    */
   focusIssueCategory?: SubsystemIssueCategory;
+  /**
+   * Per-layer verification status from the host's lane summary (the same
+   * derivation the maintainer's lane icons use). Forwarded to the issues
+   * list so a layer with nothing to verify renders muted ("not applicable")
+   * instead of a green check for a verification that never ran.
+   */
+  laneStatus?: SubsystemIssueListProps['laneStatus'];
   /**
    * Click an issue. The graph first focuses the target on the canvas itself —
    * a component target is selected and framed (any edge / trail focus
@@ -528,7 +536,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, trails, graphifyRelations, orderByLine, initialTrailId, onReorderTrails, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, title, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
+function Inner({ components, trails, graphifyRelations, orderByLine, initialTrailId, onReorderTrails, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, title, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, laneStatus, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
   const { theme } = useTheme();
   const { fitView, fitBounds, screenToFlowPosition } = useReactFlow();
   const viewport = useViewport();
@@ -2778,6 +2786,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
                       <SubsystemIssueList
                         issues={issues ?? []}
                         focusCategory={focusIssueCategory}
+                        laneStatus={laneStatus}
                         onSelectIssue={focusIssueTarget}
                         onDeselectIssue={unfocusIssueTarget}
                         onApplyFix={onApplyIssueFix}
@@ -2790,6 +2799,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
                   <SubsystemIssueList
                     issues={issues ?? []}
                     focusCategory={focusIssueCategory}
+                    laneStatus={laneStatus}
                     onSelectIssue={focusIssueTarget}
                     onDeselectIssue={unfocusIssueTarget}
                     onApplyFix={onApplyIssueFix}

package/src/subsystem/c4.ts

@@ -170,23 +170,23 @@ export interface C4Group {
  * Derive the frames to draw from the elements and the current scope.
  *
  * A container becomes a frame whenever its components are on screen — in the
- * component view, or when it is the opened container. The system frame wraps
- * whichever containers are drawn. No frame is authored; this is the view of the
- * element set, so a container's identity (id, label, technology, colour) lives
- * only on the element.
+ * component view, or when it is one of the opened containers. The system frame
+ * wraps whichever containers are drawn. No frame is authored; this is the view
+ * of the element set, so a container's identity (id, label, technology, colour)
+ * lives only on the element.
  */
 export function deriveC4Groups(
-  model: Pick<C4Model, 'view' | 'system' | 'nodes' | 'openContainerId'>,
+  model: Pick<C4Model, 'view' | 'system' | 'nodes'> & OpenState,
 ): C4Group[] {
   const groups: C4Group[] = [];
   const containers = model.nodes.filter((n): n is C4Container => n.kind === 'container');
   const components = model.nodes.filter((n): n is C4Component => n.kind === 'component');
 
-  const opened = model.openContainerId ?? null;
+  const opened = new Set(openContainerSet(model));
   // Component view shows every container's components; container view shows a
   // container's components only when it is opened.
   const framing = (containerId: string): boolean =>
-    model.view === 'component' || opened === containerId;
+    model.view === 'component' || opened.has(containerId);
 
   const framedContainers: string[] = [];
   for (const c of containers) {
@@ -294,7 +294,7 @@ export function protocolColor(protocol: string | undefined): string {
  * A drawable C4 projection. Authored: the boxes and lines, nothing drawn for
  * you. Frames are derived by the renderer from the elements' `parentId` chains
  * — a container is a frame when its components are being shown (component view,
- * or opened via `openContainerId`), never a separately-authored thing.
+ * or opened via `openContainerIds`), never a separately-authored thing.
  */
 export interface C4Model {
   view: C4View;
@@ -302,13 +302,52 @@ export interface C4Model {
   nodes: C4Element[];
   edges: C4Edge[];
   /**
-   * Drill-down scope: the id of a container whose components should be shown
-   * inside it as a frame. Absent/null → the container is drawn as a box and its
-   * components are hidden. The renderer derives the frames either way.
+   * Drill-down scope: the containers whose components are shown nested inside
+   * them as a grown card. Absent/empty → every container is drawn as a plain box
+   * and all components are hidden. The renderer derives the frames either way.
+   *
+   * Several may be open at once: each is an independent ELK parent, and opening
+   * one never closes another. Order is not significant — {@link openContainerSet}
+   * normalizes it, so two permutations of the same set are one layout.
+   */
+  openContainerIds?: readonly string[];
+  /**
+   * Single-container shorthand for {@link C4Model.openContainerIds}, folded into
+   * it by {@link openContainerSet}. Kept because `C4Model` is a published type
+   * and removing the field would break every caller at once; prefer the plural,
+   * which is what the drill-down actually means now.
+   *
+   * @deprecated Use {@link C4Model.openContainerIds}.
    */
   openContainerId?: string | null;
 }
 
+/** Anything that can say which containers are open, however it says it. */
+type OpenState = Pick<C4Model, 'openContainerId' | 'openContainerIds'>;
+
+/**
+ * The open containers as a deduplicated, **sorted** list.
+ *
+ * Sorted on purpose: this doubles as the layout cache key, and two callers that
+ * open the same containers in a different order are in the same state — one
+ * layout, not two. A plain `Set` iteration order would follow insertion, so
+ * `[a, b]` and `[b, a]` would each compute their own ELK run for a diagram that
+ * did not change.
+ */
+export function openContainerSet(state: OpenState): string[] {
+  const ids = new Set<string>(state.openContainerIds ?? []);
+  if (state.openContainerId) ids.add(state.openContainerId);
+  return [...ids].sort();
+}
+
+/**
+ * Cache key for one open state. `''` is the closed diagram, which is why it is a
+ * join and not a count.
+ */
+export function openStateKey(openIds: readonly string[]): string {
+  return openIds.join(',');
+}
+
 /**
  * `owner/name` from a purl, trimmed of scheme and fragment. Used to label the
  * system frame when a repo key is known.

package/src/utils/elkLayout.test.ts

@@ -171,6 +171,29 @@ describe('planCompoundGroups', () => {
     expect(plan.skipped).toEqual(['proc']);
   });
 
+  test('carries the parent chrome padding through, all three pads', () => {
+    // `computeElkLayout` turns these into ELK's `elk.padding` on the parent. If
+    // they stop here the parent is fitted to its children alone, and chrome drawn
+    // around the content — the grown container's label slot, its collapse
+    // affordance, the inset that separates nested cards from its edges — is lost.
+    const plan = planCompoundGroups(
+      [{ id: 'host', memberIds: ['a', 'b'], padTop: 84, padBottom: 36, padX: 36 }],
+      ['a', 'b'],
+    );
+    expect(plan.built[0]!.padTop).toBe(84);
+    expect(plan.built[0]!.padBottom).toBe(36);
+    expect(plan.built[0]!.padX).toBe(36);
+  });
+
+  test('leaves the padding unset when the group asks for none', () => {
+    // Unset, not zero: `computeElkLayout` falls back to the default 12px, so a
+    // group that never asked for chrome keeps the padding it always had.
+    const plan = planCompoundGroups([{ id: 'proc', memberIds: ['a', 'b'] }], ['a', 'b']);
+    expect(plan.built[0]!.padTop).toBeUndefined();
+    expect(plan.built[0]!.padBottom).toBeUndefined();
+    expect(plan.built[0]!.padX).toBeUndefined();
+  });
+
   test('counts leaves through nested groups', () => {
     // process → module(one leaf) is still a single leaf, so both drop by
     // default even though the process lists one member id.

package/src/utils/elkLayout.ts

@@ -593,6 +593,23 @@ export interface CompoundGroupDef {
    * partition set on the parent itself is ignored.
    */
   padTop?: number;
+  /**
+   * Space reserved below the last child, in px — the `padTop` of the other end.
+   * Set it when the parent draws chrome at the bottom that its children must clear,
+   * e.g. the drill-down's absolutely-positioned collapse affordance, which takes
+   * no space in flow and so is invisible to ELK unless it is reserved here.
+   *
+   * Falls back to the same default padding as the other three sides.
+   */
+  padBottom?: number;
+  /**
+   * Space reserved to the left *and* right of the children, in px. One number for
+   * both sides because a parent that insets its contents does so symmetrically —
+   * there is no chrome that lives on one side only.
+   *
+   * Falls back to the default padding.
+   */
+  padX?: number;
 }
 
 /** Which groups ELK builds, and which it drops. */
@@ -601,7 +618,14 @@ export interface CompoundGroupPlan {
    * Built groups in build order — a group's children always appear before it,
    * so callers can map ids to shells in one forward pass.
    */
-  built: Array<{ id: string; childIds: string[]; minWidth?: number; padTop?: number }>;
+  built: Array<{
+    id: string;
+    childIds: string[];
+    minWidth?: number;
+    padTop?: number;
+    padBottom?: number;
+    padX?: number;
+  }>;
   /**
    * Dropped groups. Their members are promoted into the nearest built
    * ancestor, so callers must clear those members' `parentId`.
@@ -703,6 +727,8 @@ export function planCompoundGroups(
         // Carried through, not just validated here: the caller turns each of
         // these into ELK layout options on the parent node.
         padTop: g.padTop,
+        padBottom: g.padBottom,
+        padX: g.padX,
       });
     }
     if (!progress) {
@@ -715,6 +741,28 @@ export function planCompoundGroups(
   return { built, skipped: [...skipped] };
 }
 
+/**
+ * The four side ports every node in the graph carries, named
+ * `<id>_top|_right|_bottom|_left` — the ids `getPortSide` resolves an edge
+ * endpoint to.
+ *
+ * Shared by leaves and compound parents on purpose. A parent is still an ELK
+ * *node* that outside edges terminate on, and ELK rejects the whole graph if an
+ * edge names a port that was never declared: `JsonImportException: Referenced
+ * shape does not exist`. Declaring ports only on leaves silently works right up
+ * until the first edge crosses into a node that later becomes a group — which is
+ * why the drill-down only broke once a container was opened *and* something
+ * outside the boundary pointed at it.
+ */
+function cardinalPorts(id: string) {
+  return [
+    { id: `${id}_top`, properties: { 'port.side': 'NORTH' } },
+    { id: `${id}_right`, properties: { 'port.side': 'EAST' } },
+    { id: `${id}_bottom`, properties: { 'port.side': 'SOUTH' } },
+    { id: `${id}_left`, properties: { 'port.side': 'WEST' } },
+  ];
+}
+
 /**
  * Compute ELK layout for nodes and edges
  *
@@ -774,12 +822,7 @@ export async function computeElkLayout(
       x: node.position.x,
       y,
       // Add ports on each side for edge connections
-      ports: [
-        { id: `${node.id}_top`, properties: { 'port.side': 'NORTH' } },
-        { id: `${node.id}_right`, properties: { 'port.side': 'EAST' } },
-        { id: `${node.id}_bottom`, properties: { 'port.side': 'SOUTH' } },
-        { id: `${node.id}_left`, properties: { 'port.side': 'WEST' } },
-      ],
+      ports: cardinalPorts(node.id),
       properties: {
         'portConstraints': 'FIXED_SIDE',
         ...(layer !== undefined ? { 'layering.layer': String(layer) } : {}),
@@ -991,14 +1034,23 @@ export async function computeElkLayout(
       sizeOptions['elk.nodeSize.constraints'] = 'MINIMUM_SIZE';
       sizeOptions['elk.nodeSize.minimum'] = `(${g.minWidth},0)`;
     }
-    if (g.padTop != null) {
-      // Reserving the parent's own chrome. Children then start below it, and
-      // the parent's height still comes from ELK's fit.
-      sizeOptions['elk.padding'] = `[top=${g.padTop},left=12,bottom=12,right=12]`;
+    if (g.padTop != null || g.padBottom != null || g.padX != null) {
+      // Reserving the parent's own chrome. Children then sit inside it, and the
+      // parent's size still comes from ELK's fit. Each side falls back to the
+      // default padding, so setting only one side keeps the others as they were
+      // rather than collapsing them to zero.
+      sizeOptions['elk.padding'] =
+        `[top=${g.padTop ?? 12},left=${g.padX ?? 12},bottom=${g.padBottom ?? 12},right=${g.padX ?? 12}]`;
     }
     builtGroups.set(g.id, {
       id: g.id,
       children,
+      // Same side ports a leaf gets. An edge from outside the group terminates
+      // on the group, and ELK throws on a port reference it cannot resolve.
+      // Deliberately NOT `portConstraints: FIXED_SIDE` the way leaves are: each
+      // port already names its own `port.side`, which is what routes the edge,
+      // and pinning a parent could fight the layout of the children it holds.
+      ports: cardinalPorts(g.id),
       layoutOptions:
         Object.keys(sizeOptions).length > 0
           ? { ...compoundLayoutOptions, ...sizeOptions }