@principal-ai/subsystems-react 0.23.0 → 0.23.2

package/src/subsystem/model.ts

@@ -20,6 +20,7 @@ import {
 import { computeElkLayout, calculatePathLength } from '../utils/elkLayout';
 import type { GraphifyComponentDetail } from '../graphify';
 import type { SubsystemDeclarationRef } from './declarationRef';
+import { purlOwnerName, purlRepoKey } from './paths';
 
 /** Structured declaration shape — same union as graphify drill-down payloads. */
 export type SubsystemConstructDeclaration = GraphifyComponentDetail;
@@ -430,13 +431,15 @@ export function formatPurl(purl: string): string {
 export type SubsystemGraphNodeType = 'subsystem-component' | 'subsystem-group';
 
 /**
- * One boundary region — either a process (runtime deployment unit) or a
- * module (source file). Nodes without that field sit outside those frames.
+ * One boundary region — process (runtime), module (source file), or package
+ * (repo identity from `purl`). Nodes without that membership sit outside
+ * those frames. Package frames are derived from `purl` (no separate field);
+ * they only appear when the graph spans multiple repos (by default).
  */
 export interface SubsystemProcessRegion {
-  /** Discriminator — which field produced this region. */
-  kind: 'process' | 'module';
-  /** The `process` or `module` value (e.g. `principal-studio/host`, `src/a.ts`). */
+  /** Discriminator — which field / identity produced this region. */
+  kind: 'process' | 'module' | 'package';
+  /** The `process` / `module` value, or purl repo key for packages. */
   key: string;
   /** Display label for the boundary frame. */
   label: string;
@@ -444,6 +447,22 @@ export interface SubsystemProcessRegion {
   memberIds: string[];
 }
 
+/** Options for which boundary frames are kept. */
+export interface BoundaryFrameOptions {
+  /**
+   * Keep 1-member process / module / package frames. Default false
+   * (singleton rule — frames need 2+ members).
+   */
+  showSingletonFrames?: boolean;
+  /**
+   * When package frames are drawn from component `purl`s.
+   * - `multi-repo` (default): only when 2+ distinct repo purls
+   * - `always`: frame every multi-member package even in a single-repo graph
+   * - `never`: no package frames
+   */
+  packageFrames?: 'multi-repo' | 'always' | 'never';
+}
+
 /** React Flow id for a process boundary group node. */
 export function processGroupNodeId(processKey: string): string {
   return `process:${processKey}`;
@@ -454,11 +473,33 @@ export function moduleGroupNodeId(moduleKey: string): string {
   return `module:${moduleKey}`;
 }
 
-/** React Flow id for a boundary group of either kind. */
+/** React Flow id for a package (repo) boundary group node. */
+export function packageGroupNodeId(packageKey: string): string {
+  return `package:${packageKey}`;
+}
+
+/** React Flow id for a boundary group of any kind. */
 export function boundaryGroupNodeId(region: Pick<SubsystemProcessRegion, 'kind' | 'key'>): string {
-  return region.kind === 'module'
-    ? moduleGroupNodeId(region.key)
-    : processGroupNodeId(region.key);
+  if (region.kind === 'module') return moduleGroupNodeId(region.key);
+  if (region.kind === 'package') return packageGroupNodeId(region.key);
+  return processGroupNodeId(region.key);
+}
+
+/**
+ * Repo/package key used for package frames — `purl` with fragment stripped.
+ * Externals and custom entities are not package-frame members.
+ */
+export function componentPackageKey(
+  c: Pick<SubsystemComponent, 'purl' | 'construct'>,
+): string | undefined {
+  if (c.construct === 'external' || c.construct === 'custom_entity') return undefined;
+  const key = purlRepoKey(c.purl);
+  if (!key || key === 'external') return undefined;
+  return key;
+}
+
+function packageRegionLabel(packageKey: string): string {
+  return purlOwnerName(packageKey) ?? formatPurl(packageKey);
 }
 
 /**
@@ -508,42 +549,103 @@ export function getSubsystemModuleRegions(
 }
 
 /**
- * One compound frame for ELK / React Flow — module frames may nest under a
- * process frame via `parentId`.
+ * Derive package (repo) boundary regions from component `purl`s — one per
+ * distinct repo key. Does not apply multi-repo / singleton filters; callers
+ * decide via {@link buildBoundaryLayoutGroups}.
+ */
+export function getSubsystemPackageRegions(
+  doc: Pick<SubsystemModelDocument, 'components'>,
+): SubsystemProcessRegion[] {
+  const byPackage = new Map<string, string[]>();
+  for (const c of doc.components) {
+    const key = componentPackageKey(c);
+    if (!key) continue;
+    const list = byPackage.get(key) ?? [];
+    list.push(c.id);
+    byPackage.set(key, list);
+  }
+  return [...byPackage.entries()].map(([key, memberIds]) => ({
+    kind: 'package' as const,
+    key,
+    label: packageRegionLabel(key),
+    memberIds,
+  }));
+}
+
+/**
+ * One compound frame for ELK / React Flow — modules nest under processes,
+ * processes under packages, when membership is shared.
  */
 export interface BoundaryLayoutGroup {
   id: string;
   memberIds: string[];
-  /** When set, this group is a child of another boundary group (process). */
+  /** When set, this group is a child of another boundary group. */
   parentId?: string;
   region: SubsystemProcessRegion;
 }
 
+function keepRegion(
+  r: SubsystemProcessRegion,
+  showSingletons: boolean,
+): boolean {
+  return showSingletons || r.memberIds.length >= 2;
+}
+
 /**
- * Build the process → module → leaf group tree for layout.
- * Multi-member modules nest under a process when every member shares that
- * process; process ELK children are nested module group ids plus any
- * process members that are not inside a kept module frame.
+ * Build the package → process → module → leaf group tree for layout.
+ *
+ * Package frames come from `purl` (no separate component field). By default
+ * they only appear when the graph spans 2+ distinct repos. Multi-member
+ * modules nest under a process when every member shares that process;
+ * processes nest under a package the same way.
  */
 export function buildBoundaryLayoutGroups(
   doc: Pick<SubsystemModelDocument, 'components'>,
+  opts: BoundaryFrameOptions = {},
 ): BoundaryLayoutGroup[] {
+  const showSingletons = opts.showSingletonFrames === true;
+  const packageMode = opts.packageFrames ?? 'multi-repo';
   const byId = new Map(doc.components.map((c) => [c.id, c]));
-  const modules = getSubsystemModuleRegions(doc).filter((r) => r.memberIds.length >= 2);
-  const processes = getSubsystemRegions(doc).filter((r) => r.memberIds.length >= 2);
+
+  const allPackages = getSubsystemPackageRegions(doc);
+  const packageEligible =
+    packageMode === 'always'
+      ? true
+      : packageMode === 'never'
+        ? false
+        : allPackages.length >= 2;
+  const packages = packageEligible
+    ? allPackages.filter((r) => keepRegion(r, showSingletons))
+    : [];
+  const keptPackageKeys = new Set(packages.map((r) => r.key));
+
+  const modules = getSubsystemModuleRegions(doc).filter((r) =>
+    keepRegion(r, showSingletons),
+  );
+  const processes = getSubsystemRegions(doc).filter((r) =>
+    keepRegion(r, showSingletons),
+  );
   const keptProcessKeys = new Set(processes.map((r) => r.key));
 
   const moduleGroups: BoundaryLayoutGroup[] = modules.map((r) => {
     const processesOfMembers = new Set<string>();
+    const packagesOfMembers = new Set<string>();
     for (const id of r.memberIds) {
-      const p = byId.get(id)?.process?.trim();
+      const c = byId.get(id);
+      const p = c?.process?.trim();
       if (p) processesOfMembers.add(p);
+      const pkg = c ? componentPackageKey(c) : undefined;
+      if (pkg) packagesOfMembers.add(pkg);
     }
     let parentId: string | undefined;
     if (processesOfMembers.size === 1) {
       const p = [...processesOfMembers][0]!;
       if (keptProcessKeys.has(p)) parentId = processGroupNodeId(p);
     }
+    if (!parentId && packagesOfMembers.size === 1) {
+      const pkg = [...packagesOfMembers][0]!;
+      if (keptPackageKeys.has(pkg)) parentId = packageGroupNodeId(pkg);
+    }
     return {
       id: moduleGroupNodeId(r.key),
       memberIds: [...r.memberIds],
@@ -561,14 +663,51 @@ export function buildBoundaryLayoutGroups(
       if (!mod) return true;
       return !nestedModuleKeys.has(mod);
     });
+
+    const packagesOfMembers = new Set<string>();
+    for (const id of r.memberIds) {
+      const c = byId.get(id);
+      const pkg = c ? componentPackageKey(c) : undefined;
+      if (pkg) packagesOfMembers.add(pkg);
+    }
+    let parentId: string | undefined;
+    if (packagesOfMembers.size === 1) {
+      const pkg = [...packagesOfMembers][0]!;
+      if (keptPackageKeys.has(pkg)) parentId = packageGroupNodeId(pkg);
+    }
+
     return {
       id: processId,
       memberIds: [...nestedModules.map((m) => m.id), ...directLeaves],
+      parentId,
       region: r,
     };
   });
 
-  return [...moduleGroups, ...processGroups];
+  const packageGroups: BoundaryLayoutGroup[] = packages.map((r) => {
+    const packageId = packageGroupNodeId(r.key);
+    const nestedProcesses = processGroups.filter((p) => p.parentId === packageId);
+    const nestedModules = moduleGroups.filter((m) => m.parentId === packageId);
+    const claimed = new Set<string>();
+    for (const p of nestedProcesses) {
+      for (const id of p.region.memberIds) claimed.add(id);
+    }
+    for (const m of nestedModules) {
+      for (const id of m.region.memberIds) claimed.add(id);
+    }
+    const directLeaves = r.memberIds.filter((id) => !claimed.has(id));
+    return {
+      id: packageId,
+      memberIds: [
+        ...nestedProcesses.map((p) => p.id),
+        ...nestedModules.map((m) => m.id),
+        ...directLeaves,
+      ],
+      region: r,
+    };
+  });
+
+  return [...moduleGroups, ...processGroups, ...packageGroups];
 }
 
 export interface SubsystemGraphNodeData extends Record<string, unknown> {
@@ -689,6 +828,14 @@ export const ROLE_COLOR: Record<SubsystemComponentRole, string> = {
   service: '#0893d2', // blue — external system
 };
 
+/**
+ * Brand color for the left construct/stereotype badge when a framework owns
+ * the label (e.g. `react · component`). Node border stays construct-colored.
+ */
+export const FRAMEWORK_BADGE_COLOR: Record<string, string> = {
+  react: '#61dafb', // React cyan
+};
+
 export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
   entry: 'entry',
   service: 'service',
@@ -790,14 +937,27 @@ export function constructBadgeLabel(component: {
   return constructLabel ?? '';
 }
 
+/**
+ * Left-badge accent: framework brand when the badge shows a framework
+ * stereotype (e.g. React cyan for `react · component`); otherwise null so
+ * the caller falls back to construct color. Border stays construct-colored.
+ */
+export function constructBadgeColor(component: {
+  framework?: string;
+  stereotype?: string;
+}): string | null {
+  if (component.framework == null || component.stereotype == null) return null;
+  return FRAMEWORK_BADGE_COLOR[component.framework] ?? null;
+}
+
 /** Default CSS floor for component nodes (padding aside). */
 export const NODE_CSS_MIN_WIDTH = 150;
 /** Inset of each top badge from the node edge (`left` / `right` style). */
 export const BADGE_EDGE_INSET = 5;
 /** Minimum gap between left construct badge and right role badge. */
 const BADGE_PAIR_GAP = 8;
-/** Badge box chrome: padding 5+5 + border 1+1. */
-const BADGE_BOX_CHROME = 12;
+/** Badge box chrome: padding 8+8 + border 2+2. */
+const BADGE_BOX_CHROME = 20;
 /** Approx monospace uppercase width incl. letter-spacing (~0.5px). */
 const BADGE_CHAR_WIDTH = 8;
 
@@ -840,11 +1000,11 @@ export function nodeMinWidthForBadges(component: {
 /**
  * Convert a subsystem graph document into React Flow nodes. Components that
  * carry a `module` get a `parentId` pointing at their module frame
- * (`module:<path>`); otherwise a `process` stamps `process:<process>`. Module
- * frames may themselves nest under a process frame (stamped on the group node
- * in `buildSubsystemGraph`). Nodes without either stay top-level. The initial
- * grid clusters by `module ?? process ?? purl`; ELK then refines with compound
- * layout.
+ * (`module:<path>`); otherwise a `process` stamps `process:<process>`.
+ * Package (`purl`) parents are stamped later in `buildSubsystemGraph` only
+ * when package frames are kept. Module frames may nest under process →
+ * package. The initial grid clusters by `module ?? process ?? purl`; ELK
+ * then refines with compound layout.
  */
 export function convertSubsystemToNodes(
   doc: SubsystemModelDocument,
@@ -913,14 +1073,15 @@ export function convertSubsystemToNodes(
 }
 
 /**
- * Convert boundary regions into React Flow parent (group) nodes. Module
- * frames that share a process nest under that process via `parentId`.
+ * Convert boundary regions into React Flow parent (group) nodes. Nesting
+ * (package → process → module) is stamped via `parentId` on groups.
  * Positions/sizes are placeholders — ELK compound layout overwrites them.
  */
 export function convertSubsystemToGroups(
   doc: Pick<SubsystemModelDocument, 'components'>,
+  opts: BoundaryFrameOptions = {},
 ): SubsystemGraphNode[] {
-  return buildBoundaryLayoutGroups(doc).map((g) => ({
+  return buildBoundaryLayoutGroups(doc, opts).map((g) => ({
     id: g.id,
     type: 'subsystem-group' as const,
     position: { x: 0, y: 0 },
@@ -988,36 +1149,55 @@ export function subsystemGraphLayoutKey(
  */
 export async function buildSubsystemGraph(
   doc: SubsystemModelDocument,
-  opts: { maxNodeWidth?: number; showEdgeLabels?: boolean; measuredWidths?: Map<string, number>; measuredHeights?: Map<string, number> } = {},
+  opts: {
+    maxNodeWidth?: number;
+    showEdgeLabels?: boolean;
+    measuredWidths?: Map<string, number>;
+    measuredHeights?: Map<string, number>;
+  } & BoundaryFrameOptions = {},
 ): Promise<{
   nodes: SubsystemGraphNode[];
   edges: SubsystemGraphEdge[];
   regions: SubsystemProcessRegion[];
 }> {
-  const { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights } = opts;
+  const {
+    maxNodeWidth,
+    showEdgeLabels,
+    measuredWidths,
+    measuredHeights,
+    showSingletonFrames,
+    packageFrames,
+  } = opts;
+  const frameOpts: BoundaryFrameOptions = { showSingletonFrames, packageFrames };
   const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
   const edges = convertSubsystemToEdges(doc);
-  // Nested boundary tree: process → module → leaves (when both fields set).
-  const layoutGroups = buildBoundaryLayoutGroups(doc);
+  // Nested boundary tree: package → process → module → leaves.
+  const layoutGroups = buildBoundaryLayoutGroups(doc, frameOpts);
   const regions = layoutGroups.map((g) => g.region);
   const regionIds = new Set(layoutGroups.map((g) => g.id));
   const byId = new Map(doc.components.map((c) => [c.id, c]));
 
-  // Drop leaf parentIds that point at singleton / missing frames; fall back
-  // from a dropped module frame to a kept process frame when possible.
+  // Resolve leaf parentIds against kept frames: module → process → package.
+  // Stamp package parents here (not in convertSubsystemToNodes) so single-repo
+  // graphs never provisionally parent under a package that will be dropped.
   for (const n of nodes) {
     if (n.type !== 'subsystem-component') continue;
     const parentId = (n as { parentId?: string }).parentId;
-    if (!parentId) continue;
-    if (regionIds.has(parentId)) continue;
-    const comp = (n.data as SubsystemGraphNodeData).component;
-    const processKey = comp?.process?.trim() || byId.get(n.id)?.process?.trim();
+    if (parentId && regionIds.has(parentId)) continue;
+    const comp = (n.data as SubsystemGraphNodeData).component ?? byId.get(n.id);
+    const processKey = comp?.process?.trim();
     const processId = processKey ? processGroupNodeId(processKey) : undefined;
     if (processId && regionIds.has(processId)) {
       (n as { parentId?: string }).parentId = processId;
-    } else {
-      delete (n as { parentId?: string }).parentId;
+      continue;
     }
+    const packageKey = comp ? componentPackageKey(comp) : undefined;
+    const packageId = packageKey ? packageGroupNodeId(packageKey) : undefined;
+    if (packageId && regionIds.has(packageId)) {
+      (n as { parentId?: string }).parentId = packageId;
+      continue;
+    }
+    if (parentId) delete (n as { parentId?: string }).parentId;
   }
 
   // External edge targets that aren't real components → create stub nodes so
@@ -1090,7 +1270,8 @@ export async function buildSubsystemGraph(
         })),
       });
       const builtGroupIds = new Set(result.groupBounds.keys());
-      // Parents before children — process frames, then nested module frames.
+      // Parents before children — package, then process, then module frames.
+      const packageGroupNodes: SubsystemGraphNode[] = [];
       const processGroupNodes: SubsystemGraphNode[] = [];
       const moduleGroupNodes: SubsystemGraphNode[] = [];
       for (const g of layoutGroups) {
@@ -1107,7 +1288,8 @@ export async function buildSubsystemGraph(
           ...(parentId ? { parentId } : {}),
           data: { region: g.region },
         };
-        if (g.region.kind === 'process') processGroupNodes.push(group);
+        if (g.region.kind === 'package') packageGroupNodes.push(group);
+        else if (g.region.kind === 'process') processGroupNodes.push(group);
         else moduleGroupNodes.push(group);
       }
       // Clear leaf parentIds that point at groups ELK dropped.
@@ -1119,6 +1301,7 @@ export async function buildSubsystemGraph(
         }
       }
       placedNodes = [
+        ...packageGroupNodes,
         ...processGroupNodes,
         ...moduleGroupNodes,
         ...(result.nodes as SubsystemGraphNode[]),
@@ -1130,6 +1313,7 @@ export async function buildSubsystemGraph(
       // Fall back to the (unpositioned) grid if ELK is unavailable — still
       // emit multi-member frames so parentId targets exist.
       console.warn('[subsystem-graph] ELK layout failed, using manual positions:', err);
+      const packageGroupNodes: SubsystemGraphNode[] = [];
       const processGroupNodes: SubsystemGraphNode[] = [];
       const moduleGroupNodes: SubsystemGraphNode[] = [];
       for (const g of layoutGroups) {
@@ -1142,10 +1326,16 @@ export async function buildSubsystemGraph(
           ...(g.parentId ? { parentId: g.parentId } : {}),
           data: { region: g.region },
         };
-        if (g.region.kind === 'process') processGroupNodes.push(group);
+        if (g.region.kind === 'package') packageGroupNodes.push(group);
+        else if (g.region.kind === 'process') processGroupNodes.push(group);
         else moduleGroupNodes.push(group);
       }
-      placedNodes = [...processGroupNodes, ...moduleGroupNodes, ...nodes];
+      placedNodes = [
+        ...packageGroupNodes,
+        ...processGroupNodes,
+        ...moduleGroupNodes,
+        ...nodes,
+      ];
     }
   }
 

package/src/subsystem/nodes.tsx

@@ -20,6 +20,7 @@ import {
   MECHANISM_COLOR,
   MECHANISM_STYLE,
   PROPOSED_COLOR,
+  constructBadgeColor,
   constructBadgeLabel,
   rightBadgeLabel,
   rightBadgeColor,
@@ -88,6 +89,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // shows as the hover badge, not as color — for now; a role glyph/accent may
   // come later. A component-authored `color` override wins over the construct.
   const color = componentColor(c, resolvePierreSyntaxThemeName(mode));
+  // Left badge: framework brand (e.g. React cyan) when the label is a
+  // framework stereotype; otherwise the same construct color as the border.
+  const badgeColor = constructBadgeColor(c) ?? color;
   const [hover, setHover] = useState(false);
   const configuredMax = SUBSYSTEM_CALLBACKS.maxNodeWidth;
   const maxWidth = configuredMax ?? 300;
@@ -114,6 +118,10 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // Selection is stamped into data by the graph component — React Flow's own
   // `selected` never updates because the node stops click propagation.
   const isSelected = selected || (data.isSelected as boolean | undefined) === true;
+  // Externals are "outside" the system — square corners on the node + badges.
+  const isExternal = c.construct === 'external';
+  const nodeRadius = isExternal ? 0 : 8;
+  const badgeRadius = isExternal ? 0 : 4;
 
   return (
     <div
@@ -141,7 +149,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         minWidth: badgeMinWidth,
         maxWidth,
         padding: '6px 10px',
-        borderRadius: 8,
+        borderRadius: nodeRadius,
         background: theme.colors.backgroundSecondary ?? theme.colors.background,
         // Selected / file-matched nodes get a thicker border. Proposed nodes
         // use a dashed goldenrod border; left construct badge keeps construct color.
@@ -157,11 +165,12 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
     >
       {/* Construct / stereotype badge — prefers framework stereotype so a
           React UI unit reads as "react · component" instead of "function".
-          Persistent; pointer-events none so clicks pass through to the node. */}
+          Persistent; pointer-events none so clicks pass through to the node.
+          Framework badges use brand color; border stays construct-colored. */}
       <div
         style={{
           position: 'absolute',
-          top: -9,
+          top: -11,
           left: BADGE_EDGE_INSET,
           zIndex: 1,
           fontFamily: theme.fonts.monospace,
@@ -170,11 +179,11 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
           textTransform: 'uppercase',
           lineHeight: '17px',
           whiteSpace: 'nowrap',
-          color,
+          color: badgeColor,
           background: theme.colors.backgroundSecondary ?? theme.colors.background,
-          border: `1px solid ${color}`,
-          borderRadius: 4,
-          padding: '0 5px',
+          border: `2px solid ${badgeColor}`,
+          borderRadius: badgeRadius,
+          padding: '2px 8px',
         }}
       >
         {constructBadgeLabel(c)}
@@ -187,7 +196,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         <div
           style={{
             position: 'absolute',
-            top: -9,
+            top: -11,
             right: BADGE_EDGE_INSET,
             zIndex: 1,
             display: 'flex',
@@ -205,9 +214,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
                 lineHeight: '17px',
                 color: storageColor,
                 background: theme.colors.backgroundSecondary ?? theme.colors.background,
-                border: `1px solid ${storageColor}`,
-                borderRadius: 4,
-                padding: '0 5px',
+                border: `2px solid ${storageColor}`,
+                borderRadius: badgeRadius,
+                padding: '2px 8px',
               }}
             >
               {storageLabel}
@@ -223,9 +232,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
                 lineHeight: '17px',
                 color: topRightColor,
                 background: theme.colors.backgroundSecondary ?? theme.colors.background,
-                border: `1px solid ${topRightColor}`,
-                borderRadius: 4,
-                padding: '0 5px',
+                border: `2px solid ${topRightColor}`,
+                borderRadius: badgeRadius,
+                padding: '2px 8px',
               }}
             >
               {topRightLabel}
@@ -241,7 +250,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         <div
           style={{
             position: 'absolute',
-            bottom: -13,
+            bottom: -14,
             left: '50%',
             transform: 'translateX(-50%)',
             zIndex: 1,
@@ -254,9 +263,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
             // borders and badges, not the file name
             color: theme.colors.text ?? theme.colors.textSecondary,
             background: theme.colors.backgroundSecondary ?? theme.colors.background,
-            border: `1px solid ${color}`,
-            borderRadius: 4,
-            padding: '0 5px',
+            border: `2px solid ${color}`,
+            borderRadius: badgeRadius,
+            padding: '2px 8px',
             cursor: 'pointer',
           }}
           onClick={(e) => {
@@ -341,8 +350,21 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
   const color = packageColor(region?.key ?? 'process');
   const dimmed = data.dimmed === true;
   const hidden = (data as { hidden?: boolean }).hidden === true;
-  const label =
-    region?.kind === 'module' ? `module · ${region.label}` : (region?.label ?? '');
+  // Label is the region identity alone (path / process key / owner/name).
+  // Kind is carried by frame chrome (square = process; rounded = module/package)
+  // — don't prefix `module ·` / `package ·` or the path reads twice.
+  const label = region?.label ?? '';
+  // Process frames match external nodes — square corners (outside the soft
+  // component language). Module / package frames keep the rounded look.
+  const isProcess = region?.kind === 'process';
+  const frameRadius = isProcess ? 0 : 12;
+  const badgeRadius = isProcess ? 0 : 4;
+  // Processes are deployment units — solid frame. Modules/packages stay dashed
+  // until selected.
+  const frameStyle = isProcess || selected ? 'solid' : 'dashed';
+  // Process keeps a tinted fill; module / package bodies stay transparent so
+  // nested frames don't stack washes.
+  const frameFill = isProcess ? `${color}14` : 'transparent';
 
   if (!region) return null;
 
@@ -353,9 +375,9 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
         width: width ?? 400,
         height: height ?? 300,
         boxSizing: 'border-box',
-        borderRadius: 12,
-        border: `2px ${selected ? 'solid' : 'dashed'} ${color}`,
-        background: `${color}14`,
+        borderRadius: frameRadius,
+        border: `2px ${frameStyle} ${color}`,
+        background: frameFill,
         opacity: hidden ? 0 : dimmed ? 0.35 : 1,
         transition: 'opacity 150ms ease',
         pointerEvents: 'none',
@@ -364,8 +386,14 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
       <div
         style={{
           position: 'absolute',
-          top: -19,
-          left: 12,
+          // Process: badge fill starts with the process fill (inside the
+          // frame border); no top badge border so widths don't fight.
+          // Module/package sit astride the top edge like component badges.
+          // Always set left/transform/borderTop explicitly — React Flow reuses
+          // group DOM nodes and `undefined` does not clear a prior value.
+          top: isProcess ? 0 : -19,
+          left: isProcess ? '50%' : 12,
+          transform: isProcess ? 'translateX(-50%)' : 'none',
           fontFamily: theme.fonts.monospace,
           fontSize: theme.fontSizes[3],
           fontWeight: 700,
@@ -373,7 +401,8 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           color,
           background: theme.colors.backgroundSecondary ?? theme.colors.background,
           border: `1px solid ${color}`,
-          borderRadius: 4,
+          borderTopWidth: isProcess ? 0 : 1,
+          borderRadius: badgeRadius,
           padding: '1px 7px',
           whiteSpace: 'nowrap',
         }}