@principal-ai/subsystems-react 0.23.1 → 0.23.2

package/src/subsystem/model.test.ts

@@ -5,11 +5,17 @@ import {
   convertSubsystemToGroups,
   getSubsystemRegions,
   getSubsystemModuleRegions,
+  getSubsystemPackageRegions,
   processGroupNodeId,
   moduleGroupNodeId,
+  packageGroupNodeId,
+  buildBoundaryLayoutGroups,
   buildSubsystemGraph,
+  componentPackageKey,
   deriveNameFromSymbol,
   constructBadgeLabel,
+  constructBadgeColor,
+  FRAMEWORK_BADGE_COLOR,
   rightBadgeLabel,
   nodeMinWidthForBadges,
   formatPurl,
@@ -148,6 +154,15 @@ describe('subsystem graph model', () => {
     ).toBe('custom_entity');
   });
 
+  test('constructBadgeColor uses React brand only for framework stereotype badges', () => {
+    expect(
+      constructBadgeColor({ framework: 'react', stereotype: 'component' }),
+    ).toBe(FRAMEWORK_BADGE_COLOR.react);
+    expect(constructBadgeColor({ framework: 'react' })).toBeNull();
+    expect(constructBadgeColor({ stereotype: 'hook' })).toBeNull();
+    expect(constructBadgeColor({ framework: 'vue', stereotype: 'component' })).toBeNull();
+  });
+
   test('nodeMinWidthForBadges widens for long construct badges and role pairs', () => {
     const plain = nodeMinWidthForBadges({ construct: 'function' });
     expect(plain).toBe(150);
@@ -445,6 +460,158 @@ describe('subsystem graph model', () => {
     expect(nodes.find((n) => n.id === moduleGroupNodeId('src/session/transcript.ts'))).toBeDefined();
   });
 
+  test('getSubsystemPackageRegions groups by purl repo key, skipping externals', () => {
+    const regions = getSubsystemPackageRegions({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app#a.ts' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { id: 'ext', name: 'Stripe', construct: 'external', file: '', purl: 'pkg:npm/stripe' },
+      ],
+    });
+    expect(regions.map((r) => r.key).sort()).toEqual([
+      'pkg:github/acme/app',
+      'pkg:github/other/lib',
+    ].sort());
+    expect(regions.every((r) => r.kind === 'package')).toBe(true);
+    expect(componentPackageKey({ construct: 'external', purl: 'pkg:npm/stripe' })).toBeUndefined();
+  });
+
+  test('buildBoundaryLayoutGroups skips package frames for single-repo graphs', () => {
+    const groups = buildBoundaryLayoutGroups({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+      ],
+    });
+    expect(groups.filter((g) => g.region.kind === 'package')).toHaveLength(0);
+  });
+
+  test('buildBoundaryLayoutGroups frames packages when multi-repo', () => {
+    const groups = buildBoundaryLayoutGroups({
+      components: [
+        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/other/lib' },
+      ],
+    });
+    const pkgs = groups.filter((g) => g.region.kind === 'package');
+    expect(pkgs.map((g) => g.region.key).sort()).toEqual([
+      'pkg:github/acme/app',
+      'pkg:github/other/lib',
+    ].sort());
+  });
+
+  test('buildBoundaryLayoutGroups nests process under package', () => {
+    const groups = buildBoundaryLayoutGroups({
+      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/other/lib',
+          process: 'lib/worker',
+        },
+        {
+          id: 'd',
+          name: 'd',
+          construct: 'function',
+          file: 'd.ts',
+          purl: 'pkg:github/other/lib',
+          process: 'lib/worker',
+        },
+      ],
+    });
+    const host = groups.find((g) => g.id === processGroupNodeId('app/host'));
+    expect(host?.parentId).toBe(packageGroupNodeId('pkg:github/acme/app'));
+  });
+
+  test('buildSubsystemGraph nests package → process → module', async () => {
+    const { nodes } = await buildSubsystemGraph({
+      components: [
+        {
+          id: 'a1',
+          name: 'a1',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/a.ts',
+        },
+        {
+          id: 'a2',
+          name: 'a2',
+          construct: 'function',
+          file: 'a.ts',
+          purl: 'pkg:github/acme/app',
+          process: 'app/host',
+          module: 'src/a.ts',
+        },
+        {
+          id: 'b1',
+          name: 'b1',
+          construct: 'function',
+          file: 'b.ts',
+          purl: 'pkg:github/other/lib',
+          process: 'lib/worker',
+          module: 'src/b.ts',
+        },
+        {
+          id: 'b2',
+          name: 'b2',
+          construct: 'function',
+          file: 'b.ts',
+          purl: 'pkg:github/other/lib',
+          process: 'lib/worker',
+          module: 'src/b.ts',
+        },
+      ],
+      relations: [],
+    });
+    const pkgA = nodes.find((n) => n.id === packageGroupNodeId('pkg:github/acme/app'));
+    const proc = nodes.find((n) => n.id === processGroupNodeId('app/host'));
+    const mod = nodes.find((n) => n.id === moduleGroupNodeId('src/a.ts'));
+    expect(pkgA).toBeDefined();
+    expect((proc as { parentId?: string }).parentId).toBe(
+      packageGroupNodeId('pkg:github/acme/app'),
+    );
+    expect((mod as { parentId?: string }).parentId).toBe(processGroupNodeId('app/host'));
+    expect((nodes.find((n) => n.id === 'a1') as { parentId?: string }).parentId).toBe(
+      moduleGroupNodeId('src/a.ts'),
+    );
+  });
+
+  test('packageFrames always draws single-repo package frames when multi-member', () => {
+    const groups = buildBoundaryLayoutGroups(
+      {
+        components: [
+          { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+          { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        ],
+      },
+      { packageFrames: 'always' },
+    );
+    expect(groups.filter((g) => g.region.kind === 'package')).toHaveLength(1);
+  });
+
   test('subsystemGraphLayoutKey ignores declarationRef-only changes', () => {
     const base = doc;
     const withRef = {

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,
+      ];
     }
   }