@principal-ai/subsystems-react 0.51.1 → 0.51.3

package/src/subsystem/C4NodeCard.tsx

@@ -7,22 +7,24 @@
  *
  * The encoding has one job: make confirmation state legible at a glance. A box
  * nobody has looked at must not read the same as a box a person signed off.
- * Kind says what the box is — shape, size, and a written tag — and everything
- * else in C4 notation (technology, description) is surfaced in the order a
- * reader wants it.
+ * Kind is carried by shape and size — plus an icon for a container's sort,
+ * application vs data-store — and C4 notation is surfaced in the order a reader
+ * wants it: technology on the top row, description under the label.
  */
 
 import { useTheme } from '@principal-ade/industry-theme';
-import { describeConstructBreakdown } from './model';
+import { AppWindow, Database } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+import { TechMark, technologyBrand } from './techIcons';
 import type { C4Node } from './c4';
 
 /**
  * Card box for a container: a wide rectangle. A container carries four things
- * at once (tag, label, type + technology, and the notation gap it still has),
- * and a strip would force the last two to truncate.
+ * at once (technology row, label, description, and the notation gap it still
+ * has), and a strip would force the last two to wrap hard.
  */
-export const NODE_W = 210;
-export const NODE_H = 138;
+export const NODE_W = 250;
+export const NODE_H = 150;
 
 /**
  * A component is a proper square — equal sides, and visibly smaller than the
@@ -30,7 +32,7 @@ export const NODE_H = 138;
  * these are different C4 levels, and it survives grayscale and colour-blind
  * reading where a border-weight difference alone does not.
  */
-export const COMPONENT_SIZE = 132;
+export const COMPONENT_SIZE = 140;
 
 /**
  * Per-level box size. The graph lays out against these, so a square component
@@ -43,12 +45,10 @@ export function nodeSize(node: C4Node): { width: number; height: number } {
 }
 
 /**
- * Fixed slot heights, so rows line up across every card regardless of which
- * optional fields are present. Without these a card missing its notation-gap
- * marker is two lines shorter and a row of cards reads as ragged.
+ * Fixed label slot, so the description below sits at the same y on every card
+ * even when a label is one line rather than two.
  */
 const LABEL_SLOT_H = 40;
-const GAP_SLOT_H = 18;
 
 type Theme = ReturnType<typeof useTheme>['theme'];
 
@@ -89,32 +89,18 @@ export function nodeStyle(node: C4Node, theme: Theme, selected = false): NodeSty
       // Dashed — an agent asked; a human has not answered.
       return { color: theme.colors.warning ?? '#e8a33a', dash: 'dashed', width: weight };
     case 'rejected':
-      // Should never be drawn (buildC4Model drops it); belt-and-braces.
+      // Should never be drawn (a rejected element is not projected); belt-and-braces.
       return { color: muted, dash: 'dotted', width: 1 };
   }
 }
 
-function baseName(path: string): string {
-  const parts = path.split('/').filter(Boolean);
-  return parts[parts.length - 1] ?? path;
-}
-
 /**
- * The kind + technology line under the label.
- *
- * A container shows its `containerKind` (application / data-store / queue);
- * C4 has no kind for the other three, so they show technology or nothing.
+ * The line under the label: the element's one-line responsibility, which C4
+ * 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 {
-  const parts = [node.containerKind, node.technology].filter(Boolean);
-  if (parts.length > 0) return parts.join(' · ');
-
-  // No confirmed attributes: fall back to what the document told us.
-  if (node.kind === 'component') {
-    return `${node.component?.construct ?? 'code'}${node.component?.file ? ` · ${baseName(node.component.file)}` : ''}`;
-  }
-  const count = node.members.length;
-  return `${describeConstructBreakdown(node.constructs)}${count > 0 ? ` · ${count} component${count === 1 ? '' : 's'}` : ''}`;
+  return node.description ?? '';
 }
 
 /**
@@ -127,6 +113,29 @@ export function nodeTag(node: C4Node): string {
   return node.kind;
 }
 
+/**
+ * The icon on the top row: a container's sort, **application vs data-store**.
+ *
+ * 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.
+ */
+export function nodeKindIcon(node: C4Node): LucideIcon | undefined {
+  if (node.kind !== 'container') return undefined;
+  return node.containerKind === 'data-store' ? Database : AppWindow;
+}
+
+/**
+ * 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.
+ */
+export function nodeTopLabel(node: C4Node): string {
+  if (node.technology) return node.technology;
+  return node.kind === 'container' ? (node.containerKind ?? 'container') : node.kind;
+}
+
 /** How a box is drawn. Shape carries the C4 kind, independent of colour. */
 export type C4ShapeKind = 'rect' | 'square' | 'pill';
 
@@ -150,8 +159,8 @@ export interface NodeShape {
  * 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 tag says it in words, and
- * the frame position says it structurally.
+ * already spent on proposed-vs-accepted. The kind icon says it, and the frame
+ * position says it structurally.
  */
 export function nodeShape(node: C4Node): NodeShape {
   switch (node.kind) {
@@ -196,9 +205,15 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const style = nodeStyle(node, theme, selected);
   const shape = nodeShape(node);
-  const missing = nodeMissing(node);
+  const Icon = nodeKindIcon(node);
+  const brand = technologyBrand(node.technology);
+  const topLabel = nodeTopLabel(node);
+  const subtitle = nodeSubtitle(node);
 
   const size = nodeSize(node);
+  // A pill (a person) has no straight left edge, so left-aligned text reads as
+  // spilling out of the oval. Centre the text and inset it from the curve.
+  const centered = shape.kind === 'pill';
 
   return (
     <div
@@ -214,7 +229,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
         // height on every card. In a graph grid that makes the row unscannable.
         justifyContent: 'flex-start',
         gap: 3,
-        padding: '10px 12px',
+        padding: centered ? '10px 30px' : '10px 12px',
         borderRadius: shape.radius,
         background: theme.colors.backgroundSecondary ?? theme.colors.background,
         border: `${style.width} ${style.dash} ${style.color}`,
@@ -223,23 +238,47 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
         fontFamily: theme.fonts.body,
       }}
     >
-      {/* The kind is what the box IS. Confirmation state is carried by the
-          border (see `nodeStyle`), not by a word: the card says what it is,
-          and the styling says who vouched for it. */}
+      {/* 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`). */}
       <span
         style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: centered ? 'center' : 'space-between',
+          gap: 6,
           fontFamily: theme.fonts.monospace,
           fontSize: theme.fontSizes[0],
-          color: style.color,
-          fontWeight: 600,
+          color: muted,
           letterSpacing: 0.5,
           textTransform: 'uppercase',
-          whiteSpace: 'nowrap',
-          overflow: 'hidden',
-          textOverflow: 'ellipsis',
+          minWidth: 0,
         }}
       >
-        {nodeTag(node)}
+        <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>
+        {Icon && (
+          <span
+            title={node.containerKind ?? node.kind}
+            aria-label={node.containerKind ?? node.kind}
+            style={{ display: 'inline-flex', flexShrink: 0, color: style.color }}
+          >
+            <Icon size={13} 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
@@ -256,43 +295,25 @@ export function C4NodeCard({ node, selected = false, handles, onClick }: C4NodeC
           WebkitLineClamp: 2,
           WebkitBoxOrient: 'vertical',
           overflow: 'hidden',
+          textAlign: centered ? 'center' : 'left',
         }}
         title={node.label}
       >
         {node.label}
       </span>
-      <span
-        style={{
-          fontFamily: theme.fonts.monospace,
-          fontSize: theme.fontSizes[0],
-          color: muted,
-          whiteSpace: 'nowrap',
-          overflow: 'hidden',
-          textOverflow: 'ellipsis',
-        }}
-        title={node.description ?? node.members.join(', ')}
-      >
-        {nodeSubtitle(node)}
-      </span>
-      {/* Reserved row: without it, a card with no notation gap is two lines
-          shorter and the row of cards reads as ragged. */}
-      <span style={{ height: GAP_SLOT_H }} aria-hidden="true" />
-      {missing.length > 0 && (
+      {subtitle && (
         <span
-          title={`C4 requires a ${missing.join(' and a ')} on every container`}
           style={{
             fontFamily: theme.fonts.monospace,
             fontSize: theme.fontSizes[0],
-            color: theme.colors.warning ?? '#e8a33a',
-            lineHeight: 1.3,
-            height: GAP_SLOT_H,
-            display: '-webkit-box',
-            WebkitLineClamp: 2,
-            WebkitBoxOrient: 'vertical',
-            overflow: 'hidden',
+            color: muted,
+            lineHeight: 1.35,
+            whiteSpace: 'normal',
+            overflowWrap: 'anywhere',
+            textAlign: centered ? 'center' : 'left',
           }}
         >
-          needs {missing.join(' + ')}
+          {subtitle}
         </span>
       )}
       {handles}

package/src/subsystem/IssueList.tsx

@@ -17,10 +17,12 @@ import {
   ChevronDown,
   ChevronRight,
   CircleCheck,
+  CircleHelp,
   Component,
   FileX,
   FolderGit2,
   Footprints,
+  History,
   MapPin,
   Network,
   Route,
@@ -104,6 +106,8 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   boundary_module_file_mismatch: 'static-topology',
   boundary_process_nest_disagree: 'dynamic-topology',
   trail: 'trail',
+  step_unconfirmed: 'trail',
+  step_stale: 'trail',
 };
 
 /**
@@ -164,6 +168,9 @@ 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,
+  // Trail step verification: unconfirmed = no augmentation yet, stale = code changed
+  step_unconfirmed: CircleHelp,
+  step_stale: History,
 };
 
 /**
@@ -244,6 +251,8 @@ const KIND_LABEL: Record<string, string> = {
   boundary_module_file_mismatch: 'Declaration file outside module',
   boundary_process_nest_disagree: 'Module spans multiple process contexts',
   trail: 'Step issue',
+  step_unconfirmed: 'Call site not verified',
+  step_stale: 'Call site changed',
 };
 
 /** Label for an issue's kind. Explicit `kindLabel` wins; unknown kinds humanize. */
@@ -275,8 +284,10 @@ const KIND_ORDER: Record<string, number> = {
   boundary_module_file_mismatch: 23,
   // Runtime topology — process containment
   boundary_process_nest_disagree: 30,
-  // Trail
+  // Trail — mechanical issues first, then step verification
   trail: 40,
+  step_unconfirmed: 41,
+  step_stale: 42,
 };
 
 const KIND_ORDER_FALLBACK = 100;

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -1184,6 +1184,33 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
     return map;
   }, [issues]);
 
+  // Per-edge step verification badge: maps edge IDs to step verification status.
+  // Keyed by the React Flow edge id (from → mechanism → to). An edge can have
+  // multiple steps with issues; we show the worst status (stale > unconfirmed).
+  const stepIssueBadgeByEdgeId = useMemo(() => {
+    const map = new Map<string, { kind: 'step_unconfirmed' | 'step_stale'; severity: 'info' | 'error'; count: number }>();
+    if (!issues?.length || !trails?.length) {
+      return map;
+    }
+    for (const issue of issues) {
+      if (issue.kind !== 'step_unconfirmed' && issue.kind !== 'step_stale') continue;
+      const stepInfo = issueStep(issue);
+      if (!stepInfo) continue;
+      const step = stepInfo.trail.steps[stepInfo.stepIndex];
+      if (!step) continue;
+      const edgeId = trailStepGraphEdgeId(step);
+      const prev = map.get(edgeId);
+      // step_stale is worse than step_unconfirmed
+      const isWorse = issue.kind === 'step_stale' && prev?.kind !== 'step_stale';
+      map.set(edgeId, {
+        kind: isWorse || !prev ? issue.kind as 'step_unconfirmed' | 'step_stale' : prev.kind,
+        severity: prev?.severity === 'error' || issue.severity === 'error' ? 'error' : 'info',
+        count: (prev?.count ?? 0) + 1,
+      });
+    }
+    return map;
+  }, [issues, trails, issueStep]);
+
   // 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
@@ -2452,7 +2479,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
   // doesn't intercept pointer events). Uses ELK-computed label midpoints from
   // the actual edge path (not node-center approximations).
   const edgeLabels = useMemo(() => {
-    return dispEdges
+    const labels = dispEdges
       .filter((e) => {
         if (e.hidden) return false;
         const d = e?.data as { dimmed?: boolean } | undefined;
@@ -2467,6 +2494,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
           labelY?: number;
           pathLength?: number;
         } | undefined;
+        const stepIssue = stepIssueBadgeByEdgeId.get(e.id);
         return {
           id: e.id,
           mechanism: d?.mechanism ?? 'uses',
@@ -2476,9 +2504,11 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
           midY: d?.labelY ?? 0,
           pathLength: d?.pathLength ?? 0,
           stepNos: selectedFlowStepNos?.get(e.id),
+          stepIssue,
         };
       });
-  }, [dispEdges, selectedFlowStepNos]);
+    return labels;
+  }, [dispEdges, selectedFlowStepNos, stepIssueBadgeByEdgeId]);
 
   // Unique source files across components → sidebar file trees.
   const treeFilePaths = treeFiles;
@@ -2958,6 +2988,53 @@ function Inner({ components, trails, graphifyRelations, orderByLine, initialTrai
               >
                 {text}
               </span>
+              {lbl.stepIssue && (() => {
+                const StepIssueIcon = ISSUE_KIND_ICON[lbl.stepIssue.kind];
+                // Match IssueList: error severity = red, info severity = amber
+                const issueColor = lbl.stepIssue.severity === 'error'
+                  ? (theme.colors.error ?? '#e5534b')
+                  : (theme.colors.warning ?? '#d4a017');
+                const badgeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
+                return (
+                  <span
+                    aria-hidden
+                    title={lbl.stepIssue.kind === 'step_stale'
+                      ? 'Call site changed since verification'
+                      : 'Call site not yet verified'}
+                    style={{
+                      position: 'absolute',
+                      right: -7,
+                      bottom: -6,
+                      zIndex: 2,
+                      display: 'inline-flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      gap: 3,
+                      minWidth: 18,
+                      padding: '2px 4px',
+                      borderRadius: 4,
+                      border: `1.5px solid ${issueColor}`,
+                      background: badgeBg,
+                      pointerEvents: 'none',
+                    }}
+                  >
+                    {StepIssueIcon && (
+                      <StepIssueIcon size={12} color={issueColor} />
+                    )}
+                    {lbl.stepIssue.count > 1 && (
+                      <span style={{
+                        color: issueColor,
+                        fontFamily: theme.fonts.monospace,
+                        fontSize: 10,
+                        fontWeight: 700,
+                        lineHeight: 1,
+                      }}>
+                        {lbl.stepIssue.count}
+                      </span>
+                    )}
+                  </span>
+                );
+              })()}
             </div>
           );
         })}

package/src/subsystem/TrailsPanel.tsx

@@ -20,6 +20,7 @@ import {
   reorderTrails,
   trailStepGraphEdgeId,
   type SubsystemTrail,
+  type SubsystemTrailStep,
 } from './model';
 import { buildStepBrief } from './trailBrief';
 
@@ -90,10 +91,14 @@ function TrailFlow({
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const hoverBg = theme.colors.background;
   const wholeFlowActive = active !== null && active.stepIndex === null;
-  // A step is "proposed" when either endpoint is a proposed component.
-  const stepProposed = (from: string, to: string) =>
-    proposedAliases != null && (proposedAliases.has(from) || proposedAliases.has(to));
-  const touchesProposed = trail.steps.some((s) => stepProposed(s.from, s.to));
+  // A step is "proposed" when it says so itself OR either endpoint component
+  // is proposed — the step flag covers planned seams whose endpoints already
+  // exist as real components.
+  const stepProposed = (step: SubsystemTrailStep) =>
+    step.proposed === true ||
+    (proposedAliases != null &&
+      (proposedAliases.has(step.from) || proposedAliases.has(step.to)));
+  const touchesProposed = trail.steps.some((s) => stepProposed(s));
   const [headerHover, setHeaderHover] = useState(false);
   const [collapseHover, setCollapseHover] = useState(false);
   const [playHover, setPlayHover] = useState(false);
@@ -366,7 +371,7 @@ function TrailFlow({
         >
           {trail.steps.map((step, i) => {
             const stepActive = active !== null && active.stepIndex === i;
-            const proposed = stepProposed(step.from, step.to);
+            const proposed = stepProposed(step);
             const revealed =
               stepActive || hoveredStep === i || focusedStep === i || copiedStep === i;
             const copied = copiedStep === i;