@principal-ai/subsystems-react 0.51.4 → 0.53.0

package/src/subsystem/C4NodeCard.tsx

@@ -13,10 +13,10 @@
  */
 
 import { useTheme } from '@principal-ade/industry-theme';
-import { AppWindow, Database } from 'lucide-react';
+import { AppWindow, Component, Database } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
 import { TechMark, technologyBrand } from './techIcons';
-import type { C4Node } from './c4';
+import type { C4Element } from './c4';
 
 /**
  * Card box for a container: a wide rectangle. A container carries four things
@@ -38,7 +38,7 @@ export const COMPONENT_SIZE = 140;
  * Per-level box size. The graph lays out against these, so a square component
  * and a rectangular container do not collide at a shared nominal width.
  */
-export function nodeSize(node: C4Node): { width: number; height: number } {
+export function nodeSize(node: C4Element): { width: number; height: number } {
   return node.kind === 'component'
     ? { width: COMPONENT_SIZE, height: COMPONENT_SIZE }
     : { width: NODE_W, height: NODE_H };
@@ -59,35 +59,50 @@ export interface NodeStyle {
 }
 
 /**
- * Border style for one node: colour, dash and weight, from confirmation state
- * and level.
+ * Border style for one node: colour from **technology**, dash and weight from
+ * **confirmation state** and level.
  *
- * One axis per channel, so nothing is said twice and nothing is contradicted:
+ * One axis per channel, so nothing is said twice:
  *
- *   colour + dash  → confirmation state (the primary axis)
+ *   colour         → technology (the brand hue; see `technologyBrand`)
+ *   dash           → confirmation state (solid accepted, dashed proposed)
  *   weight         → C4 level, as a grayscale redundancy for the square
  *   shape + size   → C4 kind (`nodeShape`, `nodeSize`)
  *
- * State owning the dash is deliberate. An earlier build gave the dash to kind
- * and drew proposed boxes solid, quietly contradicting the one thing the
- * confirm UI needs a reader to see. Kind now says itself through shape, and
- * the border says who vouched for it.
+ * Colour moved from state to technology: on a container diagram the reader
+ * wants "is this Bun or React" at a glance, and the state already reads off the
+ * dash. A selected node overrides colour so a click target stands out.
  */
-export function nodeStyle(node: C4Node, theme: Theme, selected = false): NodeStyle {
+/** The technology string for an element, if its kind has one. */
+export function nodeTechnology(node: C4Element): string | undefined {
+  switch (node.kind) {
+    case 'container':
+    case 'component':
+      return node.technology;
+    case 'external-system':
+      return node.technology;
+    case 'person':
+      return undefined;
+  }
+}
+
+export function nodeStyle(node: C4Element, theme: Theme, selected = false): NodeStyle {
   const muted = theme.colors.border ?? '#555';
+  const techColor = technologyBrand(nodeTechnology(node))?.color;
   if (selected) return { color: theme.colors.primary ?? '#5aa', dash: 'solid', width: 3 };
 
   // Border weight carries the 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;
+  const color = techColor ?? muted;
 
   switch (node.state) {
     case 'accepted':
-      // Solid and saturated — part of the architecture now.
-      return { color: theme.colors.primary ?? '#4ec9b0', dash: 'solid', width: weight };
+      // Solid — part of the architecture now.
+      return { color, 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 };
+      return { color, dash: 'dashed', width: weight };
     case 'rejected':
       // Should never be drawn (a rejected element is not projected); belt-and-braces.
       return { color: muted, dash: 'dotted', width: 1 };
@@ -99,7 +114,7 @@ export function nodeStyle(node: C4Node, theme: Theme, selected = false): NodeSty
  * asks every element to carry. No fallback — when nothing is stated, the
  * notation-gap row says so rather than the card inventing a summary.
  */
-export function nodeSubtitle(node: C4Node): string {
+export function nodeSubtitle(node: C4Element): string {
   return node.description ?? '';
 }
 
@@ -109,7 +124,7 @@ export function nodeSubtitle(node: C4Node): string {
  * Confirmation state is a separate axis carried by the border (see
  * `nodeStyle`), not by a word on the card.
  */
-export function nodeTag(node: C4Node): string {
+export function nodeTag(node: C4Element): string {
   return node.kind;
 }
 
@@ -119,11 +134,17 @@ export function nodeTag(node: C4Node): string {
  * The C4 kind itself does not need a glyph — the box shape already carries it
  * (square vs rectangle vs pill), and the row's one text slot is worth more
  * spent on the technology. Only containers have a C4-recognised split, so the
- * other three kinds return nothing.
+ * other kinds return nothing.
  */
-export function nodeKindIcon(node: C4Node): LucideIcon | undefined {
-  if (node.kind !== 'container') return undefined;
-  return node.containerKind === 'data-store' ? Database : AppWindow;
+export function nodeKindIcon(node: C4Element): LucideIcon | undefined {
+  switch (node.kind) {
+    case 'container':
+      return node.containerKind === 'data-store' ? Database : AppWindow;
+    case 'component':
+    case 'external-system':
+    case 'person':
+      return undefined;
+  }
 }
 
 /**
@@ -131,9 +152,17 @@ export function nodeKindIcon(node: C4Node): LucideIcon | undefined {
  * Postgres…). Falls back to the container kind / C4 kind when no technology is
  * stated, so the row is never blank.
  */
-export function nodeTopLabel(node: C4Node): string {
-  if (node.technology) return node.technology;
-  return node.kind === 'container' ? (node.containerKind ?? 'container') : node.kind;
+export function nodeTopLabel(node: C4Element): string {
+  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;
+  }
 }
 
 /** How a box is drawn. Shape carries the C4 kind, independent of colour. */
@@ -151,26 +180,24 @@ export interface NodeShape {
  *
  * The convention:
  *
- *   container        wide rectangle, sharp corners — a runtime boundary
+ *   container        wide rectangle, slight radius — a runtime boundary
  *   component        square — a part inside one (see `nodeSize`)
- *   external system  wide rectangle, rounded     — someone else's system
+ *   external system  wide rectangle, no radius    — someone else's system
  *   person           pill                          — not a box at all
  *
- * An external system is separated from a container by radius alone, which is
- * a weak cue. That is deliberate rather than an oversight: the border dash is
- * the only channel that could say "outside our control" loudly, and it is
- * already spent on proposed-vs-accepted. The kind icon says it, and the frame
- * position says it structurally.
+ * A container keeps a slight radius; an external system is drawn with none, so
+ * the two are distinguishable by corner treatment as well as by the kind icon
+ * and frame position. The border dash stays spent on proposed-vs-accepted.
  */
-export function nodeShape(node: C4Node): NodeShape {
+export function nodeShape(node: C4Element): NodeShape {
   switch (node.kind) {
     case 'person':
       return { kind: 'pill', radius: NODE_H / 2 };
     case 'external-system':
-      return { kind: 'rect', radius: 14 };
+      return { kind: 'rect', radius: 0 };
     case 'component':
       return { kind: 'square', radius: 6 };
-    default:
+    case 'container':
       return { kind: 'rect', radius: 4 };
   }
 }
@@ -184,7 +211,7 @@ export function nodeShape(node: C4Node): NodeShape {
  * component drawn without a parent already reports `unknown_container`, and
  * that is the question worth asking first.
  */
-export function nodeMissing(node: C4Node): string[] {
+export function nodeMissing(node: C4Element): string[] {
   if (node.kind !== 'container') return [];
   const missing: string[] = [];
   if (!node.technology) missing.push('technology');
@@ -193,20 +220,26 @@ export function nodeMissing(node: C4Node): string[] {
 }
 
 export interface C4NodeCardProps {
-  node: C4Node;
+  node: C4Element;
   selected?: boolean;
   /** 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;
 }
 
-export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeCardProps) {
+export function C4NodeCard({ node, selected = false, handles, onClick, componentCount = 0 }: C4NodeCardProps) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const style = nodeStyle(node, theme, selected);
   const shape = nodeShape(node);
   const Icon = nodeKindIcon(node);
-  const brand = technologyBrand(node.technology);
+  const brand = technologyBrand(nodeTechnology(node));
   const topLabel = nodeTopLabel(node);
   const subtitle = nodeSubtitle(node);
 
@@ -232,16 +265,64 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
         padding: centered ? '10px 30px' : '10px 12px',
         borderRadius: shape.radius,
         background: theme.colors.backgroundSecondary ?? theme.colors.background,
-        border: `${style.width} ${style.dash} ${style.color}`,
+        border: `${style.width}px ${style.dash} ${style.color}`,
         boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
         cursor: onClick ? 'pointer' : 'default',
         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: 'flex-start',
+          justifyContent: centered ? 'center' : 'flex-start',
+          gap: 6,
+          height: LABEL_SLOT_H,
+          minWidth: 0,
+        }}
+      >
+        <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
+            aria-label={node.kind === 'container' ? node.containerKind : node.kind}
+            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={16} strokeWidth={2.25} />
+          </span>
+        )}
+      </span>
+      {/* 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={{
           display: 'flex',
@@ -270,37 +351,21 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
             {topLabel}
           </span>
         </span>
-        {Icon && (
+        {node.kind === 'container' && (
           <span
-            title={node.containerKind ?? node.kind}
-            aria-label={node.containerKind ?? node.kind}
-            style={{ display: 'inline-flex', flexShrink: 0, color: style.color }}
+            style={{
+              flexShrink: 0,
+              letterSpacing: 0,
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 4,
+            }}
           >
-            <Icon size={13} strokeWidth={2.25} />
+            {componentCount}
+            <Component size={12} 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. */}
-      <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',
-          textAlign: centered ? 'center' : 'left',
-        }}
-        title={node.label}
-      >
-        {node.label}
-      </span>
       {subtitle && (
         <span
           style={{

package/src/subsystem/IssueList.tsx

@@ -17,7 +17,10 @@ import {
   ChevronDown,
   ChevronRight,
   CircleCheck,
+  CircleDashed,
+  CircleEllipsis,
   CircleHelp,
+  CircleX,
   Component,
   FileX,
   FolderGit2,
@@ -41,6 +44,7 @@ export type SubsystemIssueSeverity = 'error' | 'info';
 export type SubsystemIssueTargetKind =
   | 'component'
   | 'module'
+  | 'process'
   | 'trail'
   | 'step'
   | 'repo'
@@ -105,6 +109,12 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   graphify_unavailable: 'repo',
   boundary_module_file_mismatch: 'static-topology',
   boundary_process_nest_disagree: 'dynamic-topology',
+  // C4 process verification (verifyProcessBoundaries): a boundary whose
+  // container claim is not an accepted one. `verified` reports nothing —
+  // the audit reports absence only.
+  boundary_process_unassigned: 'dynamic-topology',
+  boundary_process_proposed: 'dynamic-topology',
+  boundary_process_rejected: 'dynamic-topology',
   trail: 'trail',
   step_unconfirmed: 'trail',
   step_stale: 'trail',
@@ -168,6 +178,11 @@ export const ISSUE_KIND_ICON: Record<string, LucideIcon> = {
   // One module, more than one claimed process parent — a containment that can't
   // be drawn, which is why the region sits at the root instead of nested.
   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_unassigned: CircleEllipsis,
+  boundary_process_proposed: CircleDashed,
+  boundary_process_rejected: CircleX,
   // Trail step verification: unconfirmed = no augmentation yet, stale = code changed
   step_unconfirmed: CircleHelp,
   step_stale: History,
@@ -250,6 +265,11 @@ const KIND_LABEL: Record<string, string> = {
   graphify_unavailable: 'Graphify cache unavailable',
   boundary_module_file_mismatch: 'Declaration file outside module',
   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_unassigned: 'Process boundary unclaimed',
+  boundary_process_proposed: 'Container awaiting decision',
+  boundary_process_rejected: 'Container rejected',
   trail: 'Step issue',
   step_unconfirmed: 'Call site not verified',
   step_stale: 'Call site changed',
@@ -284,6 +304,9 @@ 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,
   // Trail — mechanical issues first, then step verification
   trail: 40,
   step_unconfirmed: 41,

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -39,6 +39,7 @@ import {
   deriveGraphEdges,
   isConstructsOnlyModel,
   moduleGroupNodeId,
+  processGroupNodeId,
   isTrailMechanism,
   edgeColor,
   MECHANISM_DESCRIPTIONS,
@@ -1099,16 +1100,24 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     [components],
   );
 
-  // A `module` issue target names a boundary frame, so focusing the card frames
-  // that region on the canvas. Null when the target names no frame (a singleton
-  // dropped from the layout, or a region key nothing declares).
-  const issueModuleNodeId = useCallback(
+  // A `module` / `process` issue target names a boundary frame, so focusing
+  // the card frames that region on the canvas. Null when the target names no
+  // frame (a singleton dropped from the layout, or a region key nothing
+  // declares).
+  const issueFrameNodeId = useCallback(
     (issue: SubsystemIssue): string | null => {
       const target = issue.target;
-      if (target?.kind !== 'module') return null;
-      const key = target.id ?? target.label;
-      if (!components.some((c) => c.module?.trim() === key)) return null;
-      return moduleGroupNodeId(key);
+      if (target?.kind === 'module') {
+        const key = target.id ?? target.label;
+        if (!components.some((c) => c.module?.trim() === key)) return null;
+        return moduleGroupNodeId(key);
+      }
+      if (target?.kind === 'process') {
+        const key = target.id ?? target.label;
+        if (!components.some((c) => c.process === key)) return null;
+        return processGroupNodeId(key);
+      }
+      return null;
     },
     [components],
   );
@@ -1159,7 +1168,9 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   }, [issues, issueComponent]);
 
   // Per-frame diagnostics badge: the same fold, but for findings about a
-  // BOUNDARY rather than a construct. Keyed by the region's React Flow node id.
+  // BOUNDARY rather than a construct. Keyed by the region's React Flow node
+  // id — a `module` target names a module frame, a `process` target a process
+  // frame (dynamic-topology findings, e.g. C4 process verification).
   // Only kinds with a dedicated frame icon qualify (`ISSUE_KIND_ICON`) — a
   // finding with no icon of its own has nothing to badge the frame with, and
   // borrowing its layer's icon would imply the frame is at fault for it.
@@ -1168,8 +1179,12 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     if (!issues?.length) return map;
     for (const issue of issues) {
       const target = issue.target;
-      if (target?.kind !== 'module' || !ISSUE_KIND_ICON[issue.kind]) continue;
-      const id = moduleGroupNodeId(target.id ?? target.label);
+      if (!target || !ISSUE_KIND_ICON[issue.kind]) continue;
+      if (target.kind !== 'module' && target.kind !== 'process') continue;
+      const id =
+        target.kind === 'module'
+          ? moduleGroupNodeId(target.id ?? target.label)
+          : processGroupNodeId(target.id ?? target.label);
       const prev = map.get(id);
       map.set(id, {
         severity:
@@ -1267,6 +1282,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   // target:
   //   component   → that node
   //   module      → every component in that module
+  //   process     → every component with that `process` key
   //   trail → the flow's nodes + its step edges
   //   repo        → every component of that repo
   //   graph       → whole-graph finding; implicates nothing specific
@@ -1298,6 +1314,11 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
             nodeIds.add(c.alias);
           }
         }
+      } else if (t.kind === 'process') {
+        const key = t.id ?? t.label;
+        for (const c of components) {
+          if (c.process === key) nodeIds.add(c.alias);
+        }
       } else if (t.kind === 'trail') {
         const wt = (trails ?? []).find(
           (w) => w.id === t.id || w.title === t.label,
@@ -1488,7 +1509,8 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
         // Host override wins over the library's derived frame color.
         const color = region?.key != null ? boundaryColors?.[region.key] : undefined;
         // Boundary findings badge the FRAME, not a member — a region's shape is
-        // the fault, so no leaf construct carries it.
+        // the fault, so no leaf construct carries it. Process verification
+        // findings ride the same path: their target kind is `process`.
         const regionIssue = regionIssueByNodeId.get(n.id);
         return {
           ...n,
@@ -2376,7 +2398,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
       } else {
         // Nothing selectable — but a module target names a boundary frame, so
         // frame that region.
-        const moduleNodeId = issueModuleNodeId(issue);
+        const moduleNodeId = issueFrameNodeId(issue);
         if (moduleNodeId) {
           setSelected(null);
           setSelectedEdgeId(null);
@@ -2394,7 +2416,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     [
       issueComponent,
       issueStep,
-      issueModuleNodeId,
+      issueFrameNodeId,
       focusTrailStep,
       onSelect,
       onSelectIssue,
@@ -2418,7 +2440,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
         setSelectedEdgeId(null);
       } else {
         const step = issueStep(issue);
-        const moduleNodeId = step ? null : issueModuleNodeId(issue);
+        const moduleNodeId = step ? null : issueFrameNodeId(issue);
         if (step) {
           // Only unwind a step focus this card still owns. A dim-mode graph
           // keeps its step focus in hover state instead (owned by the pointer,
@@ -2445,7 +2467,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
         fitView({ padding: 0.1, duration: 300, minZoom: 0.05, maxZoom: 2 });
       });
     },
-    [issueComponent, issueStep, issueModuleNodeId, fitView],
+    [issueComponent, issueStep, issueFrameNodeId, fitView],
   );
 
   // Construct tokens inside a trail snippet. A step's line is an edge

package/src/subsystem/c4.protocolColor.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'bun:test';
+import { PROTOCOL_COLOR, PROTOCOL_COLOR_FALLBACK, protocolColor } from './c4';
+
+describe('protocolColor', () => {
+  test('maps a known protocol to its hue', () => {
+    expect(protocolColor('HTTP')).toBe(PROTOCOL_COLOR.http);
+    expect(protocolColor('RPC')).toBe(PROTOCOL_COLOR.rpc);
+    expect(protocolColor('file I/O')).toBe(PROTOCOL_COLOR['file i/o']);
+  });
+
+  test('matches a token inside a longer protocol string', () => {
+    expect(protocolColor('Electrobun RPC')).toBe(PROTOCOL_COLOR.rpc);
+    expect(protocolColor('HTTPS')).toBe(PROTOCOL_COLOR.https);
+  });
+
+  test('prefers the longest matching token', () => {
+    // `JSON-RPC` must find `json-rpc`, not the shorter `rpc`.
+    expect(protocolColor('JSON-RPC')).toBe(PROTOCOL_COLOR['json-rpc']);
+  });
+
+  test('falls back for an unknown or missing protocol', () => {
+    expect(protocolColor('carrier pigeon')).toBe(PROTOCOL_COLOR_FALLBACK);
+    expect(protocolColor(undefined)).toBe(PROTOCOL_COLOR_FALLBACK);
+    expect(protocolColor('')).toBe(PROTOCOL_COLOR_FALLBACK);
+  });
+});