@principal-ai/subsystems-react 0.51.4 → 0.52.0

package/src/subsystem/C4NodeCard.tsx

@@ -16,7 +16,7 @@ import { useTheme } from '@principal-ade/industry-theme';
 import { AppWindow, 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,7 +220,7 @@ 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;
@@ -206,7 +233,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
   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,7 +259,7 @@ 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,
@@ -272,8 +299,8 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
         </span>
         {Icon && (
           <span
-            title={node.containerKind ?? node.kind}
-            aria-label={node.containerKind ?? node.kind}
+            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 }}
           >
             <Icon size={13} strokeWidth={2.25} />
@@ -286,6 +313,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
           below sits at the same y on every card. */}
       <span
         style={{
+          fontFamily: theme.fonts.body,
           fontWeight: 600,
           fontSize: theme.fontSizes[2],
           color: theme.colors.text,

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);
+  });
+});

package/src/subsystem/c4.ts

@@ -12,6 +12,12 @@
  * supplies the drawable model directly rather than having trails converted into
  * lines.
  *
+ * The element set is an umbrella over a model, not a standalone artifact: what
+ * sits inside a box resolves from the model document's `process` fields, folded
+ * to the claiming container's key by accepted consolidation records (see
+ * `c4Evidence`). Nothing here stores membership, so nothing here can drift from
+ * the model it organizes.
+ *
  * ## Why a union and not one type with two axes
  *
  * C4's vocabulary is closed: software system, container, component, code —
@@ -32,8 +38,6 @@
  * [C4 notation]: https://c4model.com/diagrams/notation
  */
 
-import type { SubsystemComponent } from './model';
-
 /**
  * Has anyone signed off on this element yet?
  *
@@ -53,27 +57,22 @@ interface C4ElementBase {
   /** Display name. */
   label: string;
   /**
-   * The component aliases that live directly inside this element.
-   *
-   * Named explicitly rather than derived from a `process` value, because two
-   * runs of code being one container is a judgement, not a lookup.
-   *
-   * Each alias belongs to exactly one element.
+   * Nesting parent. A component's container, or a container's system frame.
+   * Absent on an external system or a person — both are outside the boundary:
+   * an external is someone else's system, a person is never part of one.
    */
-  members: string[];
-  /**
-   * The `process` values this element consolidated, when it came from more than
-   * one. Purely provenance — it lets the confirm UI show "this box absorbed
-   * principal-studio/host". Never used to infer membership.
-   */
-  derivedFrom?: string[];
+  parentId?: string;
   /** C4 asks every element to carry a one-line responsibility. */
   description?: string;
   state: C4ElementState;
   /** Why this element is proposed as it is — shown in the confirm UI. */
   rationale?: string;
-  /** Who or what authored it. */
-  author?: string;
+  /** The component aliases this element groups. */
+  members?: string[];
+  /** Distinct constructs among the members, when resolved from a document. */
+  constructs?: string[];
+  /** Source model ids that contributed members, when attribution is supplied. */
+  models?: string[];
   /** When the state last changed (ISO). */
   decidedAt?: string;
 }
@@ -96,6 +95,12 @@ export interface C4Container extends C4ElementBase {
   containerKind: C4ContainerKind;
   /** C4 requires a technology on every container. */
   technology: string;
+  /**
+   * The `process` key this container claims — the boundary it verifies,
+   * matched exactly against the model document's keys. Not a member list:
+   * the components inside resolve from the model document.
+   */
+  process?: string;
 }
 
 /**
@@ -114,7 +119,6 @@ export interface C4Component extends C4ElementBase {
   /** C4 requires a technology on every component. */
   technology: string;
 }
-
 /** A software system outside the boundary we are drawing. */
 export interface C4ExternalSystem extends C4ElementBase {
   kind: 'external-system';
@@ -130,7 +134,14 @@ export interface C4Person extends C4ElementBase {
 /** One element. Four kinds, no fifth. */
 export type C4Element = C4Container | C4Component | C4ExternalSystem | C4Person;
 
-/** A whole authored element list, for one repo or composed graph. */
+/**
+ * A whole authored element list, for one repo or composed graph. This is the
+ * shape the durable element store persists (`~/.principal/c4-elements/<purl>.json`):
+ * **accepted elements only** — the set is the approved architecture, not a
+ * history. `proposed` exists only on in-memory proposal scaffolds and is never
+ * persisted; a rejected proposal stays remembered by the proposal store, which
+ * is where proposing agents consult prior rejections.
+ */
 export interface C4ElementSet {
   /** Repo key this set describes, e.g. `pkg:github/owner/name`. */
   repoKey: string;
@@ -142,38 +153,6 @@ export interface C4ElementSet {
 /** Which level to draw. Determines which frames are drawn. */
 export type C4View = 'container' | 'component';
 
-/**
- * A flattened element, as the renderer reads it.
- *
- * The union above is what an author writes; this is the one shape every box
- * draws with, so the card does not branch on kind to find a label.
- */
-export interface C4Node {
-  id: string;
-  kind: C4Element['kind'];
-  /**
-   * Nesting parent: a component's container, a container or external system's
-   * frame, and nothing for a person — C4 puts people outside every system.
-   */
-  parentId?: string;
-  label: string;
-  technology?: string;
-  description?: string;
-  state: C4ElementState;
-  /** `application` / `data-store`. Set on containers only. */
-  containerKind?: C4ContainerKind;
-  /** Provenance, when the element consolidated several derived keys. */
-  derivedFrom?: string[];
-  /** Resolved members, when a document was supplied. A container's list includes its components'. */
-  members: string[];
-  /** Distinct constructs among resolved members. */
-  constructs: string[];
-  /** Present at component level when the document resolved it. */
-  component?: SubsystemComponent;
-  /** Source model ids that contributed members, when attribution is supplied. */
-  models?: string[];
-}
-
 /** A compound frame: the system, or a container holding its components. */
 export interface C4Group {
   id: string;
@@ -205,11 +184,56 @@ export interface C4Edge {
   count: number;
 }
 
+/**
+ * Protocol hues, keyed by a canonical protocol token.
+ *
+ * C4's notation is colour-free, so this is a local choice — but on a container
+ * diagram the protocol is what a reader wants to distinguish at a glance
+ * (in-process RPC vs HTTP vs file I/O), more than the trail verb the line came
+ * from. Keys are lowercase, matched loosely (see `protocolColor`).
+ */
+export const PROTOCOL_COLOR: Record<string, string> = {
+  rpc: '#22c55e', // green — in-process call across a boundary
+  http: '#e8853a', // orange — network request
+  https: '#e8853a',
+  rest: '#e8853a',
+  graphql: '#e061a3', // pink
+  fs: '#0ea5e9', // sky — disk
+  'file i/o': '#0ea5e9',
+  sql: '#a78bfa', // violet — a database
+  sqlite: '#a78bfa',
+  postgres: '#a78bfa',
+  'json-rpc': '#22c55e',
+  ws: '#e3b341', // gold — stream/socket
+  websocket: '#e3b341',
+  mcp: '#4ec9b0', // teal — agent/tool transport
+  stdin: '#9ca3af', // gray — process boundary
+  stdout: '#9ca3af',
+};
+
+/** Fallback hue for an edge whose protocol we have no colour for (or none). */
+export const PROTOCOL_COLOR_FALLBACK = '#9ca3af';
+
+/**
+ * Colour for an edge's protocol. Matches the longest known token contained in
+ * the (lowercased) protocol string, so `Electrobun RPC` finds `rpc` and
+ * `JSON-RPC` finds the `json-rpc` entry before `rpc`.
+ */
+export function protocolColor(protocol: string | undefined): string {
+  if (!protocol) return PROTOCOL_COLOR_FALLBACK;
+  const p = protocol.toLowerCase();
+  let best = '';
+  for (const key of Object.keys(PROTOCOL_COLOR)) {
+    if (key.length > best.length && p.includes(key)) best = key;
+  }
+  return best ? PROTOCOL_COLOR[best]! : PROTOCOL_COLOR_FALLBACK;
+}
+
 /** A drawable C4 projection. Authored, not derived. */
 export interface C4Model {
   view: C4View;
   system: { id: string; label: string; repoKey?: string };
-  nodes: C4Node[];
+  nodes: C4Element[];
   groups: C4Group[];
   edges: C4Edge[];
 }