@principal-ai/subsystems-react 0.21.1 → 0.22.0

package/dist/subsystem/model.d.ts

@@ -17,7 +17,7 @@ import type { SubsystemDeclarationRef } from './declarationRef';
 /** Structured declaration shape — same union as graphify drill-down payloads. */
 export type SubsystemConstructDeclaration = GraphifyComponentDetail;
 export type SubsystemDeclarationProvenance = 'verified' | 'authored';
-export type SubsystemComponentConstruct = 'class' | 'function' | 'method' | 'interface' | 'type_alias' | 'enum' | 'module' | 'store' | 'external' | 'custom_entity';
+export type SubsystemComponentConstruct = 'class' | 'function' | 'method' | 'interface' | 'type_alias' | 'enum' | 'store' | 'external' | 'custom_entity';
 /**
  * Semantic role — where the node sits in the topology, orthogonal to
  * `construct` (what it is). Roles have *inherited* anatomy: an entry renders
@@ -55,7 +55,7 @@ export interface SubsystemDeclToken {
  * Topology relation type — structural / module / type claims.
  * Belongs on `relations[]`, not on walkthrough hops.
  */
-export type SubsystemRelationType = 'imports' | 'imports_from' | 're_exports' | 'defines' | 'extends' | 'inherits' | 'implements' | 'mixes_in' | 'method' | 'references' | 'contains';
+export type SubsystemRelationType = 'imports' | 'extends' | 'inherits' | 'implements' | 'mixes_in' | 'method' | 'references' | 'contains';
 /**
  * Walkthrough hop mechanism — runtime seams with a `file:line` site.
  */
@@ -131,11 +131,21 @@ export interface SubsystemComponent {
     /**
      * Runtime process membership — which deployment unit this node is a
      * member of (e.g. `principal-studio/host`, `principal-studio/renderer`). Nodes
-     * sharing a `process` are drawn inside one boundary region (grouping is
-     * `process ?? purl`); nodes without one sit outside every boundary
-     * (external actors, services, libraries).
+     * sharing a `process` are drawn inside one boundary region; nodes without
+     * one sit outside every process boundary (external actors, services,
+     * libraries). Orthogonal to `module` (source-file frame).
      */
     process?: string;
+    /**
+     * Source-module membership — which file/module this export belongs to
+     * (e.g. `src/session/transcript.ts`). Nodes sharing a `module` are drawn
+     * inside one boundary frame. Prefer this over inventing a module construct:
+     * each export keeps its real construct (`function` / `class` / …) and the
+     * file reads as a frame. Orthogonal to `process` (runtime deployment).
+     * When both are set, the module frame is the component's parent (finer
+     * grain); process framing still groups siblings that share a process.
+     */
+    module?: string;
     /** A symbol this component exposes / is (the node's identity). */
     symbol?: string;
     /**
@@ -248,13 +258,11 @@ export declare function deriveGraphEdges(doc: {
  *
  * `symbol` is the source of truth (fully-qualified code identity). The name
  * is the symbol itself:
- *  - class/type/module/function/script/...  symbol → symbol (e.g. `SessionReader`)
- *  - method                               `Owner.method` → last segment (e.g. `SessionReader.normalize` → `normalize`)
- *  - module, no symbol → basename of `file` (e.g. `transcript.ts` → `transcript`) —
- *    a common-sense convention for whole-file modules, not a real TS name
- *  - otherwise                          no symbol → fall back to an existing name
+ *  - class/type/function/...  symbol → symbol (e.g. `SessionReader`)
+ *  - method                   `Owner.method` → last segment (e.g. `SessionReader.normalize` → `normalize`)
+ *  - otherwise                no symbol → fall back to an existing name
  */
-export declare function deriveNameFromSymbol(symbol: string | undefined, construct: SubsystemComponentConstruct, existingName?: string, file?: string, stereotype?: string): string;
+export declare function deriveNameFromSymbol(symbol: string | undefined, construct: SubsystemComponentConstruct, existingName?: string, _file?: string, stereotype?: string): string;
 /**
  * Human-readable purl identity — drops the `pkg:<type>/` scheme wrapper and
  * trailing version, keeping the package / owner-repo identity:
@@ -270,11 +278,13 @@ export declare function deriveNameFromSymbol(symbol: string | undefined, constru
 export declare function formatPurl(purl: string): string;
 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).
+ * One boundary region — either a process (runtime deployment unit) or a
+ * module (source file). Nodes without that field sit outside those frames.
  */
 export interface SubsystemProcessRegion {
-    /** The `process` value (e.g. `principal-studio/host`). */
+    /** Discriminator — which field produced this region. */
+    kind: 'process' | 'module';
+    /** The `process` or `module` value (e.g. `principal-studio/host`, `src/a.ts`). */
     key: string;
     /** Display label for the boundary frame. */
     label: string;
@@ -283,11 +293,38 @@ export interface SubsystemProcessRegion {
 }
 /** React Flow id for a process boundary group node. */
 export declare function processGroupNodeId(processKey: string): string;
+/** React Flow id for a module boundary group node. */
+export declare function moduleGroupNodeId(moduleKey: string): string;
+/** React Flow id for a boundary group of either kind. */
+export declare function boundaryGroupNodeId(region: Pick<SubsystemProcessRegion, 'kind' | 'key'>): string;
 /**
- * Derive boundary regions from a document — one per distinct non-empty
- * `process` value, in first-appearance order.
+ * Derive process boundary regions — one per distinct non-empty `process`
+ * value, in first-appearance order.
  */
 export declare function getSubsystemRegions(doc: Pick<SubsystemModelDocument, 'components'>): SubsystemProcessRegion[];
+/**
+ * Derive module boundary regions — one per distinct non-empty `module`
+ * value, in first-appearance order. Label is the module path (file).
+ */
+export declare function getSubsystemModuleRegions(doc: Pick<SubsystemModelDocument, 'components'>): SubsystemProcessRegion[];
+/**
+ * One compound frame for ELK / React Flow — module frames may nest under a
+ * process frame via `parentId`.
+ */
+export interface BoundaryLayoutGroup {
+    id: string;
+    memberIds: string[];
+    /** When set, this group is a child of another boundary group (process). */
+    parentId?: string;
+    region: SubsystemProcessRegion;
+}
+/**
+ * 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.
+ */
+export declare function buildBoundaryLayoutGroups(doc: Pick<SubsystemModelDocument, 'components'>): BoundaryLayoutGroup[];
 export interface SubsystemGraphNodeData extends Record<string, unknown> {
     component: SubsystemComponent;
     /** Set while a file is open in the drawer: true if this node's component
@@ -399,17 +436,19 @@ export declare function nodeMinWidthForBadges(component: {
 }): number;
 /**
  * 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.
+ * 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.
  */
 export declare function convertSubsystemToNodes(doc: SubsystemModelDocument, opts?: {
     maxNodeWidth?: number;
 }): SubsystemGraphNode[];
 /**
- * Convert boundary regions into React Flow parent (group) nodes. One per
- * distinct `process` value; member components point at these via `parentId`.
+ * Convert boundary regions into React Flow parent (group) nodes. Module
+ * frames that share a process nest under that process via `parentId`.
  * Positions/sizes are placeholders — ELK compound layout overwrites them.
  */
 export declare function convertSubsystemToGroups(doc: Pick<SubsystemModelDocument, 'components'>): SubsystemGraphNode[];

package/dist/subsystem/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/subsystem/model.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/subsystem/model.ts"],"names":[],"mappings":"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"}

package/dist/subsystem/model.js

@@ -59,23 +59,15 @@ export function deriveGraphEdges(doc) {
  *
  * `symbol` is the source of truth (fully-qualified code identity). The name
  * is the symbol itself:
- *  - class/type/module/function/script/...  symbol → symbol (e.g. `SessionReader`)
- *  - method                               `Owner.method` → last segment (e.g. `SessionReader.normalize` → `normalize`)
- *  - module, no symbol → basename of `file` (e.g. `transcript.ts` → `transcript`) —
- *    a common-sense convention for whole-file modules, not a real TS name
- *  - otherwise                          no symbol → fall back to an existing name
+ *  - class/type/function/...  symbol → symbol (e.g. `SessionReader`)
+ *  - method                   `Owner.method` → last segment (e.g. `SessionReader.normalize` → `normalize`)
+ *  - otherwise                no symbol → fall back to an existing name
  */
-export function deriveNameFromSymbol(symbol, construct, existingName, file, stereotype) {
+export function deriveNameFromSymbol(symbol, construct, existingName, _file, stereotype) {
     let name;
     if (symbol && symbol.trim()) {
         name = symbol;
     }
-    else if (construct === 'module' && file) {
-        const base = file.split('/').pop() ?? '';
-        const clean = base.replace(/\.[^.]+$/, ''); // strip extension
-        if (clean)
-            name = clean;
-    }
     if (!name)
         name = existingName ?? 'untitled';
     // Decorations = what the drill-down shows. Framework stereotypes can override
@@ -83,7 +75,7 @@ export function deriveNameFromSymbol(symbol, construct, existingName, file, ster
     // Executable constructs wear `()`; brace-bodied constructs (interface,
     // type_alias, enum) wear ` {}`. Classes render bare — the construct badge
     // already says "class".
-    // Everything else (class, store, module, external) renders bare.
+    // Everything else (class, store, external) renders bare.
     if (stereotype === 'component' && !name.startsWith('<')) {
         return `<${name}>`;
     }
@@ -127,9 +119,19 @@ export function formatPurl(purl) {
 export function processGroupNodeId(processKey) {
     return `process:${processKey}`;
 }
+/** React Flow id for a module boundary group node. */
+export function moduleGroupNodeId(moduleKey) {
+    return `module:${moduleKey}`;
+}
+/** React Flow id for a boundary group of either kind. */
+export function boundaryGroupNodeId(region) {
+    return region.kind === 'module'
+        ? moduleGroupNodeId(region.key)
+        : processGroupNodeId(region.key);
+}
 /**
- * Derive boundary regions from a document — one per distinct non-empty
- * `process` value, in first-appearance order.
+ * Derive process boundary regions — one per distinct non-empty `process`
+ * value, in first-appearance order.
  */
 export function getSubsystemRegions(doc) {
     const byProcess = new Map();
@@ -142,16 +144,84 @@ export function getSubsystemRegions(doc) {
         byProcess.set(p, list);
     }
     return [...byProcess.entries()].map(([key, memberIds]) => ({
+        kind: 'process',
         key,
         label: key,
         memberIds,
     }));
 }
+/**
+ * Derive module boundary regions — one per distinct non-empty `module`
+ * value, in first-appearance order. Label is the module path (file).
+ */
+export function getSubsystemModuleRegions(doc) {
+    const byModule = new Map();
+    for (const c of doc.components) {
+        const m = c.module?.trim();
+        if (!m)
+            continue;
+        const list = byModule.get(m) ?? [];
+        list.push(c.id);
+        byModule.set(m, list);
+    }
+    return [...byModule.entries()].map(([key, memberIds]) => ({
+        kind: 'module',
+        key,
+        label: key,
+        memberIds,
+    }));
+}
+/**
+ * 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.
+ */
+export function buildBoundaryLayoutGroups(doc) {
+    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 keptProcessKeys = new Set(processes.map((r) => r.key));
+    const moduleGroups = modules.map((r) => {
+        const processesOfMembers = new Set();
+        for (const id of r.memberIds) {
+            const p = byId.get(id)?.process?.trim();
+            if (p)
+                processesOfMembers.add(p);
+        }
+        let parentId;
+        if (processesOfMembers.size === 1) {
+            const p = [...processesOfMembers][0];
+            if (keptProcessKeys.has(p))
+                parentId = processGroupNodeId(p);
+        }
+        return {
+            id: moduleGroupNodeId(r.key),
+            memberIds: [...r.memberIds],
+            parentId,
+            region: r,
+        };
+    });
+    const processGroups = processes.map((r) => {
+        const processId = processGroupNodeId(r.key);
+        const nestedModules = moduleGroups.filter((m) => m.parentId === processId);
+        const nestedModuleKeys = new Set(nestedModules.map((m) => m.region.key));
+        const directLeaves = r.memberIds.filter((id) => {
+            const mod = byId.get(id)?.module?.trim();
+            if (!mod)
+                return true;
+            return !nestedModuleKeys.has(mod);
+        });
+        return {
+            id: processId,
+            memberIds: [...nestedModules.map((m) => m.id), ...directLeaves],
+            region: r,
+        };
+    });
+    return [...moduleGroups, ...processGroups];
+}
 export const MECHANISM_COLOR = {
     imports: '#0893d2',
-    imports_from: '#5aa9e6',
-    re_exports: '#3aa5c9',
-    defines: '#2e86ab',
     calls: '#4ec9b0',
     extends: '#b48ead',
     inherits: '#9b6fd0',
@@ -170,9 +240,6 @@ export const MECHANISM_COLOR = {
 };
 export const MECHANISM_STYLE = {
     imports: 'solid',
-    imports_from: 'solid',
-    re_exports: 'solid',
-    defines: 'solid',
     calls: 'solid',
     extends: 'dashed',
     inherits: 'dashed',
@@ -193,9 +260,6 @@ export const MECHANISM_STYLE = {
  *  directly verifiable" styling of edge labels. */
 export const MECHANISM_DESCRIPTIONS = [
     ['imports', 'import statement (code-level dependency)', true],
-    ['imports_from', 'imported by (reverse dependency)', true],
-    ['re_exports', 're-exports symbols from', true],
-    ['defines', 'defines / declares symbol', true],
     ['calls', 'function/method call (call graph edge)', true],
     ['extends', 'class inheritance', true],
     ['inherits', 'class inheritance', true],
@@ -204,7 +268,7 @@ export const MECHANISM_DESCRIPTIONS = [
     ['uses', 'general dependency (import, call, or reference)', false],
     ['method', 'structural: has method / member', true],
     ['references', 'type / symbol reference (not a call)', true],
-    ['contains', 'structural: contains / encapsulates', true],
+    ['contains', 'UI composition: shell/view owns a child surface', false],
     ['feeds', 'data flow: output feeds into input', false],
     ['produces', 'data flow: produces / outputs', false],
     ['writes', 'state access: mutates retained state', true],
@@ -349,20 +413,20 @@ export function nodeMinWidthForBadges(component) {
 }
 /**
  * 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.
+ * 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.
  */
 export function convertSubsystemToNodes(doc, opts = {}) {
     const { maxNodeWidth } = opts;
-    // Group components into boundary regions by process when authored, else by
-    // package. Process is runtime membership (drawn as one boundary region);
-    // purl is code identity — nodes without a process (external actors,
-    // services, libraries) fall back to purl and sit outside every boundary.
+    // Cluster for the pre-ELK grid: module (source file) → process (runtime)
+    // → purl (package identity).
     const byPkg = new Map();
     for (const c of doc.components) {
-        const regionKey = c.process ?? c.purl;
+        const regionKey = c.module ?? c.process ?? c.purl;
         const list = byPkg.get(regionKey) ?? [];
         list.push(c);
         byPkg.set(regionKey, list);
@@ -394,11 +458,17 @@ export function convertSubsystemToNodes(doc, opts = {}) {
             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 moduleKey = c.module?.trim();
             const processKey = c.process?.trim();
+            const parentId = moduleKey
+                ? moduleGroupNodeId(moduleKey)
+                : processKey
+                    ? processGroupNodeId(processKey)
+                    : undefined;
             nodes.push({
                 id: c.id,
                 type: 'subsystem-component',
-                ...(processKey ? { parentId: processGroupNodeId(processKey) } : {}),
+                ...(parentId ? { parentId } : {}),
                 position: { x: PAD + col * COL_W, y: cursorY + row * ROW_H },
                 width: nodeWidth,
                 height: 84,
@@ -410,18 +480,19 @@ export function convertSubsystemToNodes(doc, opts = {}) {
     return nodes;
 }
 /**
- * Convert boundary regions into React Flow parent (group) nodes. One per
- * distinct `process` value; member components point at these via `parentId`.
+ * Convert boundary regions into React Flow parent (group) nodes. Module
+ * frames that share a process nest under that process via `parentId`.
  * Positions/sizes are placeholders — ELK compound layout overwrites them.
  */
 export function convertSubsystemToGroups(doc) {
-    return getSubsystemRegions(doc).map((region) => ({
-        id: processGroupNodeId(region.key),
+    return buildBoundaryLayoutGroups(doc).map((g) => ({
+        id: g.id,
         type: 'subsystem-group',
         position: { x: 0, y: 0 },
         width: 400,
         height: 300,
-        data: { region },
+        ...(g.parentId ? { parentId: g.parentId } : {}),
+        data: { region: g.region },
     }));
 }
 /**
@@ -458,7 +529,7 @@ export function convertSubsystemToEdges(doc) {
 /** Stable key for layout-affecting graph fields (ignores declarationRef, etc.). */
 export function subsystemGraphLayoutKey(doc) {
     const components = doc.components
-        .map(({ id, purl, name, symbol, construct, file, purpose, process }) => [id, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? ''].join('\0'))
+        .map(({ id, purl, name, symbol, construct, file, purpose, process, module }) => [id, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? '', module ?? ''].join('\0'))
         .sort()
         .join('\n');
     const edgeKey = deriveGraphEdges(doc)
@@ -476,16 +547,28 @@ export async function buildSubsystemGraph(doc, opts = {}) {
     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));
+    // Nested boundary tree: process → module → leaves (when both fields set).
+    const layoutGroups = buildBoundaryLayoutGroups(doc);
+    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.
     for (const n of nodes) {
         if (n.type !== 'subsystem-component')
             continue;
-        const proc = n.data.component?.process?.trim();
-        if (proc && !regionKeys.has(proc)) {
+        const parentId = n.parentId;
+        if (!parentId)
+            continue;
+        if (regionIds.has(parentId))
+            continue;
+        const comp = n.data.component;
+        const processKey = comp?.process?.trim() || byId.get(n.id)?.process?.trim();
+        const processId = processKey ? processGroupNodeId(processKey) : undefined;
+        if (processId && regionIds.has(processId)) {
+            n.parentId = processId;
+        }
+        else {
             delete n.parentId;
         }
     }
@@ -537,8 +620,7 @@ export async function buildSubsystemGraph(doc, opts = {}) {
                 n.height = mh;
         }
     }
-    // ELK auto-layout: position nodes (layered, minimized crossings) with
-    // process partitions as compound parents so boundaries shape the layout.
+    // ELK auto-layout: nested compound parents (process → module → leaves).
     let placedNodes = nodes;
     let labelPositions = new Map();
     let elkPathStrings = new Map();
@@ -554,34 +636,75 @@ export async function buildSubsystemGraph(doc, opts = {}) {
                 interLayerSpacing: 120,
                 preserveNodePositions: false,
                 edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
-                groups: regions.map((r) => ({
-                    id: processGroupNodeId(r.key),
-                    memberIds: r.memberIds,
+                groups: layoutGroups.map((g) => ({
+                    id: g.id,
+                    memberIds: g.memberIds,
+                    parentId: g.parentId,
                 })),
             });
-            const groupNodes = regions.flatMap((region) => {
-                const bounds = result.groupBounds.get(processGroupNodeId(region.key));
+            const builtGroupIds = new Set(result.groupBounds.keys());
+            // Parents before children — process frames, then nested module frames.
+            const processGroupNodes = [];
+            const moduleGroupNodes = [];
+            for (const g of layoutGroups) {
+                const bounds = result.groupBounds.get(g.id);
                 if (!bounds)
-                    return [];
+                    continue;
+                const parentId = g.parentId && builtGroupIds.has(g.parentId) ? g.parentId : undefined;
                 const group = {
-                    id: processGroupNodeId(region.key),
+                    id: g.id,
                     type: 'subsystem-group',
                     position: { x: bounds.x, y: bounds.y },
                     width: Math.max(200, bounds.width),
                     height: Math.max(160, bounds.height),
-                    data: { region },
+                    ...(parentId ? { parentId } : {}),
+                    data: { region: g.region },
                 };
-                return [group];
-            });
-            // Parents first — React Flow resolves children via parentId.
-            placedNodes = [...groupNodes, ...result.nodes];
+                if (g.region.kind === 'process')
+                    processGroupNodes.push(group);
+                else
+                    moduleGroupNodes.push(group);
+            }
+            // Clear leaf parentIds that point at groups ELK dropped.
+            for (const n of result.nodes) {
+                if (n.type !== 'subsystem-component')
+                    continue;
+                const parentId = n.parentId;
+                if (parentId && !builtGroupIds.has(parentId)) {
+                    delete n.parentId;
+                }
+            }
+            placedNodes = [
+                ...processGroupNodes,
+                ...moduleGroupNodes,
+                ...result.nodes,
+            ];
             labelPositions = result.edgeLabelPositions;
             elkPathStrings = result.edgePaths;
             elkPathPoints = result.edgePathPoints;
         }
         catch (err) {
-            // Fall back to the (unpositioned) grid if ELK is unavailable.
+            // 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 processGroupNodes = [];
+            const moduleGroupNodes = [];
+            for (const g of layoutGroups) {
+                const group = {
+                    id: g.id,
+                    type: 'subsystem-group',
+                    position: { x: 0, y: 0 },
+                    width: 400,
+                    height: 300,
+                    ...(g.parentId ? { parentId: g.parentId } : {}),
+                    data: { region: g.region },
+                };
+                if (g.region.kind === 'process')
+                    processGroupNodes.push(group);
+                else
+                    moduleGroupNodes.push(group);
+            }
+            placedNodes = [...processGroupNodes, ...moduleGroupNodes, ...nodes];
         }
     }
     // Stamp ELK-computed label midpoints onto edge data so the overlay can