@principal-ai/subsystems-react 0.50.0 → 0.51.0

package/src/subsystem/C4Graph.tsx

@@ -25,7 +25,8 @@ import {
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout } from '../utils/elkLayout';
-import { describeConstructBreakdown, MECHANISM_COLOR } from './model';
+import { MECHANISM_COLOR } from './model';
+import { C4NodeCard, NODE_H, NODE_W, nodeStyle } from './C4NodeCard';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
 import type { C4Model, C4Node } from './toC4';
 
@@ -35,104 +36,24 @@ export interface C4GraphProps {
   onSelectNode?: (id: string | null) => void;
 }
 
-const NODE_W = 230;
-const NODE_H = 80;
-
-function baseName(path: string): string {
-  const parts = path.split('/').filter(Boolean);
-  return parts[parts.length - 1] ?? path;
-}
-
 function edgeColor(mechanism: string | undefined, fallback: string): string {
   if (!mechanism) return fallback;
   return (MECHANISM_COLOR as Record<string, string>)[mechanism] ?? fallback;
 }
 
 function C4NodeView(props: NodeProps<Node<{ node: C4Node; selected: boolean }>>) {
-  const { theme } = useTheme();
   const { node, selected } = props.data;
-  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-
-  const kindColor =
-    node.kind === 'external'
-      ? (theme.colors.warning ?? theme.colors.accent ?? theme.colors.info)
-      : node.kind === 'actor'
-        ? (theme.colors.accent ?? theme.colors.info)
-        : (theme.colors.border ?? '#333');
-
-  const tag = node.kind === 'container' ? 'container' : node.kind === 'external' ? 'external system' : node.kind === 'actor' ? 'actor' : 'component';
-
-  const subtitle =
-    node.kind === 'component'
-      ? `${node.component?.construct ?? 'code'}${node.component?.file ? ` · ${baseName(node.component.file)}` : ''}`
-      : `${describeConstructBreakdown(node.constructs)}${
-          node.members.length > 0 ? ` · ${node.members.length} component${node.members.length === 1 ? '' : 's'}` : ''
-        }`;
-
   return (
-    <div
-      style={{
-        width: NODE_W,
-        height: NODE_H,
-        boxSizing: 'border-box',
-        display: 'flex',
-        flexDirection: 'column',
-        justifyContent: 'center',
-        gap: 2,
-        padding: '8px 12px',
-        borderRadius: node.kind === 'actor' ? 20 : 8,
-        background: theme.colors.backgroundSecondary ?? theme.colors.background,
-        border: `2px ${node.kind === 'component' ? 'solid' : node.kind === 'container' ? 'solid' : 'dashed'} ${
-          selected ? theme.colors.primary : kindColor
-        }`,
-        boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
-        cursor: 'pointer',
-        fontFamily: theme.fonts.body,
-      }}
-    >
-      <span
-        style={{
-          fontFamily: theme.fonts.monospace,
-          fontSize: theme.fontSizes[0],
-          letterSpacing: 0.5,
-          textTransform: 'uppercase',
-          color: kindColor,
-          whiteSpace: 'nowrap',
-          overflow: 'hidden',
-          textOverflow: 'ellipsis',
-        }}
-      >
-        {tag}
-      </span>
-      <span
-        style={{
-          fontWeight: 600,
-          fontSize: theme.fontSizes[2],
-          color: theme.colors.text,
-          whiteSpace: 'nowrap',
-          overflow: 'hidden',
-          textOverflow: 'ellipsis',
-        }}
-        title={node.label}
-      >
-        {node.label}
-      </span>
-      <span
-        style={{
-          fontFamily: theme.fonts.monospace,
-          fontSize: theme.fontSizes[0],
-          color: muted,
-          whiteSpace: 'nowrap',
-          overflow: 'hidden',
-          textOverflow: 'ellipsis',
-        }}
-        title={node.members.join(', ')}
-      >
-        {subtitle}
-      </span>
-      <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
-      <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
-    </div>
+    <C4NodeCard
+      node={node}
+      selected={selected}
+      handles={
+        <>
+          <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
+          <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
+        </>
+      }
+    />
   );
 }
 
@@ -212,7 +133,7 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     const rfNodes: Node[] = model.nodes.map((n, i) => ({
       id: n.id,
       type: 'c4-node',
-      position: { x: (i % 4) * (NODE_W + 60), y: Math.floor(i / 4) * (NODE_H + 40) },
+      position: { x: (i % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
       width: NODE_W,
       height: NODE_H,
       ...(n.parentId ? { parentId: n.parentId } : {}),
@@ -431,6 +352,44 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
             {selected.kind} · {selected.members.length} component{selected.members.length === 1 ? '' : 's'}
             {selected.models && selected.models.length > 0 ? ` · ${selected.models.length} model${selected.models.length === 1 ? '' : 's'}` : ''}
           </div>
+
+          {/* Confirmation state, with what is still missing. */}
+          {selected.kind === 'container' && (
+            <div
+              style={{
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                color: muted,
+                borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
+                paddingTop: 6,
+                marginBottom: 8,
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 3,
+              }}
+            >
+              <span style={{ color: nodeStyle(selected, theme).color }}>
+                {selected.decoration?.state ?? 'unconfirmed'} · {selected.decoration?.type ?? 'no type'}
+              </span>
+              {selected.decoration?.technology ? (
+                <span>technology: {selected.decoration.technology}</span>
+              ) : (
+                <span style={{ color: theme.colors.warning ?? '#e8a33a' }}>technology: not stated</span>
+              )}
+              {selected.decoration?.description ? (
+                <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>{selected.decoration.description}</span>
+              ) : (
+                <span style={{ color: theme.colors.warning ?? '#e8a33a' }}>description: not stated</span>
+              )}
+              {/* A merge hides its inputs, so always show what it absorbed. */}
+              {selected.sourceKeys && selected.sourceKeys.length > 1 && (
+                <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>
+                  merged from: {selected.sourceKeys.join(', ')}
+                </span>
+              )}
+            </div>
+          )}
+
           <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
             {selected.members.map((alias) => (
               <span

package/src/subsystem/C4NodeCard.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from 'bun:test';
+import { nodeStyle, nodeSubtitle, nodeTag, nodeMissing, NODE_W, NODE_H } from './C4NodeCard';
+import type { C4Node, C4ElementType, C4AssociationState } from './toC4';
+
+const theme = {
+  colors: {
+    border: '#555',
+    primary: '#4ec9b0',
+    warning: '#e8a33a',
+    accent: '#e3b341',
+    info: '#0ea5e9',
+  },
+} as Parameters<typeof nodeStyle>[1];
+
+function node(over: Partial<C4Node> = {}): C4Node {
+  return { id: 'n', kind: 'container', label: 'n', members: [], constructs: [], isStore: false, ...over };
+}
+
+function decorated(state: C4AssociationState, extra: Record<string, unknown> = {}): C4Node {
+  return node({ decoration: { id: 'container:x', state, ...extra } as C4Node['decoration'] });
+}
+
+describe('nodeStyle', () => {
+  test('selected overrides everything', () => {
+    expect(nodeStyle(decorated('accepted'), theme, true).width).toBe(3);
+    expect(nodeStyle(node(), theme, true).color).toBe('#4ec9b0');
+  });
+
+  test('accepted is solid and uses the primary colour', () => {
+    const s = nodeStyle(decorated('accepted'), theme);
+    expect(s.dash).toBe('solid');
+    expect(s.color).toBe('#4ec9b0');
+  });
+
+  test('proposed is dashed and uses the warning colour', () => {
+    const s = nodeStyle(decorated('proposed'), theme);
+    expect(s.dash).toBe('dashed');
+    expect(s.color).toBe('#e8a33a');
+  });
+
+  test('rejected is dotted and muted', () => {
+    const s = nodeStyle(decorated('rejected'), theme);
+    expect(s.dash).toBe('dotted');
+    expect(s.color).toBe('#555');
+  });
+
+  test('no association is muted, so confirmed boxes read stronger', () => {
+    expect(nodeStyle(node(), theme).color).toBe('#555');
+  });
+
+  test('an external and an actor are distinguished without an association', () => {
+    expect(nodeStyle(node({ kind: 'external' }), theme).color).toBe('#e8a33a');
+    expect(nodeStyle(node({ kind: 'actor' }), theme).color).toBe('#e3b341');
+  });
+
+  test('confirmation state wins over kind', () => {
+    const s = nodeStyle(decorated('accepted'), theme);
+    expect(s.color).toBe('#4ec9b0');
+  });
+
+  test('falls back safely when the theme has no colour', () => {
+    const bare = { colors: {} } as Parameters<typeof nodeStyle>[1];
+    expect(() => nodeStyle(decorated('accepted'), bare)).not.toThrow();
+    expect(nodeStyle(decorated('accepted'), bare).dash).toBe('solid');
+  });
+});
+
+describe('nodeTag', () => {
+  test('names the confirmation state ahead of the C4 kind', () => {
+    expect(nodeTag(decorated('accepted'))).toBe('confirmed');
+    expect(nodeTag(decorated('proposed'))).toBe('proposed');
+    expect(nodeTag(decorated('rejected'))).toBe('rejected');
+  });
+
+  test('falls back to the kind when there is no association', () => {
+    expect(nodeTag(node())).toBe('container');
+    expect(nodeTag(node({ kind: 'external' }))).toBe('external');
+    expect(nodeTag(node({ kind: 'actor' }))).toBe('actor');
+  });
+});
+
+describe('nodeSubtitle', () => {
+  test('shows type and technology once confirmed', () => {
+    const s = nodeSubtitle(
+      decorated('accepted', { type: 'application', technology: 'Bun + Electrobun' }),
+    );
+    expect(s).toBe('application · Bun + Electrobun');
+  });
+
+  test('omits technology when it was never stated', () => {
+    expect(nodeSubtitle(decorated('accepted', { type: 'data-store' }))).toBe('data-store');
+  });
+
+  test('falls back to the construct breakdown for a raw container', () => {
+    const s = nodeSubtitle(node({ constructs: ['function', 'store'], members: ['a', 'b'] }));
+    expect(s).toContain('function');
+    expect(s).toContain('store');
+    expect(s).toContain('2 components');
+  });
+
+  test('singularises a single member', () => {
+    const s = nodeSubtitle(node({ constructs: ['function'], members: ['a'] }));
+    expect(s).toContain('1 component');
+    expect(s).not.toContain('1 components');
+  });
+
+  test('a component shows its construct and file basename', () => {
+    const s = nodeSubtitle(
+      node({
+        kind: 'component',
+        component: {
+          alias: 'a',
+          name: 'buildGroups',
+          construct: 'function',
+          file: 'src/subsystem/model.ts',
+          purl: 'pkg:x#src/subsystem/model.ts',
+        },
+      }),
+    );
+    expect(s).toBe('function · model.ts');
+  });
+});
+
+describe('nodeMissing', () => {
+  test('a bare container reports both notation gaps', () => {
+    expect(nodeMissing(node())).toEqual(['technology', 'description']);
+  });
+
+  test('one supplied gap drops only that one', () => {
+    expect(nodeMissing(decorated('accepted', { technology: 'React' }))).toEqual(['description']);
+  });
+
+  test('a fully stated container reports nothing', () => {
+    expect(
+      nodeMissing(decorated('accepted', { technology: 'React', description: 'Renders graphs.' })),
+    ).toEqual([]);
+  });
+
+  test('the requirement is on containers only', () => {
+    expect(nodeMissing(node({ kind: 'external' }))).toEqual([]);
+    expect(nodeMissing(node({ kind: 'actor' }))).toEqual([]);
+    expect(nodeMissing(node({ kind: 'component' }))).toEqual([]);
+  });
+});
+
+describe('card metrics', () => {
+  test('exposes the size the graph lays out against', () => {
+    expect(NODE_W).toBeGreaterThan(0);
+    expect(NODE_H).toBeGreaterThan(0);
+  });
+
+  test('is near-square, not a wide strip', () => {
+    // The card carries four fields (tag, label, type+technology, notation
+    // gap). A 3:1 strip truncates the last two; this is the aspect ratio that
+    // lets each sit on its own line.
+    const ratio = NODE_W / NODE_H;
+    expect(ratio).toBeGreaterThan(1);
+    expect(ratio).toBeLessThan(1.8);
+  });
+
+  test('is tall enough for four lines of content', () => {
+    // tag + 2-line label + subtitle + gap marker, plus 8px padding top/bottom.
+    expect(NODE_H).toBeGreaterThanOrEqual(130);
+  });
+
+  test('leaves breathing room around four lines of text', () => {
+    // Top-aligned now, not centred, so this is about slack rather than
+    // balance: tag + 2-line label slot + subtitle + gap slot + padding.
+    const contentBudget = 16 + 40 + 16 + 18 + 20; // lines + 10px padding ×2
+    expect(NODE_H - contentBudget).toBeGreaterThanOrEqual(12);
+  });
+
+  test('fits the longest real container label on two lines', () => {
+    // "subsystems-studio/renderer" is the longest label the 40 stored models
+    // produce. It must be allowed to wrap rather than ellipsize.
+    expect(NODE_W).toBeGreaterThanOrEqual(200);
+  });
+});
+
+/** Compile-time guard: every declared element type is reachable from a card. */
+const ALL_TYPES: C4ElementType[] = [
+  'application',
+  'data-store',
+  'queue',
+  'library',
+  'software-system',
+  'person',
+];
+
+describe('element types', () => {
+  test('each one renders as a subtitle without special-casing', () => {
+    for (const type of ALL_TYPES) {
+      expect(nodeSubtitle(decorated('accepted', { type }))).toBe(type);
+    }
+  });
+});

package/src/subsystem/C4NodeCard.tsx

@@ -0,0 +1,307 @@
+/**
+ * C4NodeCard — the box an element draws as, with nothing else.
+ *
+ * Extracted from `C4Graph.tsx` so the visual encoding can be inspected,
+ * reviewed, and unit-tested without standing up a graph. React Flow supplies
+ * edges and hit-testing; this supplies the reading surface.
+ *
+ * The encoding has one job: make confirmation state legible at a glance. A box
+ * nobody has looked at must not read the same as a box a person signed off.
+ * Everything else here is C4 notation — a type, a technology, a description —
+ * surfaced in the order a reader wants it.
+ */
+
+import { useTheme } from '@principal-ade/industry-theme';
+import { describeConstructBreakdown } from './model';
+import type { C4Node } from './toC4';
+
+/**
+ * Card box. Near-square rather than a wide strip: a C4 element carries four
+ * things at once (tag, label, type + technology, and the notation gap it still
+ * has), and a wide strip forces the last two to truncate. The extra height is
+ * what lets the `needs …` marker sit on its own line instead of clipping.
+ */
+export const NODE_W = 210;
+export const NODE_H = 138;
+
+/**
+ * Fixed slot heights, so rows line up across every card regardless of which
+ * optional fields are present. Without these a card missing its notation-gap
+ * marker is two lines shorter and a row of cards reads as ragged.
+ */
+const LABEL_SLOT_H = 40;
+const GAP_SLOT_H = 18;
+
+type Theme = ReturnType<typeof useTheme>['theme'];
+
+export interface NodeStyle {
+  color: string;
+  dash: string;
+  width: number;
+}
+
+/**
+ * Border style and colour for one node, by what we know about it.
+ *
+ * Confirmation state wins over C4 kind: an accepted container and a raw
+ * derived container are both "containers", and the reader's first question
+ * about either is whether anyone vouched for it.
+ */
+export function nodeStyle(node: C4Node, theme: Theme, selected = false): NodeStyle {
+  const muted = theme.colors.border ?? '#555';
+  if (selected) return { color: theme.colors.primary ?? '#5aa', dash: 'solid', width: 3 };
+
+  // Border width carries the C4 level, so a component stays a component even
+  // in grayscale or for a reader who cannot separate the hues.
+  const weight = node.kind === 'component' ? 1 : 2;
+
+  switch (node.decoration?.state) {
+    case 'accepted':
+      // Solid and saturated — part of the architecture now.
+      return { color: theme.colors.primary ?? '#4ec9b0', dash: 'solid', width: weight };
+    case 'proposed':
+      // Dashed — an agent asked; a human has not answered.
+      return { color: theme.colors.warning ?? '#e8a33a', dash: 'dashed', width: weight };
+    case 'rejected':
+      // Should never be drawn (toC4 drops it); belt-and-braces.
+      return { color: muted, dash: 'dotted', width: 1 };
+    default:
+      break;
+  }
+
+  // No association at all — the raw derivation. Muted, so confirmed boxes
+  // read as the stronger signal.
+  switch (node.kind) {
+    case 'external':
+      return { color: theme.colors.warning ?? '#a78bfa', dash: 'solid', width: weight };
+    case 'actor':
+      return { color: theme.colors.accent ?? theme.colors.info ?? '#e3b341', dash: 'solid', width: weight };
+    default:
+      return { color: muted, dash: 'solid', width: weight };
+  }
+}
+
+function baseName(path: string): string {
+  const parts = path.split('/').filter(Boolean);
+  return parts[parts.length - 1] ?? path;
+}
+
+/** The type + technology line under the label. */
+export function nodeSubtitle(node: C4Node): string {
+  const d = node.decoration;
+  if (d?.type || d?.technology) return [d.type, d.technology].filter(Boolean).join(' · ');
+
+  // No confirmed attributes: fall back to what the document told us.
+  if (node.kind === 'component') {
+    return `${node.component?.construct ?? 'code'}${node.component?.file ? ` · ${baseName(node.component.file)}` : ''}`;
+  }
+  const count = node.members.length;
+  return `${describeConstructBreakdown(node.constructs)}${count > 0 ? ` · ${count} component${count === 1 ? '' : 's'}` : ''}`;
+}
+
+/**
+ * The C4 level — what the box IS.
+ *
+ * Deliberately independent of confirmation state. An accepted container is
+ * still a container, and a component is a component whether or not anyone has
+ * reviewed it; collapsing the two into one label is what made the two
+ * indistinguishable. Confirmation is a separate axis (`nodeStateTag`).
+ */
+export function nodeTag(node: C4Node): string {
+  return node.kind;
+}
+
+/**
+ * Confirmation state, as its own short tag. Empty when nothing was proposed —
+ * which is itself the distinction from a reviewed element.
+ */
+export function nodeStateTag(node: C4Node): string {
+  switch (node.decoration?.state) {
+    case 'accepted':
+      return 'confirmed';
+    case 'proposed':
+      return 'proposed';
+    case 'rejected':
+      return 'rejected';
+    default:
+      return 'unconfirmed';
+  }
+}
+
+/**
+ * Shape cue for the C4 level, independent of colour and dash pattern.
+ *
+ * Colour alone is not enough: a container and a component with no association
+ * both fall back to the muted border, so they were identical in grayscale.
+ * The convention:
+ *
+ *   container   solid rectangle   — a runtime boundary, drawn to scale
+ *   component   rounded rectangle — a part inside one, drawn smaller
+ *   external    rounded rectangle + dashed (nothing to confirm inside)
+ *   actor       fully rounded      — a person, not a box
+ */
+export function nodeShape(node: C4Node): { radius: number; dash: 'solid' | 'dashed' } {
+  switch (node.kind) {
+    case 'actor':
+      return { radius: NODE_H / 2, dash: 'solid' };
+    case 'external':
+      return { radius: 14, dash: 'dashed' };
+    case 'component':
+      return { radius: 14, dash: 'solid' };
+    default:
+      return { radius: 4, dash: 'solid' };
+  }
+}
+
+/**
+ * C4 notation requires a technology and a description on every container.
+ * Name the gaps rather than leaving them to be noticed.
+ */
+export function nodeMissing(node: C4Node): string[] {
+  if (node.kind !== 'container') return [];
+  const missing: string[] = [];
+  if (!node.decoration?.technology) missing.push('technology');
+  if (!node.decoration?.description) missing.push('description');
+  return missing;
+}
+
+export interface C4NodeCardProps {
+  node: C4Node;
+  selected?: boolean;
+  /** Draw React Flow's edge handles. Off when rendering a bare gallery. */
+  handles?: React.ReactNode;
+  onClick?: () => void;
+}
+
+export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeCardProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const style = nodeStyle(node, theme, selected);
+  const shape = nodeShape(node);
+  const missing = nodeMissing(node);
+  const unconfirmed = !node.decoration?.state;
+
+  return (
+    <div
+      onClick={onClick}
+      style={{
+        width: NODE_W,
+        minHeight: NODE_H,
+        boxSizing: 'border-box',
+        display: 'flex',
+        flexDirection: 'column',
+        // Top-aligned, not centred: the number of lines varies (the notation-gap
+        // 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,
+        padding: '10px 12px',
+        borderRadius: shape.radius,
+        background: theme.colors.backgroundSecondary ?? theme.colors.background,
+        border: `${style.width} ${style.dash} ${style.color}`,
+        boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+        cursor: onClick ? 'pointer' : 'default',
+        fontFamily: theme.fonts.body,
+      }}
+    >
+      {/* Level and state on one row, separately styled. The level is what the
+          box IS; the state is whether anyone has vouched for it. Merging them
+          into one label is what made containers and components unreadable. */}
+      <span
+        style={{
+          display: 'flex',
+          alignItems: 'baseline',
+          gap: 6,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+        }}
+      >
+        <span
+          style={{
+            color: style.color,
+            fontWeight: 600,
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            minWidth: 0,
+          }}
+        >
+          {nodeTag(node)}
+        </span>
+        <span
+          title={unconfirmed ? 'Nobody has reviewed this element yet' : undefined}
+          style={{
+            color: unconfirmed ? muted : style.color,
+            // Unconfirmed is a quiet absence, not a loud claim.
+            opacity: unconfirmed ? 0.75 : 1,
+            letterSpacing: 0,
+            textTransform: 'none',
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            minWidth: 0,
+          }}
+        >
+          {nodeStateTag(node)}
+        </span>
+      </span>
+      {/* Two lines rather than an ellipsis: a truncated label hides the very
+          thing that distinguishes two containers from each other. The fixed
+          height reserves both lines even for a one-line label, so the subtitle
+          below sits at the same y on every card. */}
+      <span
+        style={{
+          fontWeight: 600,
+          fontSize: theme.fontSizes[2],
+          color: theme.colors.text,
+          lineHeight: 1.25,
+          height: LABEL_SLOT_H,
+          display: '-webkit-box',
+          WebkitLineClamp: 2,
+          WebkitBoxOrient: 'vertical',
+          overflow: 'hidden',
+        }}
+        title={node.label}
+      >
+        {node.label}
+      </span>
+      <span
+        style={{
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          color: muted,
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+        }}
+        title={node.decoration?.description ?? node.members.join(', ')}
+      >
+        {nodeSubtitle(node)}
+      </span>
+      {/* Reserved row: without it, a card with no notation gap is two lines
+          shorter and the row of cards reads as ragged. */}
+      <span style={{ height: GAP_SLOT_H }} aria-hidden="true" />
+      {missing.length > 0 && (
+        <span
+          title={`C4 requires a ${missing.join(' and a ')} on every container`}
+          style={{
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+            color: theme.colors.warning ?? '#e8a33a',
+            lineHeight: 1.3,
+            height: GAP_SLOT_H,
+            display: '-webkit-box',
+            WebkitLineClamp: 2,
+            WebkitBoxOrient: 'vertical',
+            overflow: 'hidden',
+          }}
+        >
+          needs {missing.join(' + ')}
+        </span>
+      )}
+      {handles}
+    </div>
+  );
+}