@principal-ai/subsystems-react 0.51.3 → 0.52.0

package/src/subsystem/C4NodeCard.test.ts

@@ -12,7 +12,7 @@ import {
   nodeSize,
   COMPONENT_SIZE,
 } from './C4NodeCard';
-import type { C4Node } from './c4';
+import type { C4Element, C4Container } from './c4';
 
 const theme = {
   colors: {
@@ -25,12 +25,20 @@ const theme = {
 } as Parameters<typeof nodeStyle>[1];
 
 /**
- * A drawn node, flat. `state` is required on a real `C4Node` — every authored
- * element carries a decision — so the card never has to cope with a box nobody
- * proposed, and no test pretends otherwise.
+ * A container element with overridable fields. `state` is required — every
+ * authored element carries a decision — so the card never has to cope with a
+ * box nobody proposed, and no test pretends otherwise.
  */
-function node(over: Partial<C4Node> = {}): C4Node {
-  return { id: 'n', kind: 'container', label: 'n', members: [], constructs: [], state: 'proposed', ...over };
+function node(over: Partial<C4Container> = {}): C4Element {
+  return {
+    id: 'n',
+    kind: 'container',
+    label: 'n',
+    containerKind: 'application',
+    technology: '',
+    state: 'proposed',
+    ...over,
+  };
 }
 
 describe('nodeStyle — one axis per channel', () => {
@@ -39,16 +47,12 @@ describe('nodeStyle — one axis per channel', () => {
     expect(nodeStyle(node({ state: 'accepted' }), theme, true).dash).toBe('solid');
   });
 
-  test('accepted is solid and uses the primary colour', () => {
-    const s = nodeStyle(node({ state: 'accepted' }), theme);
-    expect(s.dash).toBe('solid');
-    expect(s.color).toBe('#4ec9b0');
+  test('accepted is solid', () => {
+    expect(nodeStyle(node({ state: 'accepted' }), theme).dash).toBe('solid');
   });
 
-  test('proposed is dashed and uses the warning colour', () => {
-    const s = nodeStyle(node({ state: 'proposed' }), theme);
-    expect(s.dash).toBe('dashed');
-    expect(s.color).toBe('#e8a33a');
+  test('proposed is dashed', () => {
+    expect(nodeStyle(node({ state: 'proposed' }), theme).dash).toBe('dashed');
   });
 
   test('rejected is dotted and muted', () => {
@@ -67,12 +71,18 @@ describe('nodeStyle — one axis per channel', () => {
     }
   });
 
-  test('confirmation state wins over kind for colour', () => {
-    // Same state, four kinds: one colour. Kind is shape's job.
-    const colors = (['container', 'component', 'external-system', 'person'] as const).map(
-      (kind) => nodeStyle(node({ kind, state: 'accepted' }), theme).color,
-    );
-    expect(new Set(colors).size).toBe(1);
+  test('colour follows the technology, not the state', () => {
+    // Same kind and state, different tech: different hue.
+    const react = nodeStyle(node({ technology: 'React 19', state: 'accepted' }), theme).color;
+    const bun = nodeStyle(node({ technology: 'Bun', state: 'accepted' }), theme).color;
+    expect(react).not.toBe(bun);
+    // State does not move the colour.
+    expect(nodeStyle(node({ technology: 'React 19', state: 'proposed' }), theme).color).toBe(react);
+  });
+
+  test('an unknown technology falls back to the muted border', () => {
+    expect(nodeStyle(node({ technology: '', state: 'accepted' }), theme).color).toBe('#555');
+    expect(nodeStyle(node({ technology: 'COBOL', state: 'accepted' }), theme).color).toBe('#555');
   });
 
   test('border weight carries the level, not the state', () => {
@@ -165,10 +175,10 @@ describe('nodeShape — kind without relying on colour or dash', () => {
     expect(nodeShape(node({ kind: 'component' })).kind).toBe('square');
   });
 
-  test('an external system is a rounded rectangle', () => {
+  test('an external system has no corner radius', () => {
     const s = nodeShape(node({ kind: 'external-system' }));
     expect(s.kind).toBe('rect');
-    expect(s.radius).toBeGreaterThan(nodeShape(node()).radius);
+    expect(s.radius).toBe(0);
   });
 
   test('a person is a pill', () => {

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:
@@ -1211,6 +1226,22 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     return map;
   }, [issues, trails, issueStep]);
 
+  // Edges backed by a step that ITSELF declares `proposed` — a planned seam
+  // between otherwise-real components. Distinct from a proposed ENDPOINT
+  // (the node is the placeholder there, and draws its own dashed border):
+  // here the seam is the claim that is not real yet, so the edge label draws
+  // dashed. Proposed steps are never verified, so this never competes with
+  // the step-issue badge.
+  const proposedEdgeIds = useMemo(() => {
+    const set = new Set<string>();
+    for (const trail of trails ?? []) {
+      for (const step of trail.steps) {
+        if (step.proposed) set.add(trailStepGraphEdgeId(step));
+      }
+    }
+    return set;
+  }, [trails]);
+
   // Expanded verification layers in the diagnostics list. When any layer with
   // findings is expanded, the canvas dims everything that layer does not
   // implicate (see `issueFocus`). The list publishes this through
@@ -1251,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
@@ -1282,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,
@@ -1472,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,
@@ -1530,6 +1568,17 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     () => convertedEdges.map((e) => e.id).sort().join(','),
     [convertedEdges],
   );
+  // Stamp `proposedStep` onto edge data so the SVG edge itself (not just its
+  // label) draws dashed when a backing trail step declares itself proposed.
+  const proposedStampedEdges = useMemo(
+    () =>
+      baseEdges.map((e) =>
+        proposedEdgeIds.has(e.id)
+          ? { ...e, data: { ...(e.data as object), proposedStep: true } }
+          : e,
+      ),
+    [baseEdges, proposedEdgeIds],
+  );
 
   const dispEdges = useMemo(() => {
     const paint = (e: Edge, dimmed: boolean): Edge => {
@@ -1558,7 +1607,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
       return isTrailMechanism(mechanism);
     };
     if (openedEdgeIds || focusEdgeIds || previewEdgeIds || issueFocusEdgeIds) {
-      return baseEdges.map((e) => {
+      return proposedStampedEdges.map((e) => {
         const vis = flowElementVisibility({
           inOpened: openedEdgeIds?.has(e.id) === true,
           inSelected: focusEdgeIds?.has(e.id) === true,
@@ -1572,13 +1621,13 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
       });
     }
     if (selectedEdgeId) {
-      return baseEdges.map((e) => ({
+      return proposedStampedEdges.map((e) => ({
         ...paint(e, e.id !== selectedEdgeId),
         hidden: !edgeInView(e),
       }));
     }
-    return baseEdges.map((e) => ({ ...e, hidden: !edgeInView(e) }));
-  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds, issueFocusEdgeIds, resolvedEdgeView]);
+    return proposedStampedEdges.map((e) => ({ ...e, hidden: !edgeInView(e) }));
+  }, [proposedStampedEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds, issueFocusEdgeIds, resolvedEdgeView]);
 
   const onNodesChange = useCallback(
     (changes: NodeChange[]) => {
@@ -2349,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);
@@ -2367,7 +2416,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     [
       issueComponent,
       issueStep,
-      issueModuleNodeId,
+      issueFrameNodeId,
       focusTrailStep,
       onSelect,
       onSelectIssue,
@@ -2391,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,
@@ -2418,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
@@ -2495,6 +2544,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
           pathLength?: number;
         } | undefined;
         const stepIssue = stepIssueBadgeByEdgeId.get(e.id);
+        const proposed = proposedEdgeIds.has(e.id);
         return {
           id: e.id,
           mechanism: d?.mechanism ?? 'uses',
@@ -2505,10 +2555,11 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
           pathLength: d?.pathLength ?? 0,
           stepNos: selectedFlowStepNos?.get(e.id),
           stepIssue,
+          proposed,
         };
       });
     return labels;
-  }, [dispEdges, selectedFlowStepNos, stepIssueBadgeByEdgeId]);
+  }, [dispEdges, selectedFlowStepNos, stepIssueBadgeByEdgeId, proposedEdgeIds]);
 
   // Unique source files across components → sidebar file trees.
   const treeFilePaths = treeFiles;
@@ -2935,7 +2986,9 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
                   crisp rounded box; soft / ambiguous ones (uses, feeds,
                   watches …) get a real lobed cloud silhouette — ambiguous, not
                   a dashed proposal (or a pill, which border-radius can only
-                  ever make). */}
+                  ever make). A step that ITSELF declares `proposed` dashes the
+                  silhouette — the seam is planned, distinct from a proposed
+                  ENDPOINT, which dashes the node instead. */}
               {verifiable ? (
                 <span
                   aria-hidden
@@ -2943,7 +2996,9 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
                     position: 'absolute',
                     inset: 0,
                     borderRadius: 4,
-                    border: `0.5px solid ${color}`,
+                    border: lbl.proposed
+                      ? `1.5px dashed ${color}`
+                      : `0.5px solid ${color}`,
                     background:
                       theme.colors.backgroundSecondary ?? theme.colors.background,
                     pointerEvents: 'none',
@@ -2968,6 +3023,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
                     stroke={hexWithAlpha(color, 0.75)}
                     strokeWidth={1.2}
                     strokeLinejoin="round"
+                    strokeDasharray={lbl.proposed ? '4 3' : undefined}
                   />
                 </svg>
               )}

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