@principal-ai/subsystems-react 0.21.0 → 0.22.0

package/src/subsystem/model.ts

@@ -32,7 +32,6 @@ export type SubsystemComponentConstruct =
   | 'interface'
   | 'type_alias'
   | 'enum'
-  | 'module'
   | 'store'
   | 'external'
   | 'custom_entity';
@@ -92,9 +91,6 @@ export interface SubsystemDeclToken {
  */
 export type SubsystemRelationType =
   | 'imports'
-  | 'imports_from'
-  | 're_exports'
-  | 'defines'
   | 'extends'
   | 'inherits'
   | 'implements'
@@ -190,11 +186,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;
   /**
@@ -354,26 +360,20 @@ 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: string | undefined,
   construct: SubsystemComponentConstruct,
   existingName?: string,
-  file?: string,
+  _file?: string,
   stereotype?: string,
 ): string {
   let name: string | undefined;
   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';
 
@@ -382,7 +382,7 @@ export function deriveNameFromSymbol(
   // 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}>`;
   }
@@ -431,11 +431,13 @@ export 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;
@@ -448,9 +450,21 @@ export function processGroupNodeId(processKey: string): string {
   return `process:${processKey}`;
 }
 
+/** React Flow id for a module boundary group node. */
+export function moduleGroupNodeId(moduleKey: string): string {
+  return `module:${moduleKey}`;
+}
+
+/** React Flow id for a boundary group of either kind. */
+export function boundaryGroupNodeId(region: Pick<SubsystemProcessRegion, 'kind' | 'key'>): string {
+  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: Pick<SubsystemModelDocument, 'components'>,
@@ -464,12 +478,100 @@ export function getSubsystemRegions(
     byProcess.set(p, list);
   }
   return [...byProcess.entries()].map(([key, memberIds]) => ({
+    kind: 'process' as const,
     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: Pick<SubsystemModelDocument, 'components'>,
+): SubsystemProcessRegion[] {
+  const byModule = new Map<string, string[]>();
+  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' as const,
+    key,
+    label: key,
+    memberIds,
+  }));
+}
+
+/**
+ * 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 function buildBoundaryLayoutGroups(
+  doc: Pick<SubsystemModelDocument, 'components'>,
+): BoundaryLayoutGroup[] {
+  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: BoundaryLayoutGroup[] = modules.map((r) => {
+    const processesOfMembers = new Set<string>();
+    for (const id of r.memberIds) {
+      const p = byId.get(id)?.process?.trim();
+      if (p) processesOfMembers.add(p);
+    }
+    let parentId: string | undefined;
+    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: BoundaryLayoutGroup[] = 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 interface SubsystemGraphNodeData extends Record<string, unknown> {
   component: SubsystemComponent;
   /** Set while a file is open in the drawer: true if this node's component
@@ -509,9 +611,6 @@ export type SubsystemGraphEdge = Edge<SubsystemGraphEdgeData>;
 
 export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
   imports: '#0893d2', // blue
-  imports_from: '#5aa9e6', // light blue
-  re_exports: '#3aa5c9', // cyan-blue
-  defines: '#2e86ab', // steel blue
   calls: '#4ec9b0', // teal
   extends: '#b48ead', // purple
   inherits: '#9b6fd0', // purple
@@ -531,9 +630,6 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
 
 export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed' | 'dotted'> = {
   imports: 'solid',
-  imports_from: 'solid',
-  re_exports: 'solid',
-  defines: 'solid',
   calls: 'solid',
   extends: 'dashed',
   inherits: 'dashed',
@@ -555,9 +651,6 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
  *  directly verifiable" styling of edge labels. */
 export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][] = [
   ['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],
@@ -566,7 +659,7 @@ export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][]
   ['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],
@@ -750,23 +843,23 @@ 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: SubsystemModelDocument,
   opts: { maxNodeWidth?: number } = {},
 ): SubsystemGraphNode[] {
   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<string, SubsystemComponent[]>();
   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);
@@ -801,11 +894,17 @@ 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 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,
@@ -818,20 +917,21 @@ export function convertSubsystemToNodes(
 }
 
 /**
- * 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: Pick<SubsystemModelDocument, 'components'>,
 ): SubsystemGraphNode[] {
-  return getSubsystemRegions(doc).map((region) => ({
-    id: processGroupNodeId(region.key),
-    type: 'subsystem-group',
+  return buildBoundaryLayoutGroups(doc).map((g) => ({
+    id: g.id,
+    type: 'subsystem-group' as const,
     position: { x: 0, y: 0 },
     width: 400,
     height: 300,
-    data: { region },
+    ...(g.parentId ? { parentId: g.parentId } : {}),
+    data: { region: g.region },
   }));
 }
 
@@ -874,8 +974,8 @@ export function subsystemGraphLayoutKey(
   doc: Pick<SubsystemModelDocument, 'components' | 'relations' | 'walkthroughs'>,
 ): string {
   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)
@@ -901,15 +1001,25 @@ export async function buildSubsystemGraph(
   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 as SubsystemGraphNodeData).component?.process?.trim();
-    if (proc && !regionKeys.has(proc)) {
+    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();
+    const processId = processKey ? processGroupNodeId(processKey) : undefined;
+    if (processId && regionIds.has(processId)) {
+      (n as { parentId?: string }).parentId = processId;
+    } else {
       delete (n as { parentId?: string }).parentId;
     }
   }
@@ -961,8 +1071,7 @@ export async function buildSubsystemGraph(
     }
   }
 
-  // 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<string, { x: number; y: number }>();
   let elkPathStrings = new Map<string, string>();
@@ -978,32 +1087,69 @@ 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,
+        groups: layoutGroups.map((g) => ({
+          id: g.id,
+          memberIds: g.memberIds,
+          parentId: g.parentId,
         })),
       });
-      const groupNodes: SubsystemGraphNode[] = regions.flatMap((region) => {
-        const bounds = result.groupBounds.get(processGroupNodeId(region.key));
-        if (!bounds) return [];
+      const builtGroupIds = new Set(result.groupBounds.keys());
+      // Parents before children — process frames, then nested module frames.
+      const processGroupNodes: SubsystemGraphNode[] = [];
+      const moduleGroupNodes: SubsystemGraphNode[] = [];
+      for (const g of layoutGroups) {
+        const bounds = result.groupBounds.get(g.id);
+        if (!bounds) continue;
+        const parentId =
+          g.parentId && builtGroupIds.has(g.parentId) ? g.parentId : undefined;
         const group: SubsystemGraphNode = {
-          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 as SubsystemGraphNode[])];
+        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 as SubsystemGraphNode[]) {
+        if (n.type !== 'subsystem-component') continue;
+        const parentId = (n as { parentId?: string }).parentId;
+        if (parentId && !builtGroupIds.has(parentId)) {
+          delete (n as { parentId?: string }).parentId;
+        }
+      }
+      placedNodes = [
+        ...processGroupNodes,
+        ...moduleGroupNodes,
+        ...(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.
+      // 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: SubsystemGraphNode[] = [];
+      const moduleGroupNodes: SubsystemGraphNode[] = [];
+      for (const g of layoutGroups) {
+        const group: SubsystemGraphNode = {
+          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];
     }
   }
 

package/src/subsystem/nodes.tsx

@@ -43,7 +43,6 @@ export const CONSTRUCT_LABEL: Record<string, string> = {
   interface: 'interface',
   type_alias: 'type alias',
   enum: 'enum',
-  module: 'module',
   store: 'store',
   external: 'external',
   custom_entity: 'entity',
@@ -326,10 +325,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
 }
 
 /**
- * Process boundary frame — a React Flow parent node. Members render inside
- * via `parentId`; this draws the labeled container only (no handles, no
- * selection). The border color derives deterministically from the process key
- * so each deployment unit reads as its own region.
+ * Boundary frame — a React Flow parent node for a process or module region.
+ * Members render inside via `parentId`; this draws the labeled container only
+ * (no handles, no selection). Border color derives from the region key.
  */
 export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData, 'subsystem-group'>>) {
   const { theme } = useTheme();
@@ -343,6 +341,8 @@ 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 ?? '');
 
   if (!region) return null;
 
@@ -378,7 +378,7 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           whiteSpace: 'nowrap',
         }}
       >
-        {region.label}
+        {label}
       </div>
     </div>
   );