@principal-ai/subsystems-react 0.43.0 → 0.43.1

package/src/subsystem/model.test.ts

@@ -22,7 +22,9 @@ import {
   boundaryMinWidthForBadge,
   MODULE_BADGE_INSET,
   packageGroupNodeId,
+  directoryGroupNodeId,
   buildBoundaryLayoutGroups,
+  buildBoundaryLayoutGroupsByPath,
   buildSubsystemGraph,
   componentPackageKey,
   deriveNameFromSymbol,
@@ -851,6 +853,122 @@ describe('isConstructsOnlyModel', () => {
       }),
     ).toBe(false);
   });
+
+  test('false when module/process containment frames exist, even with no edges', () => {
+    expect(
+      isConstructsOnlyModel({
+        components: [
+          { alias: 'a', module: 'src/a.ts' },
+          { alias: 'b', module: 'src/b.ts' },
+        ],
+      }),
+    ).toBe(false);
+    expect(
+      isConstructsOnlyModel({
+        components: [{ alias: 'a', process: 'app/server' }],
+      }),
+    ).toBe(false);
+    // Blank/whitespace membership is not a frame.
+    expect(
+      isConstructsOnlyModel({ components: [{ alias: 'a', module: '  ' }] }),
+    ).toBe(true);
+  });
+});
+
+describe('buildBoundaryLayoutGroupsByPath', () => {
+  const pathComps: SubsystemComponent[] = [
+    { alias: 'record', name: 'record', construct: 'type_alias', file: 'src/session/transcript.ts', module: 'src/session/transcript.ts', purl: 'pkg:github/p/app' },
+    { alias: 'parse', name: 'parse', construct: 'function', file: 'src/session/transcript.ts', module: 'src/session/transcript.ts', purl: 'pkg:github/p/app' },
+    { alias: 'tool-name', name: 'toolName', construct: 'function', file: 'src/session/paths.ts', module: 'src/session/paths.ts', purl: 'pkg:github/p/app' },
+    { alias: 'boot', name: 'boot', construct: 'function', file: 'src/host/main.ts', module: 'src/host/main.ts', purl: 'pkg:github/p/app' },
+    { alias: 'store', name: 'store', construct: 'store', file: 'src/host/store.ts', module: 'src/host/store.ts', purl: 'pkg:github/p/app' },
+  ];
+
+  test('derives directory frames and nests modules under them', () => {
+    const groups = buildBoundaryLayoutGroupsByPath(
+      { components: pathComps },
+      { showSingletonFrames: true },
+    );
+    const byId = new Map(groups.map((g) => [g.id, g]));
+
+    expect(byId.has(directoryGroupNodeId('src'))).toBe(true);
+    expect(byId.has(directoryGroupNodeId('src/session'))).toBe(true);
+    expect(byId.has(directoryGroupNodeId('src/host'))).toBe(true);
+
+    // directory → directory nesting
+    expect(byId.get(directoryGroupNodeId('src/session'))?.parentId).toBe(
+      directoryGroupNodeId('src'),
+    );
+    // module → directory nesting
+    expect(byId.get(moduleGroupNodeId('src/session/transcript.ts'))?.parentId).toBe(
+      directoryGroupNodeId('src/session'),
+    );
+    // top directory has no frame above it
+    expect(byId.get(directoryGroupNodeId('src'))?.parentId).toBeUndefined();
+
+    // Labels are relative to the parent frame, not the full path.
+    expect(byId.get(directoryGroupNodeId('src'))?.region.label).toBe('src');
+    expect(byId.get(directoryGroupNodeId('src/session'))?.region.label).toBe('session');
+    expect(byId.get(moduleGroupNodeId('src/session/transcript.ts'))?.region.label).toBe(
+      'transcript.ts',
+    );
+  });
+
+  test('each leaf is claimed by exactly one group (no compound duplicates)', () => {
+    const groups = buildBoundaryLayoutGroupsByPath(
+      { components: pathComps },
+      { showSingletonFrames: true },
+    );
+    const groupIds = new Set(groups.map((g) => g.id));
+    const leafCount = new Map<string, number>();
+    for (const g of groups) {
+      for (const m of g.memberAliases) {
+        // group ids are allowed to repeat (as child references); leaves must not
+        if (groupIds.has(m)) continue;
+        leafCount.set(m, (leafCount.get(m) ?? 0) + 1);
+      }
+    }
+    for (const [alias, n] of leafCount) {
+      expect(n, `${alias} claimed ${n} times`).toBe(1);
+    }
+  });
+
+  test('compacts single-child directory chains (app → app/book)', () => {
+    const comps: SubsystemComponent[] = [
+      { alias: 'page', name: 'page', construct: 'function', file: 'app/book/page.tsx', module: 'app/book/page.tsx', purl: 'pkg:github/p/app' },
+      { alias: 'actions', name: 'actions', construct: 'function', file: 'app/book/actions.ts', module: 'app/book/actions.ts', purl: 'pkg:github/p/app' },
+      { alias: 'lib-a', name: 'a', construct: 'function', file: 'lib/a.ts', module: 'lib/a.ts', purl: 'pkg:github/p/app' },
+      { alias: 'lib-b', name: 'b', construct: 'function', file: 'lib/b.ts', module: 'lib/b.ts', purl: 'pkg:github/p/app' },
+    ];
+    const groups = buildBoundaryLayoutGroupsByPath(
+      { components: comps },
+      { showSingletonFrames: true },
+    );
+    const ids = new Set(groups.map((g) => g.id));
+    // `app` has a single child dir and no direct files → merged into `app/book`.
+    expect(ids.has(directoryGroupNodeId('app'))).toBe(false);
+    expect(ids.has(directoryGroupNodeId('app/book'))).toBe(true);
+    const appBook = groups.find((g) => g.id === directoryGroupNodeId('app/book'))!;
+    expect(appBook.parentId).toBeUndefined();
+    expect(appBook.region.label).toBe('app/book');
+    expect(ids.has(directoryGroupNodeId('lib'))).toBe(true);
+  });
+
+  test('exact mode adds no directory frames', () => {
+    const groups = buildBoundaryLayoutGroups(
+      { components: pathComps },
+      { showSingletonFrames: true, moduleNesting: 'exact' },
+    );
+    expect(groups.some((g) => g.region.kind === 'directory')).toBe(false);
+  });
+
+  test('path mode is selected by the moduleNesting option', () => {
+    const groups = buildBoundaryLayoutGroups(
+      { components: pathComps },
+      { showSingletonFrames: true, moduleNesting: 'path' },
+    );
+    expect(groups.some((g) => g.region.kind === 'directory')).toBe(true);
+  });
 });
 
 describe('describeConstructBreakdown', () => {

package/src/subsystem/model.ts

@@ -477,15 +477,23 @@ export function deriveGraphEdges(doc: {
 }
 
 /**
- * True when the model has components but no walkthrough or graphify edges.
- * Those snapshots are a catalog of declarations, not a graph.
+ * True when the model has components but no graph structure at all: no
+ * walkthrough/graphify edges AND no boundary containment (`module` / `process`)
+ * to frame. Those snapshots are a catalog of declarations, not a graph.
+ *
+ * A model that carries `module` / `process` membership still draws frames even
+ * with zero edges — that is static topology, so it is not constructs-only.
  */
 export function isConstructsOnlyModel(doc: {
-  components: readonly { alias: string }[];
+  components: readonly { alias: string; module?: string; process?: string }[];
   walkthroughs?: readonly SubsystemWalkthrough[];
   graphifyRelations?: readonly SubsystemGraphifyRelation[];
 }): boolean {
   if (doc.components.length === 0) return false;
+  const hasBoundary = doc.components.some(
+    (c) => (c.module?.trim() ?? '') !== '' || (c.process?.trim() ?? '') !== '',
+  );
+  if (hasBoundary) return false;
   return deriveGraphEdges({
     walkthroughs: doc.walkthroughs,
     graphifyRelations: doc.graphifyRelations,
@@ -608,7 +616,7 @@ export type SubsystemGraphNodeType = 'subsystem-component' | 'subsystem-group';
  */
 export interface SubsystemProcessRegion {
   /** Discriminator — which field / identity produced this region. */
-  kind: 'process' | 'module' | 'package';
+  kind: 'process' | 'module' | 'directory' | 'package';
   /** The `process` / `module` value, or purl repo key for packages. */
   key: string;
   /** Display label for the boundary frame. */
@@ -631,6 +639,15 @@ export interface BoundaryFrameOptions {
    * - `never`: no package frames
    */
   packageFrames?: 'multi-repo' | 'always' | 'never';
+  /**
+   * How module frames group.
+   * - `exact` (default): one frame per distinct `module` string.
+   * - `path`: derive directory frames from the path segments of each
+   *   component's `module`, and nest module frames under the directories that
+   *   contain them. Directory frames are interposed between process/package
+   *   and module frames.
+   */
+  moduleNesting?: 'exact' | 'path';
 }
 
 /** React Flow id for a process boundary group node. */
@@ -643,6 +660,23 @@ export function moduleGroupNodeId(moduleKey: string): string {
   return `module:${moduleKey}`;
 }
 
+/** React Flow id for a directory boundary group node (path-derived nesting). */
+export function directoryGroupNodeId(dirKey: string): string {
+  return `directory:${dirKey}`;
+}
+
+/** Normalize a module path to forward slashes, no trailing slash or `./`. */
+function normalizeModulePath(p: string): string {
+  return p.trim().replace(/\\/g, '/').replace(/\/+$/, '').replace(/^\.\//, '');
+}
+
+/** Parent directory of a path-like key, or `''` when it has no slash. */
+function parentDirectory(path: string): string {
+  const norm = normalizeModulePath(path);
+  const idx = norm.lastIndexOf('/');
+  return idx <= 0 ? '' : norm.slice(0, idx);
+}
+
 export const MODULE_BADGE_INSET = 12;
 const MODULE_BADGE_CHAR_WIDTH = 12.5;
 const MODULE_BADGE_CHROME = 16;
@@ -718,6 +752,7 @@ export function packageGroupNodeId(packageKey: string): string {
 /** React Flow id for a boundary group of any kind. */
 export function boundaryGroupNodeId(region: Pick<SubsystemProcessRegion, 'kind' | 'key'>): string {
   if (region.kind === 'module') return moduleGroupNodeId(region.key);
+  if (region.kind === 'directory') return directoryGroupNodeId(region.key);
   if (region.kind === 'package') return packageGroupNodeId(region.key);
   return processGroupNodeId(region.key);
 }
@@ -840,6 +875,9 @@ export function buildBoundaryLayoutGroups(
   doc: Pick<SubsystemModelDocument, 'components'>,
   opts: BoundaryFrameOptions = {},
 ): BoundaryLayoutGroup[] {
+  if (opts.moduleNesting === 'path') {
+    return buildBoundaryLayoutGroupsByPath(doc, opts);
+  }
   const showSingletons = opts.showSingletonFrames === true;
   const packageMode = opts.packageFrames ?? 'multi-repo';
   const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
@@ -983,6 +1021,261 @@ export function buildBoundaryLayoutGroups(
   return [...moduleGroups, ...processGroups, ...packageGroups];
 }
 
+/**
+ * Path-nesting variant of {@link buildBoundaryLayoutGroups}.
+ *
+ * Adds directory frames derived from each component's `module` path segments
+ * (`src/session/transcript.ts` → `src` → `src/session` → module frame) and
+ * nests module frames under the deepest directory that contains them. Directory
+ * frames are kept when they hold 2+ leaves (or `showSingletonFrames`). Process
+ * and package frames nest above directories exactly as before.
+ *
+ * Module frames are unchanged (one per exact `module` string); leaves still
+ * parent to their module frame in `convertSubsystemToNodes`.
+ */
+export function buildBoundaryLayoutGroupsByPath(
+  doc: Pick<SubsystemModelDocument, 'components'>,
+  opts: BoundaryFrameOptions = {},
+): BoundaryLayoutGroup[] {
+  const showSingletons = opts.showSingletonFrames === true;
+  const packageMode = opts.packageFrames ?? 'multi-repo';
+  const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
+
+  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 processes = getSubsystemRegions(doc).filter((r) =>
+    keepRegion(r, showSingletons),
+  );
+  const keptProcessKeys = new Set(processes.map((r) => r.key));
+
+  const modules = getSubsystemModuleRegions(doc).filter((r) =>
+    keepRegion(r, showSingletons),
+  );
+
+  // Directory regions: every ancestor directory of a component's module path,
+  // with the union of all aliases beneath it.
+  const dirMembers = new Map<string, Set<string>>();
+  for (const c of doc.components) {
+    const m = c.module?.trim();
+    if (!m) continue;
+    let d = parentDirectory(m);
+    while (d) {
+      const set = dirMembers.get(d) ?? new Set<string>();
+      set.add(c.alias);
+      dirMembers.set(d, set);
+      d = parentDirectory(d);
+    }
+  }
+  const keptDirKeys = new Set<string>();
+  for (const [d, members] of dirMembers) {
+    if (members.size >= 2 || showSingletons) keptDirKeys.add(d);
+  }
+
+  // Files sitting directly in each directory (drives chain compaction below).
+  const directFileCount = new Map<string, number>();
+  for (const c of doc.components) {
+    const m = c.module?.trim();
+    if (!m) continue;
+    const d = parentDirectory(m);
+    if (d) directFileCount.set(d, (directFileCount.get(d) ?? 0) + 1);
+  }
+  // Compact single-child directory chains, mirroring the file tree: a directory
+  // whose only child is a single subdirectory (and which holds no files
+  // directly) is merged into it. `app` → `app/book` renders one `app/book`
+  // frame, not `app` wrapping `book`.
+  let compacting = true;
+  while (compacting) {
+    compacting = false;
+    const childDirsOf = new Map<string, string[]>();
+    for (const d of keptDirKeys) {
+      let a = parentDirectory(d);
+      while (a && !keptDirKeys.has(a)) a = parentDirectory(a);
+      if (!a) continue;
+      const list = childDirsOf.get(a) ?? [];
+      list.push(d);
+      childDirsOf.set(a, list);
+    }
+    for (const d of [...keptDirKeys]) {
+      const childDirs = childDirsOf.get(d) ?? [];
+      if (childDirs.length === 1 && (directFileCount.get(d) ?? 0) === 0) {
+        keptDirKeys.delete(d);
+        compacting = true;
+      }
+    }
+  }
+
+  const nearestKeptDirAncestor = (dirKey: string): string | undefined => {
+    let p = parentDirectory(dirKey);
+    while (p) {
+      if (keptDirKeys.has(p)) return p;
+      p = parentDirectory(p);
+    }
+    return undefined;
+  };
+  const dirRegions: SubsystemProcessRegion[] = [...keptDirKeys]
+    .sort()
+    .map((key) => {
+      // Label is the path relative to the enclosing kept directory (which
+      // already carries the prefix): `book` under `app`, or the full collapsed
+      // path `app/book` when the chain was compacted.
+      const ancestor = nearestKeptDirAncestor(key);
+      return {
+        kind: 'directory' as const,
+        key,
+        label: ancestor ? key.slice(ancestor.length + 1) : key,
+        memberAliases: [...(dirMembers.get(key) ?? [])],
+      };
+    });
+  const moduleDirParent = (moduleKey: string): string | undefined => {
+    let d = parentDirectory(moduleKey);
+    while (d) {
+      if (keptDirKeys.has(d)) return d;
+      d = parentDirectory(d);
+    }
+    return undefined;
+  };
+
+  const sharedProcessParent = (
+    memberAliases: readonly string[],
+  ): string | undefined => {
+    const seen = new Set<string>();
+    for (const alias of memberAliases) {
+      const p = byAlias.get(alias)?.process?.trim();
+      if (p) seen.add(p);
+    }
+    if (seen.size !== 1) return undefined;
+    const p = [...seen][0]!;
+    return keptProcessKeys.has(p) ? processGroupNodeId(p) : undefined;
+  };
+  const sharedPackageParent = (
+    memberAliases: readonly string[],
+  ): string | undefined => {
+    const seen = new Set<string>();
+    for (const alias of memberAliases) {
+      const c = byAlias.get(alias);
+      const pkg = c ? componentPackageKey(c) : undefined;
+      if (pkg) seen.add(pkg);
+    }
+    if (seen.size !== 1) return undefined;
+    const pkg = [...seen][0]!;
+    return keptPackageKeys.has(pkg) ? packageGroupNodeId(pkg) : undefined;
+  };
+  const frameParent = (memberAliases: readonly string[]): string | undefined =>
+    sharedProcessParent(memberAliases) ?? sharedPackageParent(memberAliases);
+
+  const moduleGroups: BoundaryLayoutGroup[] = modules.map((r) => {
+    const dirParent = moduleDirParent(r.key);
+    const parentId = dirParent
+      ? directoryGroupNodeId(dirParent)
+      : frameParent(r.memberAliases);
+    // Relative label when nested: `app/book/actions.ts` under `app/book`
+    // reads as `actions.ts`. At the root the full module path stays.
+    const label = dirParent ? r.key.slice(dirParent.length + 1) : r.label;
+    return {
+      id: moduleGroupNodeId(r.key),
+      memberAliases: [...r.memberAliases],
+      parentId,
+      region: { ...r, label },
+    };
+  });
+
+  const dirGroupByKey = new Map(dirRegions.map((r) => [r.key, r]));
+  const moduleRegionByKey = new Map(modules.map((r) => [r.key, r]));
+  const dirGroups: BoundaryLayoutGroup[] = dirRegions.map((r) => {
+    const id = directoryGroupNodeId(r.key);
+    const ancestor = nearestKeptDirAncestor(r.key);
+    const parentId = ancestor
+      ? directoryGroupNodeId(ancestor)
+      : frameParent(r.memberAliases);
+    // Immediate children: subdirectories and module frames parented here.
+    // Only child *group ids* go in the layout member list — a group's
+    // descendant leaves belong to its child groups alone, or ELK sees the
+    // same leaf in two compound parents and rejects the layout.
+    const childDirKeys = dirRegions
+      .filter((d) => nearestKeptDirAncestor(d.key) === r.key)
+      .map((d) => d.key);
+    const childModuleKeys = modules
+      .filter((m) => moduleDirParent(m.key) === r.key)
+      .map((m) => m.key);
+    const claimed = new Set<string>();
+    for (const dk of childDirKeys) {
+      for (const a of dirGroupByKey.get(dk)?.memberAliases ?? []) claimed.add(a);
+    }
+    for (const mk of childModuleKeys) {
+      for (const a of moduleRegionByKey.get(mk)?.memberAliases ?? []) claimed.add(a);
+    }
+    const directLeaves = r.memberAliases.filter((a) => !claimed.has(a));
+    return {
+      id,
+      memberAliases: [
+        ...childDirKeys.map(directoryGroupNodeId),
+        ...childModuleKeys.map(moduleGroupNodeId),
+        ...directLeaves,
+      ],
+      parentId,
+      region: r,
+    };
+  });
+
+  const frameGroups = [...dirGroups, ...moduleGroups];
+
+  // Aliases owned by a module frame (singleton or not) must not become direct
+  // leaves of an enclosing process/package frame.
+  const moduleMemberAliases = new Set<string>();
+  for (const r of modules) for (const a of r.memberAliases) moduleMemberAliases.add(a);
+
+  const processGroups: BoundaryLayoutGroup[] = processes.map((r) => {
+    const processId = processGroupNodeId(r.key);
+    const nested = frameGroups.filter((g) => g.parentId === processId);
+    const claimed = new Set<string>();
+    for (const g of nested) for (const a of g.region.memberAliases) claimed.add(a);
+    const directLeaves = r.memberAliases.filter(
+      (alias) => !claimed.has(alias) && !moduleMemberAliases.has(alias),
+    );
+    return {
+      id: processId,
+      memberAliases: [...nested.map((g) => g.id), ...directLeaves],
+      parentId: sharedPackageParent(r.memberAliases),
+      region: r,
+    };
+  });
+
+  const processMemberAliases = new Set<string>();
+  for (const r of processes) for (const a of r.memberAliases) processMemberAliases.add(a);
+
+  const packageGroups: BoundaryLayoutGroup[] = packages.map((r) => {
+    const packageId = packageGroupNodeId(r.key);
+    const nested = [...processGroups, ...frameGroups].filter(
+      (g) => g.parentId === packageId,
+    );
+    const claimed = new Set<string>();
+    for (const g of nested) for (const a of g.region.memberAliases) claimed.add(a);
+    const directLeaves = r.memberAliases.filter(
+      (alias) =>
+        !claimed.has(alias) &&
+        !moduleMemberAliases.has(alias) &&
+        !processMemberAliases.has(alias),
+    );
+    return {
+      id: packageId,
+      memberAliases: [...nested.map((g) => g.id), ...directLeaves],
+      region: r,
+    };
+  });
+
+  return [...frameGroups, ...processGroups, ...packageGroups];
+}
+
 export interface SubsystemGraphNodeData extends Record<string, unknown> {
   component: SubsystemComponent;
   /** Set while a file is open in the drawer: true if this node's component
@@ -1294,6 +1587,30 @@ export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][]
   ['registers-into', 'registration pattern', false],
 ];
 
+/**
+ * Single border/badge color for directory (folder) frames. Folders read as one
+ * kind of container, so they share a neutral hue rather than hashing per-path
+ * like modules / processes / packages. Host `boundaryColors` still overrides.
+ */
+export const FOLDER_FRAME_COLOR = '#7aa2d4';
+
+/**
+ * True when a boundary frame names a folder. `directory` frames always are.
+ * A `module` frame is a folder when its key looks like a directory path — the
+ * last segment has no file extension (the model has no explicit file/folder
+ * flag, so this is a heuristic; `Dockerfile`-style extensionless files read as
+ * folders).
+ */
+export function isFolderFrame(
+  region: { kind: string; key: string } | undefined,
+): boolean {
+  if (!region) return false;
+  if (region.kind === 'directory') return true;
+  if (region.kind !== 'module') return false;
+  const last = region.key.split('/').pop() ?? '';
+  return last !== '' && !last.includes('.');
+}
+
 /** Package color palette (derived deterministically from the package name). */
 export function packageColor(name: string): string {
   const palette = [
@@ -1709,10 +2026,15 @@ export async function buildSubsystemGraph(
     measuredHeights,
     showSingletonFrames,
     packageFrames,
+    moduleNesting,
     graphifyRelations,
     orderByLine = false,
   } = opts;
-  const frameOpts: BoundaryFrameOptions = { showSingletonFrames, packageFrames };
+  const frameOpts: BoundaryFrameOptions = {
+    showSingletonFrames,
+    packageFrames,
+    moduleNesting,
+  };
   const nodes = convertSubsystemToNodes(doc, { maxNodeWidth });
   const edges = convertSubsystemToEdges(doc, graphifyRelations);
   // Nested boundary tree: package → process → module → leaves.
@@ -1804,7 +2126,12 @@ export async function buildSubsystemGraph(
     try {
       const result = await computeElkLayout(nodes, edges, {
         routingStyle: 'orthogonal',
-        direction: 'RIGHT',
+        // Edge-driven graphs flow left-to-right. With no edges (pure
+        // containment, e.g. the static-topology layer) a RIGHT layout stacks
+        // disconnected top-level frames in one vertical column; DOWN makes the
+        // layered pass place those sibling frames along the horizontal axis
+        // while each frame's members stack vertically.
+        direction: edges.length > 0 ? 'RIGHT' : 'DOWN',
         nodeSpacing: 60,
         edgeSpacing: 30,
         edgeNodeSpacing: 60,
@@ -1825,7 +2152,7 @@ export async function buildSubsystemGraph(
           // room for the collapsed badge. Processes/packages never collapse:
           // size the frame to hold the full centered label plus padding.
           minWidth:
-            g.region.kind === 'module'
+            g.region.kind === 'module' || g.region.kind === 'directory'
               ? moduleMinWidthForBadge(g.region.label)
               : boundaryMinWidthForBadge(g.region.label),
         })),
@@ -1890,7 +2217,7 @@ export async function buildSubsystemGraph(
           position: { x: 0, y: 0 },
           width: Math.max(
             400,
-            g.region.kind === 'module'
+            g.region.kind === 'module' || g.region.kind === 'directory'
               ? moduleMinWidthForBadge(g.region.label)
               : boundaryMinWidthForBadge(g.region.label),
           ),

package/src/subsystem/nodes.tsx

@@ -33,6 +33,8 @@ import {
   moduleBadgeHoverLabel,
   moduleBadgeWidth,
   packageColor,
+  FOLDER_FRAME_COLOR,
+  isFolderFrame,
   type SubsystemGraphNodeData,
   type SubsystemGroupNodeData,
   type SubsystemGraphEdge,
@@ -445,8 +447,14 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
     selected?: boolean;
   };
   const region = data.region;
-  // Explicit host override wins over the derived (hash-based) frame color.
-  const color = data.color ?? packageColor(region?.key ?? 'process');
+  // Explicit host override wins over the derived frame color. Folder frames
+  // (directory, or a module whose key names a folder) share one neutral hue;
+  // everything else hashes per key.
+  const color =
+    data.color ??
+    (isFolderFrame(region ?? undefined)
+      ? FOLDER_FRAME_COLOR
+      : packageColor(region?.key ?? 'process'));
   const dimmed = data.dimmed === true;
   const hidden = (data as { hidden?: boolean }).hidden === true;
   // Label is the region identity alone (path / process key / owner/name).
@@ -454,7 +462,9 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
   // — don't prefix `module ·` / `package ·` or the path reads twice.
   const label = region?.label ?? '';
   const [expandedLabel, setExpandedLabel] = useState<string | null>(null);
-  const isModule = region?.kind === 'module';
+  // Directory frames (path-derived nesting) render like modules — dashed,
+  // collapsible path badge.
+  const isModule = region?.kind === 'module' || region?.kind === 'directory';
   const isProcess = region?.kind === 'process';
   const expanded = isModule && expandedLabel === label;
   const availableBadgeWidth = Math.max(0, (width ?? 400) - MODULE_BADGE_INSET * 2 - 4);

package/src/utils/elkLayout.ts

@@ -759,6 +759,16 @@ export async function computeElkLayout(
     if (parentId && builtGroups.has(parentId)) continue; // nested inside parent
     elkParents.push(node);
   }
+  // Order root-level compounds by model order (the caller's `groups` array), so
+  // disconnected sibling frames lay out deterministically — e.g. `app/book`
+  // before `lib`. Without this, planCompoundGroups' bottom-up build order
+  // decides placement.
+  const groupOrder = new Map(groupDefs.map((g, i) => [g.id, i]));
+  elkParents.sort(
+    (a, b) =>
+      (groupOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER) -
+      (groupOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER),
+  );
 
   // Create ELK graph
   const rootOptions = getElkOptions(options);