@principal-ai/subsystems-react 0.51.2 → 0.51.4

package/src/stories/Subsystem/C4Graph/C4Container.stories.tsx

@@ -0,0 +1,212 @@
+import React, { useMemo, useState } from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { C4Graph } from '../../../subsystem/C4Graph';
+import type { C4Edge, C4Model, C4Node } from '../../../subsystem/c4';
+
+const meta = {
+  title: 'Subsystem/C4Graph/C4Container',
+  component: C4Graph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof C4Graph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// A C4 container diagram, hand-built.
+//
+// Nothing here is derived: the boxes are `C4Node`s an author wrote down, and
+// the lines are explicit `C4Edge`s — no trails, no rollup. This is the shape a
+// caller hands to `C4Graph` once a model has been authored.
+//
+// The system frame holds the containers and the external systems (C4 draws a
+// dependency we do not own inside the boundary); the person sits outside it.
+// ---------------------------------------------------------------------------
+
+const SYSTEM = { id: 'system:acme', label: 'Subsystem Modeling', repoKey: 'pkg:github/acme/subsystem-modeling' };
+
+function container(over: Partial<C4Node> & Pick<C4Node, 'id' | 'label'>): C4Node {
+  return {
+    kind: 'container',
+    members: [],
+    constructs: [],
+    state: 'accepted',
+    containerKind: 'application',
+    ...over,
+  };
+}
+
+const NODES: C4Node[] = [
+  container({
+    id: 'container:studio-host',
+    label: 'Subsystem Studio — host',
+    containerKind: 'application',
+    technology: 'Bun + Electrobun',
+    description: 'Owns the model store on disk and serves the renderer over RPC.',
+    parentId: SYSTEM.id,
+  }),
+  container({
+    id: 'container:studio-renderer',
+    label: 'Subsystem Studio — renderer',
+    containerKind: 'application',
+    technology: 'React 19',
+    description: 'Renders subsystem models and talks to the host over RPC.',
+    parentId: SYSTEM.id,
+  }),
+  container({
+    id: 'container:cli',
+    label: 'Subsystem Modeling CLI',
+    containerKind: 'application',
+    technology: 'Node',
+    description: 'Creates and updates models from the terminal.',
+    parentId: SYSTEM.id,
+  }),
+  container({
+    id: 'container:model-store',
+    label: 'Subsystem model store',
+    containerKind: 'data-store',
+    technology: 'JSON on disk',
+    description: 'Every stored model and the correction queue.',
+    parentId: SYSTEM.id,
+  }),
+  // An external system drawn inside the boundary — something we depend on.
+  {
+    kind: 'external-system',
+    id: 'external:opencode',
+    label: 'OpenCode v2 service',
+    technology: 'HTTP',
+    description: 'Runs the maintain agent sessions this model is edited by.',
+    state: 'accepted',
+    members: [],
+    constructs: [],
+    parentId: SYSTEM.id,
+  },
+  // A person sits outside every system boundary.
+  {
+    kind: 'person',
+    id: 'person:maintainer',
+    label: 'Maintain operator',
+    description: 'Reviews and accepts the correction proposals.',
+    state: 'accepted',
+    members: [],
+    constructs: [],
+  },
+];
+
+const EDGES: C4Edge[] = [
+  {
+    id: 'flow:renderer-host',
+    source: 'container:studio-renderer',
+    target: 'container:studio-host',
+    label: 'RPC',
+    protocol: 'Electrobun RPC',
+    mechanisms: ['calls'],
+    count: 1,
+  },
+  {
+    id: 'flow:host-store',
+    source: 'container:studio-host',
+    target: 'container:model-store',
+    label: 'fs · JSON',
+    protocol: 'file I/O',
+    mechanisms: ['reads', 'writes'],
+    count: 2,
+  },
+  {
+    id: 'flow:host-opencode',
+    source: 'container:studio-host',
+    target: 'external:opencode',
+    label: 'HTTPS',
+    protocol: 'HTTP',
+    mechanisms: ['calls'],
+    count: 1,
+  },
+  {
+    id: 'flow:cli-store',
+    source: 'container:cli',
+    target: 'container:model-store',
+    label: 'fs · JSON',
+    protocol: 'file I/O',
+    mechanisms: ['writes'],
+    count: 1,
+  },
+  {
+    id: 'flow:maintainer-renderer',
+    source: 'person:maintainer',
+    target: 'container:studio-renderer',
+    label: 'UI',
+    mechanisms: ['uses'],
+    count: 1,
+  },
+];
+
+/**
+ * The container-view projection of the authored elements. From here on it is a
+ * plain render input: `C4Graph` sizes and lays these out, it does not build any
+ * of them.
+ */
+const containerModel: C4Model = {
+  view: 'container',
+  system: SYSTEM,
+  nodes: NODES,
+  groups: [
+    {
+      id: SYSTEM.id,
+      kind: 'system',
+      label: SYSTEM.label,
+      memberIds: NODES.filter((n) => n.parentId === SYSTEM.id).map((n) => n.id),
+    },
+  ],
+  edges: EDGES,
+};
+
+function Demo() {
+  const [selected, setSelected] = useState<string | null>(null);
+  const model = useMemo(() => containerModel, []);
+
+  const containers = model.nodes.filter((n) => n.kind === 'container').length;
+  const outside = model.nodes.filter(
+    (n) => n.kind === 'external-system' || n.kind === 'person',
+  ).length;
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <C4Graph model={model} title="Subsystem Modeling" onSelectNode={setSelected} />
+      </div>
+      <div
+        style={{
+          padding: '6px 12px',
+          display: 'flex',
+          alignItems: 'center',
+          gap: 18,
+          fontFamily: 'monospace',
+          fontSize: 12,
+          color: '#aaa',
+          borderTop: '1px solid #333',
+        }}
+      >
+        <span>
+          {containers} containers · {outside} outside
+        </span>
+        <span>{model.edges.length} lines</span>
+        <span>selected: {selected ?? '(none)'}</span>
+        <span style={{ color: '#777' }}>boxes and lines are authored, not derived</span>
+      </div>
+    </div>
+  );
+}
+
+export const Containers: Story = {
+  render: () => <Demo />,
+};

package/src/stories/Subsystem/C4Graph/C4NodeGallery.stories.tsx

@@ -6,7 +6,7 @@ import {
   nodeStyle,
   nodeSubtitle,
   nodeTag,
-  nodeTypeLabel,
+  nodeTopLabel,
   nodeShape,
   nodeSize,
   nodeMissing,
@@ -25,7 +25,7 @@ import type { C4Node } from '../../../subsystem/c4';
 // is a plain presentational component, so it can be reviewed and diffed
 // without a layout engine in the way.
 //
-// Every card here is a flattened `C4Node` — exactly what `buildC4Model`
+// Every card here is a flattened `C4Node` — the one shape a C4 box draws with,
 // produces from an authored element, with the per-kind fields already resolved
 // to the one shape the card draws with.
 // ---------------------------------------------------------------------------
@@ -334,7 +334,12 @@ function Gallery() {
 
       <div style={{ fontFamily: 'monospace', fontSize: 11, marginBottom: 26, lineHeight: 1.9 }}>
         <div style={{ display: 'flex', gap: 20, flexWrap: 'wrap' }}>
-          <span style={{ color: '#e8e8ea' }}>KIND — shape, icon, and border weight</span>
+          <span style={{ color: '#e8e8ea' }}>KIND — shape and border weight</span>
+        </div>
+        <div style={{ color: muted, marginTop: 2 }}>
+          Top-left is the technology’s brand mark — shown only when we hold the official SVG — and its
+          name. Top-right is a container’s C4 sort, application vs data-store. The line under the label
+          is the description.
         </div>
         <div style={{ display: 'flex', gap: 18, flexWrap: 'wrap', marginTop: 4 }}>
           {KINDS.map((kind) => {
@@ -385,13 +390,18 @@ function Gallery() {
                 </div>
               )}
               <Case
-                caption={`${v.node.id} · "${nodeTag(v.node)}"${
-                  nodeTypeLabel(v.node) ? ` / ${nodeTypeLabel(v.node)}` : ''
-                } · ${v.node.state} · ${nodeShape(v.node).kind} ${
-                  nodeSize(v.node).width
-                }×${nodeSize(v.node).height} · ${nodeSubtitle(v.node)}${
-                  nodeMissing(v.node).length ? ` · missing ${nodeMissing(v.node).join('+')}` : ''
-                }`}
+                caption={[
+                  v.node.id,
+                  `"${nodeTag(v.node)}"`,
+                  v.node.kind === 'container' ? v.node.containerKind : null,
+                  v.node.state,
+                  `${nodeShape(v.node).kind} ${nodeSize(v.node).width}×${nodeSize(v.node).height}`,
+                  nodeTopLabel(v.node),
+                  nodeSubtitle(v.node),
+                  nodeMissing(v.node).length ? `missing ${nodeMissing(v.node).join('+')}` : null,
+                ]
+                  .filter(Boolean)
+                  .join(' · ')}
               >
                 <C4NodeCard node={v.node} />
               </Case>

package/src/stories/Subsystem/ComponentGraph/IssueOverlay.stories.tsx

@@ -503,8 +503,10 @@ const MAINTAIN_ISSUES: SubsystemIssue[] = [
     target: {
       kind: 'step',
       id: 'wt-wait-finish-event',
-      label: 'Wait for the finish event',
-      detail: 'step 7',
+      // The host labels a step by its call-site symbol — the same row text
+      // the trail UI shows — with the trail title as the detail line.
+      label: 'matchFinishEvent',
+      detail: 'Wait for the finish event',
       stepIndex: 6,
     },
   },

package/src/stories/Subsystem/ComponentGraph/ProposedTrails.stories.tsx

@@ -144,6 +144,26 @@ const trails: SubsystemTrail[] = [
       },
     ],
   },
+  {
+    id: 'wt-planned-seam',
+    title: 'Planned seam (step-proposed)',
+    steps: [
+      {
+        from: 'audit',
+        to: 'cli',
+        mechanism: 'uses',
+        file: 'src/bun/verify-subsystem-component.ts',
+        line: 1,
+        symbol: 'probeCliVersion',
+        // Step-level proposed: BOTH endpoints are real components — the
+        // seam itself is what is planned. The edge label draws dashed on
+        // the canvas; distinct from a proposed endpoint, which dashes the
+        // node instead. Verification skips the step until promoted.
+        proposed: true,
+        annotation: 'The step itself is proposed — edge label is dashed.',
+      },
+    ],
+  },
 ];
 
 function ProposedTrailsDemo() {
@@ -153,7 +173,7 @@ function ProposedTrailsDemo() {
         components={components}
         trails={trails}
         title="proposed-work marker"
-        description="Trails that touch a **proposed** component get their title tinted darkgoldenrod in the flows panel; expand a row and each step onto a proposed component is tinted too (index and title). Nodes for proposed components already draw dashed darkgoldenrod on the canvas."
+        description="Trails that touch a **proposed** component get their title tinted darkgoldenrod in the flows panel; expand a row and each step onto a proposed component is tinted too (index and title). Nodes for proposed components draw dashed darkgoldenrod on the canvas. A step that is itself `proposed` — a planned seam between real components — dashes its **edge label** instead."
       />
     </div>
   );

package/src/subsystem/C4Graph.tsx

@@ -1,7 +1,7 @@
 /**
  * C4Graph — a C4 projection of a (composed) subsystem model on React Flow.
  *
- * Feed it a `C4Model` from `buildC4Model()` and it draws the
+ * Feed it an authored `C4Model` and it draws the
  * system as a compound frame, its containers (or components) as boxes, and
  * externals/actors outside the system. `trail` steps render as flow
  * edges. Click a box to list the source components it rolled up.
@@ -14,6 +14,7 @@
 import { useEffect, useMemo, useState } from 'react';
 import {
   Edge,
+  EdgeProps,
   Handle,
   MarkerType,
   Node,
@@ -22,9 +23,11 @@ import {
   ReactFlow,
   ReactFlowProvider,
   useReactFlow,
+  useViewport,
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { computeElkLayout } from '../utils/elkLayout';
+import { computeElkLayout, pointAlongPath, pointsToSmoothPath } from '../utils/elkLayout';
+import { EDGE_LABEL_FONT_SIZE, EDGE_LABEL_HEIGHT, EDGE_LABEL_WIDTH } from '../utils/edgeLabel';
 import { MECHANISM_COLOR } from './model';
 import { C4NodeCard, NODE_H, NODE_W, nodeSize, nodeStyle } from './C4NodeCard';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
@@ -34,6 +37,17 @@ export interface C4GraphProps {
   model: C4Model;
   title?: string;
   onSelectNode?: (id: string | null) => void;
+  /**
+   * Extra width / height reserved around each card when laying out, in flow px.
+   * The visible gap between boxes is `2 × gutter` (ELK's `nodeNode` spacing,
+   * plus the frame padding where a frame adds one).
+   *
+   * Above the default 28 the `needs …` gap row was removed, so cards are
+   * shorter and packing them tighter than the spacing they were tuned at makes
+   * them collide. Raise it for a more airy graph.
+   * @default 28
+   */
+  gutter?: number;
 }
 
 function edgeColor(mechanism: string | undefined, fallback: string): string {
@@ -57,6 +71,118 @@ function C4NodeView(props: NodeProps<Node<{ node: C4Node; selected: boolean }>>)
   );
 }
 
+/**
+ * Edge-label overlay.
+ *
+ * Drawn as chips in flow space via `<ViewportPortal>` — React Flow applies the
+ * viewport transform, so the label chip needs no manual zoom/pan math and can
+ * never drift from the edges it sits on. Positions are ELK's computed label
+ * anchors (`edgeLabelPositions`), in flow coordinates.
+ */
+function C4EdgeLabels({
+  positions,
+  edges,
+  muted,
+}: {
+  positions: Map<string, { x: number; y: number }>;
+  edges: C4Model['edges'];
+  muted: string;
+}) {
+  const { theme } = useTheme();
+  const viewport = useViewport();
+  const surface = theme.colors.backgroundSecondary ?? theme.colors.background;
+  const byId = useMemo(() => new Map(edges.map((e) => [e.id, e])), [edges]);
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+        zIndex: 5,
+      }}
+    >
+      {[...positions].map(([id, p]) => {
+        const edge = byId.get(id);
+        if (!edge) return null;
+        const color = edgeColor(edge.mechanisms[0], muted);
+        const text = edge.protocol ?? edge.label;
+        return (
+          <div
+            key={id}
+            style={{
+              position: 'absolute',
+              left: p.x * viewport.zoom + viewport.x,
+              top: p.y * viewport.zoom + viewport.y,
+              transform: `translate(-50%, -50%) scale(${viewport.zoom})`,
+              transformOrigin: 'center center',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: EDGE_LABEL_WIDTH,
+              height: EDGE_LABEL_HEIGHT,
+              boxSizing: 'border-box',
+              padding: '7px 8px',
+            }}
+          >
+            <span
+              aria-hidden
+              style={{
+                position: 'absolute',
+                inset: 0,
+                borderRadius: 4,
+                border: `0.5px solid ${color}`,
+                background: surface,
+              }}
+            />
+            <span
+              style={{
+                position: 'relative',
+                maxWidth: '100%',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                fontSize: EDGE_LABEL_FONT_SIZE,
+                lineHeight: 1,
+                fontFamily: theme.fonts.monospace,
+                fontWeight: 500,
+                color,
+              }}
+            >
+              {text}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * C4 edge — draws ELK's routed polyline, not React Flow's default bezier.
+ *
+ * The line and the label chip must share one geometry: the chip is placed from
+ * the same `elkPathPoints` this renders. React Flow's built-in edge would curve
+ * between handles while the chip sat on ELK's orthogonal route, which is why
+ * labels read as "off the line".
+ */
+function C4EdgeView({ data, markerEnd }: EdgeProps<Edge<{ path?: string; color?: string }>>) {
+  const path = data?.path ?? '';
+  if (!path) return null;
+  return (
+    <path
+      d={path}
+      fill="none"
+      stroke={data?.color}
+      strokeWidth={1}
+      strokeDasharray="6 4"
+      markerEnd={markerEnd}
+      style={{ pointerEvents: 'none' }}
+    />
+  );
+}
+
 function C4GroupView(props: NodeProps<Node<{ label: string; kind: 'system' | 'container'; color: string }>>) {
   const { theme } = useTheme();
   const color = props.data.color;
@@ -106,7 +232,11 @@ const nodeTypes = {
   'c4-group': C4GroupView,
 };
 
-function Inner({ model, title, onSelectNode }: C4GraphProps) {
+const edgeTypes = {
+  'c4-edge': C4EdgeView,
+};
+
+function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -114,6 +244,9 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
   const [rfEdges, setRfEdges] = useState<Edge[]>([]);
   const [ready, setReady] = useState(false);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [labelPositions, setLabelPositions] = useState<Map<string, { x: number; y: number }>>(
+    () => new Map(),
+  );
 
   const layoutKey = useMemo(
     () =>
@@ -130,10 +263,11 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     setReady(false);
     setSelectedId(null);
 
-    // Per-node size, so a square component is laid out as a square. Feeding the
-    // container dimensions for everything would make ELK reserve 210x138 of
-    // space around a 132x132 box and space the component view twice as far
-    // apart as it needs.
+    // Per-kind size, so a square component is laid out as a square. Feeding the
+    // container dimensions for everything would make ELK reserve 250x150 of
+    // space around a 140x140 box and space the component view twice as far
+    // apart as it needs. `gutter` is added here, not passed as node spacing, so
+    // a frame's padding clears the card inside it by the same margin.
     const rfNodes: Node[] = model.nodes.map((n, i) => {
       const size = nodeSize(n);
       return {
@@ -142,8 +276,8 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         // Fallback grid pitch uses the container box — the largest, so the
         // pre-layout positions never overlap. ELK replaces them on success.
         position: { x: (i % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
-        width: size.width,
-        height: size.height,
+        width: size.width + gutter,
+        height: size.height + gutter,
         ...(n.parentId ? { parentId: n.parentId } : {}),
         data: { node: n, selected: false },
       };
@@ -160,18 +294,15 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
       const color = edgeColor(e.mechanisms[0], muted);
       return {
         id: e.id,
+        type: 'c4-edge',
         source: e.source,
         target: e.target,
-        label: e.label,
-        labelShowBg: false,
-        labelStyle: { fill: muted, fontSize: theme.fontSizes[0], fontFamily: theme.fonts.monospace },
-        style: {
-          stroke: color,
-          strokeWidth: 1 + Math.min(e.count, 6) * 0.4,
-          strokeDasharray: '6 4',
-        },
+        // The reserved label box and the chip must agree on size, so ELK is
+        // given the same text the chip draws (protocol first, then label). The
+        // chip itself is the C4EdgeLabels overlay, not this field.
+        label: e.protocol ?? e.label,
         markerEnd: { type: MarkerType.ArrowClosed, color, width: 18, height: 18 },
-        data: { edge: e },
+        data: { edge: e, color, path: '' },
       };
     });
 
@@ -180,10 +311,23 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
       preserveNodePositions: false,
       groups,
       keepSingletonGroups: true,
+      edgeLabels: { enabled: true, placement: 'CENTER' },
     })
       .then((result) => {
         if (!alive) return;
         const positioned = new Map(result.nodes.map((n) => [n.id, n]));
+        // Draw each edge along ELK's routed polyline and place its label from
+        // the same points — one geometry for the line and the chip.
+        const labelPositions = new Map<string, { x: number; y: number }>();
+        const withPaths = rfEdges.map((e) => {
+          const pts = result.edgePathPoints?.get(e.id);
+          if (!pts || pts.length === 0) return e;
+          labelPositions.set(e.id, pointAlongPath(pts, 0.5));
+          // Rounded corners on ELK's orthogonal route — gentler than raw right
+          // angles, and still the exact polyline the label is placed on.
+          return { ...e, data: { ...e.data, path: pointsToSmoothPath(pts, 12) } };
+        });
+        setLabelPositions(labelPositions);
         const builtGroups = new Set(result.groupBounds.keys());
         const groupById = new Map(model.groups.map((g) => [g.id, g]));
 
@@ -231,7 +375,7 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         });
 
         setNodes([...shells, ...leaves]);
-        setRfEdges(rfEdges);
+        setRfEdges(withPaths);
         setReady(true);
         requestAnimationFrame(() => fitView({ padding: 0.15 }));
       })
@@ -277,6 +421,7 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         nodes={displayNodes}
         edges={rfEdges}
         nodeTypes={nodeTypes}
+        edgeTypes={edgeTypes}
         className={GRAPH_CANVAS_CLASS}
         {...GRAPH_NAV_PROPS}
         onNodeClick={(_e, node) => {
@@ -290,9 +435,16 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
           onSelectNode?.(null);
         }}
         proOptions={{ hideAttribution: true }}
+        // Pin the flow to its container. The label overlay is a sibling sized
+        // `inset: 0`, so the two must share an origin or `viewport.y` (measured
+        // in the flow's own box) lands the chips off vertically.
+        style={{ width: '100%', height: '100%' }}
       >
         <GraphChrome />
       </ReactFlow>
+      {ready && labelPositions.size > 0 && (
+        <C4EdgeLabels positions={labelPositions} edges={model.edges} muted={muted} />
+      )}
       {!ready && (
         <div
           style={{