@principal-ai/subsystems-react 0.52.0 → 0.53.1

package/src/subsystem/C4NodeCard.test.ts

@@ -150,18 +150,21 @@ describe('nodeTopLabel — the technology, or the kind when none is stated', ()
     expect(
       nodeTopLabel(node({ containerKind: 'application', technology: 'Bun + Electrobun' })),
     ).toBe('Bun + Electrobun');
-    expect(nodeTopLabel(node({ kind: 'component', technology: 'React + ELK' }))).toBe('React + ELK');
   });
 
   test('a container with no technology falls back to its kind', () => {
     expect(nodeTopLabel(node({ containerKind: 'data-store', technology: '' }))).toBe('data-store');
   });
 
-  test('the other kinds fall back to their C4 kind', () => {
-    expect(nodeTopLabel(node({ kind: 'component' }))).toBe('component');
+  test('an external system / person falls back to its C4 kind', () => {
     expect(nodeTopLabel(node({ kind: 'external-system' }))).toBe('external-system');
     expect(nodeTopLabel(node({ kind: 'person' }))).toBe('person');
   });
+
+  test('a component has no top label — its technology is the container’s', () => {
+    expect(nodeTopLabel(node({ kind: 'component', technology: 'React + ELK' }))).toBe('');
+    expect(nodeTopLabel(node({ kind: 'component' }))).toBe('');
+  });
 });
 
 describe('nodeShape — kind without relying on colour or dash', () => {

package/src/subsystem/C4NodeCard.tsx

@@ -13,7 +13,7 @@
  */
 
 import { useTheme } from '@principal-ade/industry-theme';
-import { AppWindow, Database } from 'lucide-react';
+import { AppWindow, Component, Database, Maximize2 } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
 import { TechMark, technologyBrand } from './techIcons';
 import type { C4Element } from './c4';
@@ -50,6 +50,17 @@ export function nodeSize(node: C4Element): { width: number; height: number } {
  */
 const LABEL_SLOT_H = 40;
 
+/**
+ * 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
+ * air. The description is hidden while grown, so it is not part of this.
+ *
+ * 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;
+
 type Theme = ReturnType<typeof useTheme>['theme'];
 
 export interface NodeStyle {
@@ -151,14 +162,17 @@ export function nodeKindIcon(node: C4Element): LucideIcon | undefined {
  * The text on the top row: the technology the box is built with (Bun, React,
  * Postgres…). Falls back to the container kind / C4 kind when no technology is
  * stated, so the row is never blank.
+ *
+ * A component returns `''`: its technology is almost always the container's, so
+ * restating it is noise. The container frame already carries it.
  */
 export function nodeTopLabel(node: C4Element): string {
+  if (node.kind === 'component') return '';
   const technology = nodeTechnology(node);
   if (technology) return technology;
   switch (node.kind) {
     case 'container':
       return node.containerKind;
-    case 'component':
     case 'external-system':
     case 'person':
       return node.kind;
@@ -225,9 +239,37 @@ export interface C4NodeCardProps {
   /** Draw React Flow's edge handles. Off when rendering a bare gallery. */
   handles?: React.ReactNode;
   onClick?: () => void;
+  /**
+   * Number of `C4Component`s authored inside this element. The card can't see
+   * the model, so the graph passes it in; shown right-aligned on the technology
+   * row for containers. Omitted/0 → no count.
+   */
+  componentCount?: number;
+  /**
+   * When set, the card draws an expand affordance (bottom-right) that calls
+   * this — the drill-down trigger. Only containers with components pass it.
+   */
+  onExpand?: () => void;
+  /**
+   * Explicit box size, overriding the kind's default. Lets a host animate the
+   * card (the drill-down grow) without the card owning that state.
+   */
+  width?: number;
+  height?: number;
+  /**
+   * Show the description line under the label. Off when the card is grown to
+   * host components — the internals occupy that space.
+   * @default true
+   */
+  showDescription?: boolean;
+  /**
+   * Content drawn below the header (label / technology / description). Used by
+   * the grown card to host its component cards.
+   */
+  children?: React.ReactNode;
 }
 
-export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeCardProps) {
+export function C4NodeCard({ node, selected = false, handles, onClick, componentCount = 0, onExpand, width, height, showDescription = true, children }: C4NodeCardProps) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const style = nodeStyle(node, theme, selected);
@@ -246,8 +288,10 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
     <div
       onClick={onClick}
       style={{
-        width: size.width,
-        minHeight: size.height,
+        position: 'relative',
+        width: width ?? size.width,
+        minHeight: height ?? size.height,
+        transition: 'width 420ms ease-out, min-height 420ms ease-out',
         boxSizing: 'border-box',
         display: 'flex',
         flexDirection: 'column',
@@ -265,71 +309,104 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
         fontFamily: theme.fonts.body,
       }}
     >
-      {/* Left: the brand mark when we hold the official one, then the
-          technology. Right: a container's C4 sort, application vs data-store.
-          The kind itself stays on the shape, confirmation on the border (see
-          `nodeShape`, `nodeStyle`). */}
+      {/* The label row: the kind mark, then the name. 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={{
           display: 'flex',
-          alignItems: 'center',
+          alignItems: 'flex-start',
           justifyContent: centered ? 'center' : 'space-between',
           gap: 6,
-          fontFamily: theme.fonts.monospace,
-          fontSize: theme.fontSizes[0],
-          color: muted,
-          letterSpacing: 0.5,
-          textTransform: 'uppercase',
+          height: LABEL_SLOT_H,
           minWidth: 0,
         }}
       >
-        <span style={{ display: 'flex', alignItems: 'center', gap: 6, minWidth: 0 }}>
-          {brand && <TechMark brand={brand} />}
-          <span
-            style={{
-              fontWeight: 600,
-              whiteSpace: 'nowrap',
-              overflow: 'hidden',
-              textOverflow: 'ellipsis',
-              minWidth: 0,
-            }}
-          >
-            {topLabel}
-          </span>
+        <span
+          style={{
+            fontFamily: theme.fonts.body,
+            fontWeight: 600,
+            fontSize: theme.fontSizes[2],
+            color: theme.colors.text,
+            lineHeight: 1.25,
+            maxHeight: LABEL_SLOT_H,
+            display: '-webkit-box',
+            WebkitLineClamp: 2,
+            WebkitBoxOrient: 'vertical',
+            overflow: 'hidden',
+            textAlign: centered ? 'center' : 'left',
+            minWidth: 0,
+          }}
+        >
+          {node.label}
         </span>
         {Icon && (
           <span
-            title={node.kind === 'container' ? node.containerKind : node.kind}
             aria-label={node.kind === 'container' ? node.containerKind : node.kind}
-            style={{ display: 'inline-flex', flexShrink: 0, color: style.color }}
+            style={{
+              display: 'inline-flex',
+              flexShrink: 0,
+              color: style.color,
+              // Nudge down so the glyph optically centres on the first text line.
+              marginTop: 3,
+            }}
           >
-            <Icon size={13} strokeWidth={2.25} />
+            <Icon size={16} strokeWidth={2.25} />
           </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. */}
+      {/* The technology row: the brand mark when we hold the official one, then
+          the technology. For a container, right-aligned, the number of members
+          it groups. The kind itself stays on the shape, confirmation on the
+          border (see `nodeShape`, `nodeStyle`). */}
       <span
         style={{
-          fontFamily: theme.fonts.body,
-          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',
-          textAlign: centered ? 'center' : 'left',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: centered ? 'center' : 'space-between',
+          gap: 6,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          color: muted,
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+          minWidth: 0,
         }}
-        title={node.label}
       >
-        {node.label}
+        {topLabel && (
+          <span style={{ display: 'flex', alignItems: 'center', gap: 6, minWidth: 0 }}>
+            {brand && <TechMark brand={brand} />}
+            <span
+              style={{
+                fontWeight: 600,
+                whiteSpace: 'nowrap',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                minWidth: 0,
+              }}
+            >
+              {topLabel}
+            </span>
+          </span>
+        )}
+        {node.kind === 'container' && (
+          <span
+            style={{
+              flexShrink: 0,
+              letterSpacing: 0,
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 4,
+            }}
+          >
+            {componentCount}
+            <Component size={12} strokeWidth={2.25} />
+          </span>
+        )}
       </span>
-      {subtitle && (
+      {showDescription && subtitle && (
         <span
           style={{
             fontFamily: theme.fonts.monospace,
@@ -344,6 +421,38 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
           {subtitle}
         </span>
       )}
+      {children}
+      {/* Drill-down affordance: bottom-right, its own hit target so the card's
+          own click (select) is unaffected. */}
+      {onExpand && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onExpand();
+          }}
+          aria-label="Show components"
+          style={{
+            position: 'absolute',
+            right: 6,
+            bottom: 6,
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: 22,
+            height: 22,
+            padding: 0,
+            borderRadius: 4,
+            border: `1px solid ${style.color}`,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            color: style.color,
+            cursor: 'pointer',
+            lineHeight: 1,
+          }}
+        >
+          <Maximize2 size={13} strokeWidth={2.25} />
+        </button>
+      )}
       {handles}
     </div>
   );

package/src/subsystem/IssueList.category.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test';
+import { issueCategory, issueKindLabel } from './IssueList';
+
+/**
+ * Every C4 process-verification kind must land in the dynamic-topology
+ * category. These kinds are emitted by new audit passes over time, and an
+ * unmapped kind silently falls through to `construct` — the list then files a
+ * process finding under Constructs while the maintenance lane tally counts it
+ * as dynamic-topology, so the construct lane reads verified (green) beside a
+ * process issue. The regressions are real: `boundary_process_missing` shipped
+ * unmapped long before the container-first kinds joined it.
+ */
+describe('issueCategory — C4 process kinds', () => {
+  const processKinds = [
+    'boundary_process_missing',
+    'boundary_process_nest_disagree',
+    'boundary_process_unassigned',
+    'boundary_process_proposed',
+    'boundary_process_rejected',
+    'boundary_process_unbacked',
+  ];
+
+  for (const kind of processKinds) {
+    test(`${kind} categorizes as dynamic-topology`, () => {
+      expect(issueCategory({ id: 'x', severity: 'info', kind, message: '' })).toBe(
+        'dynamic-topology',
+      );
+    });
+  }
+
+  test('mapped kinds get human labels, not the humanized fallback', () => {
+    expect(issueKindLabel({ id: 'x', severity: 'info', kind: 'boundary_process_missing', message: '' })).toBe(
+      'Process claim missing',
+    );
+    expect(issueKindLabel({ id: 'x', severity: 'info', kind: 'boundary_process_unbacked', message: '' })).toBe(
+      'Process claim unbacked',
+    );
+  });
+});

package/src/subsystem/IssueList.tsx

@@ -20,12 +20,14 @@ import {
   CircleDashed,
   CircleEllipsis,
   CircleHelp,
+  CircleSlash,
   CircleX,
   Component,
   FileX,
   FolderGit2,
   Footprints,
   History,
+  Link2Off,
   MapPin,
   Network,
   Route,
@@ -112,9 +114,11 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   // C4 process verification (verifyProcessBoundaries): a boundary whose
   // container claim is not an accepted one. `verified` reports nothing —
   // the audit reports absence only.
+  boundary_process_missing: 'dynamic-topology',
   boundary_process_unassigned: 'dynamic-topology',
   boundary_process_proposed: 'dynamic-topology',
   boundary_process_rejected: 'dynamic-topology',
+  boundary_process_unbacked: 'dynamic-topology',
   trail: 'trail',
   step_unconfirmed: 'trail',
   step_stale: 'trail',
@@ -180,9 +184,12 @@ export const ISSUE_KIND_ICON: Record<string, LucideIcon> = {
   boundary_process_nest_disagree: Split,
   // C4 process verification: unclaimed = no container at all, proposed = an
   // agent scaffold awaits a decision, rejected = a container was declined.
+  boundary_process_missing: CircleSlash,
   boundary_process_unassigned: CircleEllipsis,
   boundary_process_proposed: CircleDashed,
   boundary_process_rejected: CircleX,
+  // Container-first gate: a claim cites a key no accepted container owns.
+  boundary_process_unbacked: Link2Off,
   // Trail step verification: unconfirmed = no augmentation yet, stale = code changed
   step_unconfirmed: CircleHelp,
   step_stale: History,
@@ -267,9 +274,11 @@ const KIND_LABEL: Record<string, string> = {
   boundary_process_nest_disagree: 'Module spans multiple process contexts',
   // C4 process verification (labels read as boundary states, since the layer
   // scopes them to process frames).
+  boundary_process_missing: 'Process claim missing',
   boundary_process_unassigned: 'Process boundary unclaimed',
   boundary_process_proposed: 'Container awaiting decision',
   boundary_process_rejected: 'Container rejected',
+  boundary_process_unbacked: 'Process claim unbacked',
   trail: 'Step issue',
   step_unconfirmed: 'Call site not verified',
   step_stale: 'Call site changed',
@@ -304,9 +313,11 @@ const KIND_ORDER: Record<string, number> = {
   boundary_module_file_mismatch: 23,
   // Runtime topology — process containment
   boundary_process_nest_disagree: 30,
-  boundary_process_unassigned: 31,
-  boundary_process_proposed: 32,
-  boundary_process_rejected: 33,
+  boundary_process_missing: 31,
+  boundary_process_unassigned: 32,
+  boundary_process_unbacked: 33,
+  boundary_process_proposed: 34,
+  boundary_process_rejected: 35,
   // Trail — mechanical issues first, then step verification
   trail: 40,
   step_unconfirmed: 41,

package/src/subsystem/c4.ts

@@ -153,7 +153,11 @@ export interface C4ElementSet {
 /** Which level to draw. Determines which frames are drawn. */
 export type C4View = 'container' | 'component';
 
-/** A compound frame: the system, or a container holding its components. */
+/**
+ * A compound frame the renderer draws: the system, or a container holding its
+ * components. Never authored — `deriveC4Groups` produces these from the element
+ * `parentId` chains and the current scope.
+ */
 export interface C4Group {
   id: string;
   kind: 'system' | 'container';
@@ -162,6 +166,63 @@ export interface C4Group {
   memberIds: string[];
 }
 
+/**
+ * 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.
+ */
+export function deriveC4Groups(
+  model: Pick<C4Model, 'view' | 'system' | 'nodes' | 'openContainerId'>,
+): 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;
+  // 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;
+
+  const framedContainers: string[] = [];
+  for (const c of containers) {
+    const members = components
+      .filter((comp) => (comp.container ?? comp.parentId) === c.id)
+      .map((comp) => comp.id);
+    if (members.length > 0 && framing(c.id)) {
+      groups.push({
+        id: c.id,
+        kind: 'container',
+        label: c.label,
+        parentId: model.system.id,
+        memberIds: members,
+      });
+      framedContainers.push(c.id);
+    }
+  }
+
+  // The system frame wraps the framed containers (component view) or the whole
+  // set of containers (container view) — the boundary is the system, so it must
+  // NOT shrink to the opened container. Opening one adds a nested container
+  // frame inside it; the system frame still spans everything.
+  const systemMembers =
+    model.view === 'component' ? framedContainers : containers.map((c) => c.id);
+  if (systemMembers.length > 0) {
+    groups.push({
+      id: model.system.id,
+      kind: 'system',
+      label: model.system.label,
+      memberIds: systemMembers,
+    });
+  }
+
+  return groups;
+}
+
 /**
  * A line between two elements. Authored, like the boxes.
  *
@@ -229,13 +290,23 @@ export function protocolColor(protocol: string | undefined): string {
   return best ? PROTOCOL_COLOR[best]! : PROTOCOL_COLOR_FALLBACK;
 }
 
-/** A drawable C4 projection. Authored, not derived. */
+/**
+ * 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.
+ */
 export interface C4Model {
   view: C4View;
   system: { id: string; label: string; repoKey?: string };
   nodes: C4Element[];
-  groups: C4Group[];
   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.
+   */
+  openContainerId?: string | null;
 }
 
 /**