@principal-ai/principal-view-react 0.16.58 → 0.16.60

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -2,10 +2,10 @@
  * SubsystemComponentGraph — a clickable, read-only React Flow component graph
  * for a subsystem snapshot.
  *
- * Nodes are positioned with ELK auto-layout (layered, minimized crossings) and
- * colored by package. Only cross-package edges leave a package region. Clicking
- * a component invokes `onSelect`. (Package frames are deferred — nodes are
- * color-coded by package for now.)
+ * Nodes are positioned with ELK auto-layout (layered, minimized crossings,
+ * process-aware compound groups). Components sharing a `process` render
+ * inside one labeled boundary frame; nodes without one sit outside every
+ * boundary. Clicking a component invokes `onSelect`.
  *
  * This is a focused fork of the package's `GraphRenderer` pipeline (same ELK
  * edge routing, delayed fitView, Background/Controls/MiniMap, node/edge type
@@ -44,7 +44,7 @@ import {
   type SubsystemThroughline,
 } from './model';
 import type { SubsystemOpenFileOptions } from './declarationRef';
-import { SubsystemComponentNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
+import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDeclaration } from './ComponentDeclaration';
@@ -53,6 +53,12 @@ import { FileDrawer } from './FileDrawer';
 import { EdgeLegendModal, MECHANISM_DESCRIPTIONS } from './EdgeLegendModal';
 import { buildRepoGroups, repoAvatarUrl, type RepoGroup } from './paths';
 
+/** Cap screen-space edge labels to this fraction of the edge's on-screen length. */
+const EDGE_LABEL_MAX_EDGE_FRACTION = 0.55;
+/** Rough monospace width at fontSize 10 + horizontal padding/border. */
+const EDGE_LABEL_CHAR_PX = 6.2;
+const EDGE_LABEL_PAD_PX = 18;
+
 export interface SubsystemComponentGraphProps {
   components: SubsystemComponent[];
   edges: SubsystemComponentEdge[];
@@ -73,8 +79,22 @@ export interface SubsystemComponentGraphProps {
   maxNodeWidth?: number;
   /** Show edge labels (mechanism names) on the graph. @default true */
   showEdgeLabels?: boolean;
+  /** Show the mechanism-legend button overlay on the canvas. @default true */
+  showLegend?: boolean;
   /** Subsystem title displayed in the sidebar. */
   title?: string;
+  /**
+   * Suppresses the sidebar entirely (title, description, file tree,
+   * throughlines) for graph-only embeds. Pair with `graphTitle` to keep the
+   * subsystem name visible as an overlay on the canvas.
+   */
+  hideSidebar?: boolean;
+  /**
+   * Subsystem title rendered as a non-interactive overlay chip on the graph
+   * canvas (top-center). Does not trigger the sidebar — for graph-only
+   * embeds that still need to name what they show.
+   */
+  graphTitle?: string;
   /** Markdown description rendered in the sidebar. */
   description?: string;
   /** Rendered over the graph canvas only (not the title/legend sidebar). */
@@ -109,6 +129,7 @@ export interface SubsystemComponentGraphProps {
 
 const nodeTypes: NodeTypes = {
   'subsystem-component': SubsystemComponentNode,
+  'subsystem-group': SubsystemGroupNode,
 };
 
 const edgeTypes: EdgeTypes = {
@@ -136,7 +157,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showLegend, title, hideSidebar, graphTitle, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -224,22 +245,25 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   const measuredDimsRef = useRef(new Map<string, { width: number; height: number }>());
   const pendingMeasuredRef = useRef(false);
 
-  // Pass 2: once every node has a measured dimension, re-run ELK.
+  // Pass 2: once every leaf node has a measured dimension, re-run ELK.
+  // Group parents are sized by ELK, not measured — exclude them or pass 2
+  // would wait forever for dimensions that never arrive.
   const prevMeasuredSigRef = useRef('');
   const pass2DoneRef = useRef(false);
   const triggerPass2 = useCallback(() => {
     if (pass2DoneRef.current) return;
     const dims = measuredDimsRef.current;
-    if (dims.size < built.nodes.length) return;
-    const sig = built.nodes.map((n) => `${n.id}:${dims.get(n.id)?.width ?? '?'}`).join(',');
+    const leafNodes = built.nodes.filter((n) => n.type !== 'subsystem-group');
+    if (dims.size < leafNodes.length) return;
+    const sig = leafNodes.map((n) => `${n.id}:${dims.get(n.id)?.width ?? '?'}`).join(',');
     if (sig.includes('?:')) return;
     if (sig === prevMeasuredSigRef.current) return;
     prevMeasuredSigRef.current = sig;
     pendingMeasuredRef.current = false;
     pass2DoneRef.current = true;
 
-    const measuredWidths = new Map(built.nodes.map((n) => [n.id, dims.get(n.id)!.width]));
-    const measuredHeights = new Map(built.nodes.map((n) => [n.id, dims.get(n.id)!.height]));
+    const measuredWidths = new Map(leafNodes.map((n) => [n.id, dims.get(n.id)!.width]));
+    const measuredHeights = new Map(leafNodes.map((n) => [n.id, dims.get(n.id)!.height]));
     let alive = true;
     void buildSubsystemGraph(
       { components, edges },
@@ -397,6 +421,26 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   // React Flow's own selection state from updating.
   const dispNodes = useMemo(() => {
     return xyflowNodesBase.map((n) => {
+      // Boundary frames follow their members: hidden when no member is
+      // visible, dimmed when members are dimmed. Never selectable.
+      if (n.type === 'subsystem-group') {
+        const memberIds = ((n.data as { region?: { memberIds?: string[] } } | undefined)?.region?.memberIds) ?? [];
+        const vis = flowElementVisibility({
+          inOpened: memberIds.some((id) => openedNodeIds?.has(id) === true),
+          inSelected: memberIds.some((id) => brightNodeIds?.has(id) === true),
+          anyOpened: openedNodeIds != null,
+          anySelected: brightNodeIds != null,
+        });
+        return {
+          ...n,
+          hidden: vis.hidden,
+          selectable: false,
+          data: {
+            ...(n.data as object),
+            ...(vis.dimmed && { dimmed: true }),
+          },
+        };
+      }
       const comp = (n.data as { component?: SubsystemComponent } | undefined)?.component;
       const fileMatch = fileMatchForNode(comp?.file, openFile, focusNodeIds?.has(n.id) === true);
       const isSelected = selected?.id !== undefined && comp?.id === selected.id;
@@ -460,8 +504,12 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   const onNodesChange = useCallback(
     (changes: NodeChange[]) => {
       // Capture dimension changes (React Flow's measurement callback).
+      // Group parents are ELK-sized — ignore their measurements.
+      const groupIds = new Set(
+        dispNodes.filter((n) => n.type === 'subsystem-group').map((n) => n.id),
+      );
       for (const ch of changes) {
-        if (ch.type === 'dimensions' && ch.dimensions) {
+        if (ch.type === 'dimensions' && ch.dimensions && !groupIds.has(ch.id)) {
           measuredDimsRef.current.set(ch.id, ch.dimensions);
           pendingMeasuredRef.current = true;
         }
@@ -677,13 +725,20 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     return dispEdges
       .filter((e) => !e.hidden)
       .map((e) => {
-        const d = e.data as { mechanism?: string; dimmed?: boolean; labelX?: number; labelY?: number } | undefined;
+        const d = e.data as {
+          mechanism?: string;
+          dimmed?: boolean;
+          labelX?: number;
+          labelY?: number;
+          pathLength?: number;
+        } | undefined;
         return {
           id: e.id,
           mechanism: d?.mechanism ?? 'imports',
           dimmed: d?.dimmed === true,
           midX: d?.labelX ?? 0,
           midY: d?.labelY ?? 0,
+          pathLength: d?.pathLength ?? 0,
           stepNos: selectedFlowStepNos?.get(e.id),
         };
       });
@@ -729,7 +784,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   return (
     <div style={{ width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }}>
       {/* Sidebar: scrollable title/description on top, files or flows pinned to the bottom half */}
-      {(title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (
+      {!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (
         <div
           style={{
             width: 340,
@@ -923,6 +978,17 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
             const verifiable = MECHANISM_DESCRIPTIONS.find(([m]) => m === mechanism)?.[2] ?? true;
             const screenX = lbl.midX * viewport.zoom + viewport.x;
             const screenY = lbl.midY * viewport.zoom + viewport.y;
+            const text = lbl.stepNos?.length
+              ? `${lbl.stepNos.map((n) => `${n}:`).join(' ')} ${lbl.mechanism}`
+              : lbl.mechanism;
+            // Labels stay readable at full size until they'd exceed a share of
+            // the edge's screen length, then shrink with zoom.
+            const estWidth = text.length * EDGE_LABEL_CHAR_PX + EDGE_LABEL_PAD_PX;
+            const screenEdgeLen = lbl.pathLength * viewport.zoom;
+            const scale =
+              lbl.pathLength > 0 && estWidth > 0
+                ? Math.min(1, (screenEdgeLen * EDGE_LABEL_MAX_EDGE_FRACTION) / estWidth)
+                : 1;
             return (
               <div
                 key={lbl.id}
@@ -939,22 +1005,26 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
                 // Center on the flow-space midpoint. Labels live in screen
                 // space (fixed size when zoomed out), so top-left anchoring
                 // would drift them right/down of the edge as zoom drops.
-                transform: 'translate(-50%, -50%)',
+                transform: `translate(-50%, -50%) scale(${scale})`,
+                transformOrigin: 'center center',
+                display: 'flex',
+                alignItems: 'center',
                 fontSize: 10,
+                lineHeight: 1,
                 fontFamily: theme.fonts.monospace,
                 fontWeight: 500,
                 color,
                 background: 'rgba(21,21,21,0.9)',
                 border: verifiable ? `0.5px solid ${color}` : `1px dashed ${color}`,
                 borderRadius: verifiable ? 4 : '10px 14px 12px 16px / 14px 10px 16px 12px',
-                padding: '1px 5px',
+                padding: '3px 8px',
                 cursor: 'pointer',
                 pointerEvents: 'auto',
                 opacity: lbl.dimmed ? 0.15 : 1,
                 whiteSpace: 'nowrap',
               }}
             >
-              {lbl.stepNos?.length ? `${lbl.stepNos.map((n) => `${n}:`).join(' ')} ${lbl.mechanism}` : lbl.mechanism}
+              {text}
             </div>
           );
         })}
@@ -996,7 +1066,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         <Controls showZoom showFitView showInteractive />
       </ReactFlow>
       {/* Legend button — top-left overlay on the canvas; opens the modal. */}
-      {usedMechanisms.size > 0 && (
+      {showLegend !== false && usedMechanisms.size > 0 && (
         <button
           type="button"
           onClick={() => setLegendOpen(true)}
@@ -1022,6 +1092,36 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
           <MapIcon size={13} />
           Legend
         </button>
+      )}
+      {/* Graph title — non-interactive chip centered at the top of the canvas
+          (clear of the top-left legend button and top-right declaration
+          card). Lets graph-only embeds name the subsystem they show. */}
+      {graphTitle && (
+        <div
+          style={{
+            position: 'absolute',
+            top: 10,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            zIndex: 6,
+            maxWidth: '60%',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+            padding: '6px 18px',
+            fontSize: theme.fontSizes[3],
+            fontWeight: 600,
+            fontFamily: theme.fonts.heading,
+            color: theme.colors.text,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 6,
+            boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+            pointerEvents: 'none',
+          }}
+        >
+          {graphTitle}
+        </div>
       )}
         {/* Selected-component declaration — floating card over the canvas
             (top-right, clear of the top-left legend button). The graph never

package/src/subsystem/model.test.ts

@@ -2,6 +2,9 @@ import { describe, expect, test } from 'bun:test';
 import {
   convertSubsystemToNodes,
   convertSubsystemToEdges,
+  convertSubsystemToGroups,
+  getSubsystemRegions,
+  processGroupNodeId,
   buildSubsystemGraph,
   deriveNameFromSymbol,
   formatPurl,
@@ -121,6 +124,59 @@ describe('subsystem graph model', () => {
     expect(formatPurl('not-a-purl')).toBe('not-a-purl');
   });
 
+  test('getSubsystemRegions groups by process, skipping process-less nodes', () => {
+    const regions = getSubsystemRegions({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/acme/app', process: 'app/renderer' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+      ],
+    });
+    expect(regions.map((r) => r.key)).toEqual(['app/host', 'app/renderer']);
+    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+  });
+
+  test('convertSubsystemToNodes stamps parentId for process members only', () => {
+    const nodes = convertSubsystemToNodes({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+      ],
+      edges: [],
+    });
+    expect((nodes.find((n) => n.id === 'a') as { parentId?: string }).parentId).toBe(
+      processGroupNodeId('app/host'),
+    );
+    expect((nodes.find((n) => n.id === 'd') as { parentId?: string }).parentId).toBeUndefined();
+  });
+
+  test('convertSubsystemToGroups emits one parent per process', () => {
+    const groups = convertSubsystemToGroups({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+      ],
+    });
+    expect(groups).toHaveLength(1);
+    expect(groups[0]!.id).toBe(processGroupNodeId('app/host'));
+    expect(groups[0]!.type).toBe('subsystem-group');
+  });
+
+  test('buildSubsystemGraph drops singleton process frames (no parentId, no group)', async () => {
+    const { nodes, regions } = await buildSubsystemGraph({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { id: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+      ],
+      edges: [{ id: 'e1', from: 'a', to: 'b', mechanism: 'calls' }],
+    });
+    expect(regions.map((r) => r.key)).toEqual(['app/host']);
+    expect((nodes.find((n) => n.id === 'solo') as { parentId?: string }).parentId).toBeUndefined();
+    expect(nodes.find((n) => n.id === processGroupNodeId('app/lonely'))).toBeUndefined();
+  });
+
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
     const base = { components: comps, edges };
     const withRef = {

package/src/subsystem/model.ts

@@ -17,7 +17,7 @@ import {
   type Edge,
   type Node,
 } from '@xyflow/react';
-import { computeElkLayout } from '../utils/elkLayout';
+import { computeElkLayout, calculatePathLength } from '../utils/elkLayout';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
 
@@ -28,6 +28,7 @@ export type SubsystemComponentConstruct =
   | 'interface'
   | 'type_alias'
   | 'enum'
+  | 'react_component'
   | 'module'
   | 'store'
   | 'external';
@@ -92,12 +93,14 @@ export interface SubsystemComponent {
   name: string;
   /**
    * The node's construct — what it IS as a declaration (class, function,
-   * method, interface, type alias, enum, store, external), driving node
-   * anatomy, color, badge, and the verification strategy. Every construct
-   * anchors to a definition; runtime occurrences (variables, activations,
-   * instances) are NOT constructs — they belong to a future execution-mode
-   * graph whose occurrence nodes reference these definitions. Ontology:
-   * construct = what it is, role = where it sits, process = where it runs.
+   * method, interface, type alias, enum, react_component, store, external),
+   * driving node anatomy, color, badge, and the verification strategy. Every
+   * construct anchors to a definition; runtime occurrences (variables,
+   * activations, instances) are NOT constructs — they belong to a future
+   * execution-mode graph whose occurrence nodes reference these definitions.
+   * Ontology: construct = what it is, role = where it sits, process = where
+   * it runs. Use `react_component` (not `function`) for JSX/TSX UI units so
+   * the badge reads "component" instead of "function".
    */
   construct: SubsystemComponentConstruct;
   /** Source location the component lives in (repo-root-relative path). */
@@ -292,6 +295,46 @@ export interface SubsystemGraphDocument {
 
 export type SubsystemGraphNodeType = 'subsystem-component' | 'subsystem-group';
 
+/**
+ * One process boundary region — all components sharing a `process` value.
+ * Nodes without a `process` sit outside every boundary (no region).
+ */
+export interface SubsystemProcessRegion {
+  /** The `process` value (e.g. `trail-viewer/host`). */
+  key: string;
+  /** Display label for the boundary frame. */
+  label: string;
+  /** Component ids that are members of this region. */
+  memberIds: string[];
+}
+
+/** React Flow id for a process boundary group node. */
+export function processGroupNodeId(processKey: string): string {
+  return `process:${processKey}`;
+}
+
+/**
+ * Derive boundary regions from a document — one per distinct non-empty
+ * `process` value, in first-appearance order.
+ */
+export function getSubsystemRegions(
+  doc: Pick<SubsystemGraphDocument, 'components'>,
+): SubsystemProcessRegion[] {
+  const byProcess = new Map<string, string[]>();
+  for (const c of doc.components) {
+    const p = c.process?.trim();
+    if (!p) continue;
+    const list = byProcess.get(p) ?? [];
+    list.push(c.id);
+    byProcess.set(p, list);
+  }
+  return [...byProcess.entries()].map(([key, memberIds]) => ({
+    key,
+    label: key,
+    memberIds,
+  }));
+}
+
 export interface SubsystemGraphNodeData extends Record<string, unknown> {
   component: SubsystemComponent;
   /** Set while a file is open in the drawer: true if this node's component
@@ -302,7 +345,15 @@ export interface SubsystemGraphNodeData extends Record<string, unknown> {
   dimmed?: boolean;
 }
 
-export type SubsystemGraphNode = Node<SubsystemGraphNodeData, SubsystemGraphNodeType>;
+export interface SubsystemGroupNodeData extends Record<string, unknown> {
+  region: SubsystemProcessRegion;
+  /** True while the region's members are dimmed by flow focus. */
+  dimmed?: boolean;
+}
+
+export type SubsystemGraphNode =
+  | Node<SubsystemGraphNodeData, 'subsystem-component'>
+  | Node<SubsystemGroupNodeData, 'subsystem-group'>;
 
 export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   mechanism: SubsystemEdgeMechanism;
@@ -313,6 +364,8 @@ export interface SubsystemGraphEdgeData extends Record<string, unknown> {
   /** ELK-computed label midpoint (from the actual edge path, not node centers). */
   labelX?: number;
   labelY?: number;
+  /** Polyline length in flow-space units (for capping screen-space label size). */
+  pathLength?: number;
   /** ELK-computed SVG edge path (overrides React Flow's default path). */
   elkPath?: string;
 }
@@ -394,12 +447,11 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
 };
 
 /**
- * Convert a subsystem graph document into React Flow nodes. We render **flat**
- * (no React Flow parent/group nodes) for robustness: package regions are laid
- * out in a grid and each component carries its package + a `pkgBounds`
- * rectangle on its node data so the group wrapper (drawn by the graph
- * component) can frame it. Only components' real positions matter to React
- * Flow; the package boundary is a visual region, not a sub-flow node.
+ * Convert a subsystem graph document into React Flow nodes. Components that
+ * carry a `process` get a `parentId` pointing at their boundary group node
+ * (`process:<process>`); nodes without one stay top-level (outside every
+ * boundary). The initial grid groups by `process ?? purl` so the pre-ELK
+ * positions are already clustered; ELK then refines with compound layout.
  */
 export function convertSubsystemToNodes(
   doc: SubsystemGraphDocument,
@@ -447,9 +499,11 @@ export function convertSubsystemToNodes(
       const cssBorder = 4; // 2px border each side
       const rawWidth = Math.max(cssMinWidth, textWidth + cssPadding + cssBorder);
       const nodeWidth = Math.max(cssMinWidth, Math.min(cap, rawWidth));
+      const processKey = c.process?.trim();
       nodes.push({
         id: c.id,
         type: 'subsystem-component',
+        ...(processKey ? { parentId: processGroupNodeId(processKey) } : {}),
         position: { x: PAD + col * COL_W, y: cursorY + row * ROW_H },
         width: nodeWidth,
         height: 84,
@@ -461,6 +515,24 @@ export function convertSubsystemToNodes(
   return nodes;
 }
 
+/**
+ * Convert boundary regions into React Flow parent (group) nodes. One per
+ * distinct `process` value; member components point at these via `parentId`.
+ * Positions/sizes are placeholders — ELK compound layout overwrites them.
+ */
+export function convertSubsystemToGroups(
+  doc: Pick<SubsystemGraphDocument, 'components'>,
+): SubsystemGraphNode[] {
+  return getSubsystemRegions(doc).map((region) => ({
+    id: processGroupNodeId(region.key),
+    type: 'subsystem-group',
+    position: { x: 0, y: 0 },
+    width: 400,
+    height: 300,
+    data: { region },
+  }));
+}
+
 /**
  * Convert a subsystem graph document into React Flow edges. Edges whose target
  * is an external label (not a component id) point at a synthetic stub so the
@@ -522,10 +594,23 @@ export async function buildSubsystemGraph(
 ): Promise<{
   nodes: SubsystemGraphNode[];
   edges: SubsystemGraphEdge[];
+  regions: SubsystemProcessRegion[];
 }> {
   const { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights } = opts;
   const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
   const edges = convertSubsystemToEdges(doc);
+  // Boundary regions: one per multi-member process. Singletons get no frame —
+  // strip the parentId convertSubsystemToNodes stamped so React Flow never
+  // points at a non-existent parent.
+  const regions = getSubsystemRegions(doc).filter((r) => r.memberIds.length >= 2);
+  const regionKeys = new Set(regions.map((r) => r.key));
+  for (const n of nodes) {
+    if (n.type !== 'subsystem-component') continue;
+    const proc = (n.data as SubsystemGraphNodeData).component?.process?.trim();
+    if (proc && !regionKeys.has(proc)) {
+      delete (n as { parentId?: string }).parentId;
+    }
+  }
 
   // External edge targets that aren't real components → create stub nodes so
   // cross-package edges have something to land on.
@@ -574,10 +659,12 @@ export async function buildSubsystemGraph(
     }
   }
 
-  // ELK auto-layout: position nodes (layered, minimized crossings).
+  // ELK auto-layout: position nodes (layered, minimized crossings) with
+  // process partitions as compound parents so boundaries shape the layout.
   let placedNodes = nodes;
   let labelPositions = new Map<string, { x: number; y: number }>();
   let elkPathStrings = new Map<string, string>();
+  let elkPathPoints = new Map<string, { x: number; y: number }[]>();
   if (nodes.length > 0) {
     try {
       const result = await computeElkLayout(nodes, edges, {
@@ -589,10 +676,29 @@ export async function buildSubsystemGraph(
         interLayerSpacing: 120,
         preserveNodePositions: false,
         edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
+        groups: regions.map((r) => ({
+          id: processGroupNodeId(r.key),
+          memberIds: r.memberIds,
+        })),
       });
-      placedNodes = result.nodes as SubsystemGraphNode[];
+      const groupNodes: SubsystemGraphNode[] = regions.flatMap((region) => {
+        const bounds = result.groupBounds.get(processGroupNodeId(region.key));
+        if (!bounds) return [];
+        const group: SubsystemGraphNode = {
+          id: processGroupNodeId(region.key),
+          type: 'subsystem-group',
+          position: { x: bounds.x, y: bounds.y },
+          width: Math.max(200, bounds.width),
+          height: Math.max(160, bounds.height),
+          data: { region },
+        };
+        return [group];
+      });
+      // Parents first — React Flow resolves children via parentId.
+      placedNodes = [...groupNodes, ...(result.nodes as SubsystemGraphNode[])];
       labelPositions = result.edgeLabelPositions;
       elkPathStrings = result.edgePaths;
+      elkPathPoints = result.edgePathPoints;
     } catch (err) {
       // Fall back to the (unpositioned) grid if ELK is unavailable.
       console.warn('[subsystem-graph] ELK layout failed, using manual positions:', err);
@@ -613,7 +719,12 @@ export async function buildSubsystemGraph(
       const d = (e as SubsystemGraphEdge).data as SubsystemGraphEdgeData;
       d.elkPath = elkP;
     }
+    const pts = elkPathPoints.get(e.id);
+    if (pts && pts.length > 1) {
+      const d = (e as SubsystemGraphEdge).data as SubsystemGraphEdgeData;
+      d.pathLength = calculatePathLength(pts);
+    }
   }
 
-  return { nodes: placedNodes, edges };
+  return { nodes: placedNodes, edges, regions };
 }