@principal-ai/subsystems-react 0.35.7 → 0.36.0

package/src/subsystem/graphChrome.tsx

@@ -30,6 +30,26 @@ export const GRAPH_NAV_PROPS = {
   edgesReconnectable: false,
 } satisfies Partial<ReactFlowProps>;
 
+/**
+ * React Flow mounts its edge SVG (`.react-flow__edges`) and node layer
+ * (`.react-flow__nodes`) as sibling containers inside the viewport, both at
+ * `z-index: auto`, and leans on DOM order (edges first, nodes second) to keep
+ * nodes on top. Nodes carry an inline `z-index: 0`, which on its own does not
+ * reliably beat the edge layer, so an edge routing into a boundary frame's top
+ * border paints *over* that frame's label. Lift the whole node layer above the
+ * edge layer once for every graph that spreads `GRAPH_NAV_PROPS`.
+ *
+ * Scoped by `GRAPH_CANVAS_CLASS` so it only touches our canvases.
+ */
+export const GRAPH_CANVAS_CLASS = 'subsystem-graph-canvas';
+
+export const GRAPH_LAYER_CSS = `.${GRAPH_CANVAS_CLASS} .react-flow__nodes { z-index: 1; }`;
+
+/** Scoped style tag for `GRAPH_LAYER_CSS`; render once beside `<ReactFlow>`. */
+export function GraphLayerStyle() {
+  return <style>{GRAPH_LAYER_CSS}</style>;
+}
+
 /** Background dots + zoom/fit/interactive widget; render inside `<ReactFlow>`. */
 export function GraphChrome() {
   return (

package/src/subsystem/model.test.ts

@@ -435,6 +435,97 @@ describe('subsystem graph model', () => {
     expect(nodes.find((n) => n.id === processGroupNodeId('app/lonely'))).toBeUndefined();
   });
 
+  // NOTE: buildSubsystemGraph cannot assert ELK-built frames here — elkjs
+  // constructs a Worker, which bun's test env lacks, so every call falls back
+  // to manual positions. Frame existence is covered by planCompoundGroups
+  // tests in utils/elkLayout.test.ts; these cover the grouping inputs.
+
+  test('buildBoundaryLayoutGroups keeps singleton regions only when asked', () => {
+    const doc = {
+      components: [
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+      ],
+    };
+    const off = buildBoundaryLayoutGroups(doc as never);
+    expect(off.map((g) => g.id)).not.toContain(processGroupNodeId('app/lonely'));
+
+    const on = buildBoundaryLayoutGroups(doc as never, { showSingletonFrames: true });
+    const lonely = on.find((g) => g.id === processGroupNodeId('app/lonely'));
+    expect(lonely).toBeDefined();
+    expect(lonely!.memberAliases).toEqual(['solo']);
+  });
+
+  test('subsystem component graph keeps singleton frames unless opted out', () => {
+    // The component graph's default differs from buildBoundaryLayoutGroups'
+    // own default: SubsystemComponentGraph passes showSingletonFrames=true so
+    // a one-file process keeps its boundary, matching the aggregate graph.
+    // Only an explicit false falls back to the 2+ member rule.
+    const doc = {
+      components: [
+        { alias: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+      ],
+    };
+    // Mirrors the Inner default: `showSingletonFrames = true`.
+    const componentGraphDefault = true;
+    const kept = buildBoundaryLayoutGroups(doc as never, { showSingletonFrames: componentGraphDefault });
+    expect(kept.map((g) => g.id)).toContain(processGroupNodeId('app/lonely'));
+
+    const optedOut = buildBoundaryLayoutGroups(doc as never, { showSingletonFrames: false });
+    expect(optedOut.map((g) => g.id)).not.toContain(processGroupNodeId('app/lonely'));
+  });
+
+  test('buildBoundaryLayoutGroups parents every leaf to exactly one frame', () => {
+    // The invariant that keeps ELK from throwing "value already present".
+    // Singletons do not claim (see buildBoundaryLayoutGroups): they always
+    // nest, so the enclosing frame's own filter has to exclude them. This
+    // asserts the outcome rather than the mechanism.
+    const doc = {
+      components: [
+        { alias: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+        { alias: 'x', name: 'x', construct: 'function', file: 'x.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'y', name: 'y', construct: 'function', file: 'y.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'z', name: 'z', construct: 'function', file: 'z.ts', purl: 'pkg:github/acme/other', process: 'other/host' },
+        { alias: 'w', name: 'w', construct: 'function', file: 'w.ts', purl: 'pkg:github/acme/other', process: 'other/host' },
+        // module-less leaf in a multi-member process
+        { alias: 'loose', name: 'loose', construct: 'function', file: 'l.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+      ],
+    };
+    const groups = buildBoundaryLayoutGroups(doc as never, { showSingletonFrames: true });
+    const owners = new Map<string, string[]>();
+    for (const g of groups) {
+      for (const alias of g.memberAliases) {
+        owners.set(alias, [...(owners.get(alias) ?? []), g.id]);
+      }
+    }
+    for (const [alias, claimedBy] of owners) {
+      expect(new Set(claimedBy).size, `leaf ${alias} claimed by ${claimedBy.join(', ')}`).toBe(1);
+    }
+    // The singleton process nests under its package rather than claiming.
+    const lonely = groups.find((g) => g.id === processGroupNodeId('app/lonely'));
+    expect(lonely!.memberAliases).toEqual(['solo']);
+    expect(lonely!.parentId).toBe(packageGroupNodeId('pkg:github/acme/app'));
+  });
+
+  test('buildBoundaryLayoutGroups singleton module claims its leaf from the process', () => {
+    const doc = {
+      components: [
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'm1', name: 'm1', construct: 'function', file: 'm1.ts', purl: 'pkg:github/acme/app', module: 'src/one.ts', process: 'app/host' },
+        { alias: 'm2', name: 'm2', construct: 'function', file: 'm1.ts', purl: 'pkg:github/acme/app', module: 'src/one.ts', process: 'app/host' },
+      ],
+    };
+    const groups = buildBoundaryLayoutGroups(doc as never, { showSingletonFrames: true });
+    const mod = groups.find((g) => g.id === moduleGroupNodeId('src/one.ts'));
+    const proc = groups.find((g) => g.id === processGroupNodeId('app/host'));
+    expect(mod!.memberAliases).toEqual(['m1', 'm2']);
+    // The module is nested, so the process lists the module — not its
+    // leaves. `a` has no module, so it stays a direct leaf of the process.
+    expect(proc!.memberAliases).toEqual([moduleGroupNodeId('src/one.ts'), 'a']);
+    expect(proc!.parentId).toBeUndefined();
+  });
+
   test('buildSubsystemGraph frames multi-member modules', async () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [

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', () => {