@principal-ai/subsystems-react 0.35.6 → 0.36.0

package/src/subsystem/model.ts

@@ -824,6 +824,13 @@ export function buildBoundaryLayoutGroups(
   // ("value already present"). Mixed-process modules (common in composed
   // graphs, where models frame one file under different processes) never
   // nest — without this claim they land in both frames.
+  //
+  // Singletons deliberately do NOT claim, `showSingletonFrames` or not: a
+  // one-member process spans exactly one package and a one-member module
+  // sits in exactly one process, so each always nests, and the enclosing
+  // frame's own `claimed`/`nestedModuleKeys` filter already excludes the
+  // leaf. Claiming as well would only strip those leaves from a package's
+  // direct leaves for no gain.
   const claimedByModule = new Set<string>();
   for (const r of modules) {
     if (r.memberAliases.length >= 2) {
@@ -832,8 +839,7 @@ export function buildBoundaryLayoutGroups(
   }
   // Same rule one level up: a leaf owned by a multi-member process frame
   // must not also sit directly in a package frame. (Singleton processes
-  // never claim — ELK skips them and promotes the member upward, so the
-  // member has to stay reachable through its package or ungrouped.)
+  // never claim — see above.)
   const claimedByProcess = new Set<string>();
   for (const r of processes) {
     if (r.memberAliases.length >= 2) {
@@ -1046,6 +1052,87 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
   'registers-into': 'dashed',
 };
 
+/**
+ * Region colors for process boundaries in the aggregate graph. Kept separate
+ * from MECHANISM_COLOR on purpose: that palette encodes edge semantics on thin
+ * arrowed strokes, this one encodes containment on wide filled regions, and a
+ * shared hue would make the two readings ambiguous.
+ */
+export const BOUNDARY_COLOR: readonly string[] = [
+  '#6c9eff', // blue
+  '#3fb8a0', // teal
+  '#8fbf5f', // green
+  '#d9a441', // amber
+  '#d67ab1', // magenta
+  '#9d7fe0', // violet
+  '#e8705f', // coral
+  '#4fb0d4', // sky
+  '#c2a83c', // olive
+  '#a876c8', // orchid
+  '#d1487f', // crimson
+  '#a3c94f', // lime
+];
+
+/** Stable 32-bit hash (FNV-1a plus a final mix) so low bits still spread. */
+function hashBoundaryKey(key: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < key.length; i++) {
+    h ^= key.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  h ^= h >>> 15;
+  h = Math.imul(h, 0x2545f491);
+  h ^= h >>> 13;
+  return h >>> 0;
+}
+
+/**
+ * Assign each process boundary key a color from BOUNDARY_COLOR.
+ *
+ * A bare `hash % palette.length` collides constantly once a repo has more than
+ * a handful of processes — unrelated boundaries end up the same hue, which
+ * defeats the point of coding them at all. So the hash only picks the
+ * *preferred* slot and collisions probe forward to the next free one, with
+ * keys visited in sorted order to keep the result deterministic. Distinct
+ * boundaries therefore never share a color unless the key count exceeds the
+ * palette, and past that point the least-used hue wins rather than an
+ * arbitrary one, so the busiest boundaries keep unique colors longest.
+ *
+ * Assignment depends on the key set, so filtering the graph can reshuffle
+ * hues. That is the deliberate trade: the legend is always on screen, whereas
+ * a stable-but-colliding mapping is unreadable.
+ */
+export function assignBoundaryColors(keys: readonly string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const owners = new Map<string, number>();
+  for (const key of [...keys].sort()) {
+    if (out.has(key)) continue;
+    const start = hashBoundaryKey(key) % BOUNDARY_COLOR.length;
+    let picked: string | undefined;
+    for (let i = 0; i < BOUNDARY_COLOR.length; i++) {
+      const candidate = BOUNDARY_COLOR[(start + i) % BOUNDARY_COLOR.length]!;
+      if (owners.get(candidate)) continue;
+      picked = candidate;
+      break;
+    }
+    // Palette exhausted: share the least-used hue, ties going to the earlier
+    // slot so the result stays deterministic.
+    if (!picked) {
+      picked = BOUNDARY_COLOR.reduce((a, b) =>
+        (owners.get(a) ?? 0) <= (owners.get(b) ?? 0) ? a : b,
+      )!;
+    }
+    owners.set(picked, (owners.get(picked) ?? 0) + 1);
+    out.set(key, picked);
+  }
+  return out;
+}
+
+/** Low-alpha fill for a boundary region, from its assigned color. */
+export function boundaryFill(color: string, alpha = '1f'): string {
+  return `${color}${alpha}`;
+}
+
 /** Mechanism → [description, verifiable-with-graphify]. Drives the "not
  *  directly verifiable" styling of edge labels. */
 export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][] = [
@@ -1552,6 +1639,11 @@ export async function buildSubsystemGraph(
           parentId: g.parentId,
           minWidth: g.region.kind === 'module' ? moduleMinWidthForBadge(g.region.label) : undefined,
         })),
+        // Honour `showSingletonFrames`: a one-member process or module is
+        // still a real boundary. `buildBoundaryLayoutGroups` already made
+        // those regions claim their members, so keeping them here cannot
+        // double-parent a leaf.
+        keepSingletonGroups: showSingletonFrames === true,
       });
       const builtGroupIds = new Set(result.groupBounds.keys());
       // Parents before children — package, then process, then module frames.

package/src/subsystem/nodes.tsx

@@ -405,6 +405,7 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
     isModule && canToggle ? moduleBadgeHoverLabel(label, availableBadgeWidth) : label;
   const frameRadius = isProcess ? 0 : 12;
   const badgeRadius = isProcess ? 0 : 4;
+  const badgeBg = theme.colors.backgroundSecondary ?? theme.colors.background;
   // Processes are deployment units — solid frame. Modules/packages stay dashed
   // until selected.
   const frameStyle = isProcess || selected ? 'solid' : 'dashed';
@@ -455,12 +456,12 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           position: 'absolute',
           // Process: badge fill starts with the process fill (inside the
           // frame border); no top badge border so widths don't fight.
-          // Module/package sit astride the top edge like component badges.
-          // Always set left/transform/borderTop explicitly — React Flow reuses
+          // Module/package are centred astride the top edge like component
+          // badges. Always set left/transform explicitly — React Flow reuses
           // group DOM nodes and `undefined` does not clear a prior value.
-          top: isProcess ? 0 : -19,
+          top: 0,
           left: isProcess ? '50%' : 12,
-          transform: isProcess ? 'translateX(-50%)' : 'none',
+          transform: isProcess ? 'translateX(-50%)' : 'translateY(-50%)',
           zIndex: canToggle ? 10 : undefined,
           // Width is explicit while collapsible so hover-reveal of more path
           // text animates; the cap keeps both states inside the frame.
@@ -472,17 +473,19 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
               : undefined,
           transition: 'width 140ms ease, box-shadow 120ms ease',
           cursor: canToggle ? 'pointer' : undefined,
-          boxShadow: canToggle && hover ? `0 2px 10px ${color}55` : undefined,
+          // The trailing halo squares the rounded corners back off in the fill
+          // colour, so an edge crossing a corner can't show through the notch.
+          boxShadow: `${canToggle && hover ? `0 2px 10px ${color}55, ` : ''}0 0 0 1.5px ${badgeBg}`,
           fontFamily: theme.fonts.monospace,
           fontSize: theme.fontSizes[3],
           fontWeight: 700,
           letterSpacing: 0.6,
           color,
-          background: theme.colors.backgroundSecondary ?? theme.colors.background,
-          border: `1px solid ${color}`,
-          borderTopWidth: isProcess ? 0 : 1,
+          background: badgeBg,
+          border: `2px solid ${color}`,
+          borderTopWidth: isProcess ? 0 : 2,
           borderRadius: badgeRadius,
-          padding: '1px 7px',
+          padding: '3px 9px',
           whiteSpace: 'nowrap',
           overflow: 'hidden',
           textOverflow: 'ellipsis',

package/src/utils/elkLayout.test.ts

@@ -1,9 +1,10 @@
 /**
  * Tests for ELK Layout Utility
  *
- * Tests the pure helper functions that don't require the ELK runtime.
- * The computeElkLayout function is tested via Storybook visual tests
- * since ELK requires a web worker environment.
+ * Tests the pure helper functions that don't require the ELK runtime, plus
+ * the compound-group planner. computeElkLayout itself needs a web worker
+ * (elkjs constructs one), so it is covered by Storybook visual tests and by
+ * testing planCompoundGroups — the part that decides which frames exist.
  */
 
 import { describe, test, expect } from 'bun:test';
@@ -11,9 +12,122 @@ import {
   pointsToPath,
   pointsToSmoothPath,
   calculatePathMidpoint,
+  planCompoundGroups,
   type Point,
 } from './elkLayout';
 
+describe('planCompoundGroups', () => {
+  test('drops a single-leaf group by default and promotes its member', () => {
+    const plan = planCompoundGroups(
+      [{ id: 'proc', memberIds: ['solo'] }],
+      ['solo'],
+    );
+    expect(plan.built.map((g) => g.id)).toEqual([]);
+    expect(plan.skipped).toEqual(['proc']);
+  });
+
+  test('keeps a single-leaf group when the caller opts in', () => {
+    const plan = planCompoundGroups(
+      [{ id: 'proc', memberIds: ['solo'] }],
+      ['solo'],
+      true,
+    );
+    expect(plan.skipped).toEqual([]);
+    expect(plan.built).toEqual([{ id: 'proc', childIds: ['solo'], minWidth: undefined }]);
+  });
+
+  test('keeps a multi-leaf group in both modes', () => {
+    const defs = [{ id: 'proc', memberIds: ['a', 'b'] }];
+    for (const keep of [false, true]) {
+      const plan = planCompoundGroups(defs, ['a', 'b'], keep);
+      expect(plan.built.map((g) => g.id)).toEqual(['proc']);
+      expect(plan.skipped).toEqual([]);
+    }
+  });
+
+  test('always drops an empty group even when singletons are kept', () => {
+    const plan = planCompoundGroups([{ id: 'proc', memberIds: [] }], ['a'], true);
+    expect(plan.built).toEqual([]);
+    expect(plan.skipped).toEqual(['proc']);
+  });
+
+  test('counts leaves through nested groups', () => {
+    // process → module(one leaf) is still a single leaf, so both drop by
+    // default even though the process lists one member id.
+    const defs = [
+      { id: 'mod', memberIds: ['a'] },
+      { id: 'proc', memberIds: ['mod'] },
+    ];
+    expect(planCompoundGroups(defs, ['a']).skipped).toEqual(['mod', 'proc']);
+    expect(planCompoundGroups(defs, ['a'], true).built.map((g) => g.id)).toEqual([
+      'mod',
+      'proc',
+    ]);
+  });
+
+  test('a two-leaf module keeps its process alive under the default', () => {
+    const defs = [
+      { id: 'mod', memberIds: ['a', 'b'] },
+      { id: 'proc', memberIds: ['mod'] },
+    ];
+    const plan = planCompoundGroups(defs, ['a', 'b']);
+    expect(plan.built.map((g) => g.id)).toEqual(['mod', 'proc']);
+    expect(plan.built[1]!.childIds).toEqual(['mod']);
+  });
+
+  test('promotes a dropped group member into its built parent', () => {
+    // proc contains a singleton module (dropped) plus a bare leaf, so proc
+    // still has two leaves and survives; the module's leaf is promoted in.
+    const defs = [
+      { id: 'mod', memberIds: ['a'] },
+      { id: 'proc', memberIds: ['mod', 'b'] },
+    ];
+    const plan = planCompoundGroups(defs, ['a', 'b']);
+    expect(plan.skipped).toEqual(['mod']);
+    expect(plan.built.map((g) => g.id)).toEqual(['proc']);
+    expect(plan.built[0]!.childIds.sort()).toEqual(['a', 'b']);
+  });
+
+  test('builds children before parents', () => {
+    const defs = [
+      { id: 'pkg', memberIds: ['procA', 'procB'] },
+      { id: 'procA', memberIds: ['a1', 'a2'] },
+      { id: 'procB', memberIds: ['b1', 'b2'] },
+    ];
+    const plan = planCompoundGroups(defs, ['a1', 'a2', 'b1', 'b2']);
+    const order = plan.built.map((g) => g.id);
+    expect(order.indexOf('procA')).toBeLessThan(order.indexOf('pkg'));
+    expect(order.indexOf('procB')).toBeLessThan(order.indexOf('pkg'));
+  });
+
+  test('drops groups caught in a cycle instead of looping forever', () => {
+    const defs = [
+      { id: 'x', memberIds: ['y'] },
+      { id: 'y', memberIds: ['x'] },
+    ];
+    const plan = planCompoundGroups(defs, ['a']);
+    expect(plan.built).toEqual([]);
+    expect(plan.skipped.sort()).toEqual(['x', 'y']);
+  });
+
+  test('ignores member ids that match no leaf or group', () => {
+    const plan = planCompoundGroups(
+      [{ id: 'proc', memberIds: ['a', 'ghost'] }],
+      ['a'],
+      true,
+    );
+    expect(plan.built[0]!.childIds).toEqual(['a']);
+  });
+
+  test('carries minWidth through to the plan', () => {
+    const plan = planCompoundGroups(
+      [{ id: 'mod', memberIds: ['a', 'b'], minWidth: 220 }],
+      ['a', 'b'],
+    );
+    expect(plan.built[0]!.minWidth).toBe(220);
+  });
+});
+
 describe('elkLayout helper functions', () => {
   describe('pointsToPath', () => {
     test('should return empty string for empty array', () => {

package/src/utils/elkLayout.ts

@@ -80,6 +80,16 @@ export interface ElkLayoutOptions {
    * Members reference their immediate parent via React Flow `parentId`.
    */
   groups?: Array<{ id: string; memberIds: string[]; parentId?: string; minWidth?: number }>;
+
+  /**
+   * Keep groups that hold a single leaf instead of dropping them and
+   * promoting their member to the parent. A one-child group is still a real
+   * boundary — a process with a single module, or a process whose components
+   * carry no module — so callers that own the grouping semantics opt in here.
+   * Callers must ensure each leaf appears in at most one group, or ELK throws
+   * on the duplicate. @default false
+   */
+  keepSingletonGroups?: boolean;
 }
 
 /** Result of ELK layout computation */
@@ -341,6 +351,126 @@ function getElkOptions(options: ElkLayoutOptions): LayoutOptions {
   return baseOptions;
 }
 
+/** A group definition accepted by {@link planCompoundGroups}. */
+export interface CompoundGroupDef {
+  id: string;
+  memberIds: string[];
+  minWidth?: number;
+}
+
+/** Which groups ELK builds, and which it drops. */
+export interface CompoundGroupPlan {
+  /**
+   * Built groups in build order — a group's children always appear before it,
+   * so callers can map ids to shells in one forward pass.
+   */
+  built: Array<{ id: string; childIds: string[]; minWidth?: number }>;
+  /**
+   * Dropped groups. Their members are promoted into the nearest built
+   * ancestor, so callers must clear those members' `parentId`.
+   */
+  skipped: string[];
+}
+
+/**
+ * Decide which compound groups survive, independently of the ELK runtime.
+ *
+ * Groups resolve bottom-up: a group is ready once every member is a leaf or an
+ * already-resolved group. A group is dropped when it would hold nothing, or —
+ * unless `keepSingletonGroups` — when it holds a single leaf, since a frame
+ * wrapped around one box reads worse than the box alone. Callers that keep
+ * singletons own the grouping semantics and must guarantee each leaf appears
+ * in at most one group, or ELK throws on the duplicate.
+ *
+ * Pure so the skip rules are testable without an ELK worker.
+ */
+export function planCompoundGroups(
+  groupDefs: CompoundGroupDef[],
+  leafIds: Iterable<string>,
+  keepSingletonGroups = false,
+): CompoundGroupPlan {
+  const leaves = new Set(leafIds);
+  const byId = new Map(groupDefs.map((g) => [g.id, g]));
+  const built: CompoundGroupPlan['built'] = [];
+  const skipped = new Set<string>();
+  const pending = [...groupDefs];
+
+  /** Leaves below a group, counting through nested groups. */
+  const leafDescendantCount = (memberIds: string[]): number => {
+    let n = 0;
+    for (const mid of memberIds) {
+      if (leaves.has(mid)) n += 1;
+      else {
+        const g = byId.get(mid);
+        if (g) n += leafDescendantCount(g.memberIds);
+      }
+    }
+    return n;
+  };
+
+  while (pending.length > 0) {
+    let progress = false;
+    for (let i = pending.length - 1; i >= 0; i--) {
+      const g = pending[i]!;
+      const childIds: string[] = [];
+      let ready = true;
+      for (const mid of g.memberIds) {
+        if (leaves.has(mid)) {
+          childIds.push(mid);
+          continue;
+        }
+        if (skipped.has(mid)) {
+          // Promote a dropped group's members into this parent.
+          const dropped = byId.get(mid);
+          if (!dropped) {
+            ready = false;
+            break;
+          }
+          for (const sm of dropped.memberIds) {
+            if (leaves.has(sm) || built.some((b) => b.id === sm)) childIds.push(sm);
+            else if (!skipped.has(sm)) {
+              ready = false;
+              break;
+            }
+          }
+          if (!ready) break;
+          continue;
+        }
+        if (built.some((b) => b.id === mid)) {
+          childIds.push(mid);
+          continue;
+        }
+        if (byId.has(mid)) {
+          ready = false;
+          break;
+        }
+        // Unknown id — ignored (external stubs etc. may be absent).
+      }
+      if (!ready) continue;
+
+      pending.splice(i, 1);
+      progress = true;
+
+      if (
+        childIds.length < 1 ||
+        (!keepSingletonGroups && leafDescendantCount(g.memberIds) < 2)
+      ) {
+        skipped.add(g.id);
+        continue;
+      }
+
+      built.push({ id: g.id, childIds, minWidth: g.minWidth });
+    }
+    if (!progress) {
+      // Cycle or unresolved refs — leave the rest unbuilt.
+      for (const g of pending) skipped.add(g.id);
+      break;
+    }
+  }
+
+  return { built, skipped: [...skipped] };
+}
+
 /**
  * Compute ELK layout for nodes and edges
  *
@@ -354,7 +484,7 @@ export async function computeElkLayout(
   edges: Edge[],
   options: ElkLayoutOptions = {}
 ): Promise<ElkLayoutResult> {
-  const { preserveNodePositions = true } = options;
+  const { preserveNodePositions = true, keepSingletonGroups = false } = options;
   const edgeLabels = options.edgeLabels;
   const direction = options.direction ?? 'RIGHT';
 
@@ -516,89 +646,28 @@ export async function computeElkLayout(
     'elk.spacing.nodeNode': '40',
   };
 
-  /** Descendant leaf count for singleton checks (nested groups count through). */
-  const leafDescendantCount = (memberIds: string[]): number => {
-    let n = 0;
-    for (const mid of memberIds) {
-      if (elkById.has(mid)) n += 1;
-      else {
-        const g = groupById.get(mid);
-        if (g) n += leafDescendantCount(g.memberIds);
-      }
-    }
-    return n;
-  };
-
+  const plan = planCompoundGroups(groupDefs, elkById.keys(), keepSingletonGroups);
+  const skippedGroups = new Set(plan.skipped);
   const builtGroups = new Map<string, ElkNode>();
-  const skippedGroups = new Set<string>();
-  const pending = [...groupDefs];
-  // Build bottom-up: a group is ready when every member is a leaf or an
-  // already-built / skipped group. Skipped groups promote their members.
-  while (pending.length > 0) {
-    let progress = false;
-    for (let i = pending.length - 1; i >= 0; i--) {
-      const g = pending[i]!;
-      const childNodes: ElkNode[] = [];
-      let ready = true;
-      for (const mid of g.memberIds) {
-        if (elkById.has(mid)) {
-          childNodes.push(elkById.get(mid)!);
-          continue;
-        }
-        if (skippedGroups.has(mid)) {
-          // Promote skipped group's members into this parent.
-          const skipped = groupById.get(mid);
-          if (!skipped) {
-            ready = false;
-            break;
-          }
-          for (const sm of skipped.memberIds) {
-            if (elkById.has(sm)) childNodes.push(elkById.get(sm)!);
-            else if (builtGroups.has(sm)) childNodes.push(builtGroups.get(sm)!);
-            else if (!skippedGroups.has(sm)) {
-              ready = false;
-              break;
-            }
-          }
-          if (!ready) break;
-          continue;
-        }
-        if (builtGroups.has(mid)) {
-          childNodes.push(builtGroups.get(mid)!);
-          continue;
-        }
-        if (groupById.has(mid)) {
-          ready = false;
-          break;
-        }
-        // Unknown id — ignore (external stubs etc. may be absent).
-      }
-      if (!ready) continue;
-
-      pending.splice(i, 1);
-      progress = true;
-
-      // Skip frames with fewer than 2 leaf descendants — promote children up.
-      if (leafDescendantCount(g.memberIds) < 2 || childNodes.length < 1) {
-        skippedGroups.add(g.id);
-        continue;
+  for (const g of plan.built) {
+    const children: ElkNode[] = [];
+    for (const cid of g.childIds) {
+      const leaf = elkById.get(cid);
+      if (leaf) children.push(leaf);
+      else {
+        const nested = builtGroups.get(cid);
+        if (nested) children.push(nested);
       }
-
-      builtGroups.set(g.id, {
-        id: g.id,
-        children: childNodes,
-        layoutOptions: g.minWidth == null ? compoundLayoutOptions : {
-          ...compoundLayoutOptions,
-          'elk.nodeSize.constraints': 'MINIMUM_SIZE',
-          'elk.nodeSize.minimum': `(${g.minWidth},0)`,
-        },
-      });
-    }
-    if (!progress) {
-      // Cycle or unresolved refs — leave remaining groups unbuilt.
-      for (const g of pending) skippedGroups.add(g.id);
-      break;
     }
+    builtGroups.set(g.id, {
+      id: g.id,
+      children,
+      layoutOptions: g.minWidth == null ? compoundLayoutOptions : {
+        ...compoundLayoutOptions,
+        'elk.nodeSize.constraints': 'MINIMUM_SIZE',
+        'elk.nodeSize.minimum': `(${g.minWidth},0)`,
+      },
+    });
   }
 
   const groupedLeafIds = new Set<string>();