@principal-ai/subsystems-react 0.35.6 → 0.36.0

package/src/subsystem/SubsystemAggregateGraph.tsx

@@ -27,8 +27,8 @@ import {
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout } from '../utils/elkLayout';
-import { describeConstructBreakdown, MECHANISM_COLOR } from './model';
-import { GRAPH_NAV_PROPS, GraphChrome } from './graphChrome';
+import { describeConstructBreakdown, MECHANISM_COLOR, assignBoundaryColors, boundaryFill } from './model';
+import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
 
 export interface AggregateFrameMember {
   alias: string;
@@ -91,13 +91,16 @@ function edgeColor(mechanism: string | undefined, fallback: string): string {
 }
 
 function AggregateFrameGroupView(
-  props: NodeProps<Node<{ label: string; kind: 'process' | 'external' }>>,
+  props: NodeProps<Node<{ label: string; color: string; kind: 'process' | 'external' }>>,
 ) {
   const { theme } = useTheme();
   const external = props.data.kind === 'external';
-  const border = external
+  // Processes take the hue assigned to their key, so boundaries read as regions
+  // at a glance; externals keep the warning accent, meaning "outside the repo".
+  // Dashed stays reserved for containment — solid chrome means a real entity.
+  const color = external
     ? (theme.colors.warning ?? theme.colors.accent ?? theme.colors.info)
-    : (theme.colors.border ?? '#333');
+    : props.data.color;
   return (
     <div
       style={{
@@ -105,25 +108,42 @@ function AggregateFrameGroupView(
         height: '100%',
         boxSizing: 'border-box',
         borderRadius: 12,
-        border: `2px ${external ? 'solid' : 'dashed'} ${border}`,
-        background: 'transparent',
+        border: `2px dashed ${color}`,
+        background: external ? 'transparent' : boundaryFill(color),
         pointerEvents: 'none',
       }}
     >
       <span
         style={{
           position: 'absolute',
-          top: -11,
+          // Centred on the frame's top border; translateY keeps it centred as
+          // the padding/border below grow instead of re-tuning a magic `top`.
+          top: 0,
+          transform: 'translateY(-50%)',
           left: 12,
+          // Edges route in through the frame's top edge, right where this
+          // label sits. The solid border + vertical padding give the opaque
+          // chip enough backing to mask a crossing edge with a gap rather than
+          // running flush against the text, and zIndex keeps the label above
+          // sibling frame nodes (mirrors the component graph's badges).
+          zIndex: 1,
           fontFamily: theme.fonts.monospace,
-          fontSize: theme.fontSizes[1],
+          fontSize: theme.fontSizes[2],
+          fontWeight: 600,
           letterSpacing: 0.5,
           textTransform: 'uppercase',
-          color: external
-            ? border
-            : (theme.colors.textMuted ?? theme.colors.textSecondary),
+          lineHeight: '18px',
+          color,
           background: theme.colors.background,
-          padding: '0 8px',
+          // A rounded chip leaves transparent notches at its corners, and an
+          // edge crossing the frame's top border shows through them. The halo
+          // is the same colour as the fill, so it squares the corners back off
+          // invisibly while covering the antialiased boundary row too.
+          boxShadow: `0 0 0 1.5px ${theme.colors.background}`,
+          border: `2px solid ${color}`,
+          borderRadius: 4,
+          padding: '4px 10px',
+          boxSizing: 'border-box',
           whiteSpace: 'nowrap',
         }}
       >
@@ -295,16 +315,37 @@ function Inner({
   const [ready, setReady] = useState(false);
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [hoveredId, setHoveredId] = useState<string | null>(null);
+  const [legendOpen, setLegendOpen] = useState(true);
 
   const layoutKey = useMemo(
     () =>
       [
-        ...frames.map((f) => f.id).sort(),
+        // Group assignment is part of the key: a frame keeps its id when its
+        // majority process flips, and the boundary colors follow the group.
+        ...frames
+          .map((f) => `${f.id}\0${f.group?.kind ?? ''}\0${f.group?.key ?? ''}`)
+          .sort(),
         ...edges.map((e) => `${e.from}\0${e.to}\0${e.steps}`).sort(),
       ].join('\n'),
     [frames, edges, hubs],
   );
 
+  // Process boundaries and their frame counts. Derived from the frames, so the
+  // legend and the boundary nodes can never drift from what is actually drawn.
+  const processBoundaries = useMemo(() => {
+    const counts = new Map<string, number>();
+    for (const f of frames) {
+      if (f.group?.kind !== 'process') continue;
+      counts.set(f.group.key, (counts.get(f.group.key) ?? 0) + 1);
+    }
+    return [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  }, [frames]);
+
+  const boundaryColors = useMemo(
+    () => assignBoundaryColors(processBoundaries.map(([key]) => key)),
+    [processBoundaries],
+  );
+
   useEffect(() => {
     let alive = true;
     setReady(false);
@@ -377,6 +418,11 @@ function Inner({
       // process frames.
       preserveNodePositions: false,
       groups,
+      // Every process and external boundary is real, including one holding a
+      // single frame — a quiet process still has components in it, and
+      // without this ELK drops the boundary and promotes the lone frame to
+      // root, which is indistinguishable from the process not existing.
+      keepSingletonGroups: true,
     })
       .then((result) => {
         if (!alive) return;
@@ -395,6 +441,10 @@ function Inner({
             selectable: false,
             data: {
               label: def?.key ?? id,
+              color:
+                (def?.kind === 'process' ? boundaryColors.get(def.key) : undefined) ??
+                theme.colors.border ??
+                '#333',
               kind: def?.kind ?? 'process',
             },
           });
@@ -429,7 +479,27 @@ function Inner({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [layoutKey]);
 
+  // A boundary is a container, not an endpoint: edges reference frame/hub
+  // ids, never the group shell's. Hovering one therefore needs its own rule.
+  // Treating the shell as the focus put *nothing* in its neighbour set, so the
+  // boundary's own contents were the ones that dimmed. Instead: keep every node
+  // lit and dim only the edges that do not touch the boundary.
+  const boundaryMembers = useMemo(() => {
+    const focus = hoveredId ?? selectedId;
+    if (!focus) return null;
+    if (nodes.find((n) => n.id === focus)?.type !== 'aggregate-frame-group') {
+      return null;
+    }
+    const members = new Set<string>();
+    for (const n of nodes) {
+      if ((n as { parentId?: string }).parentId === focus) members.add(n.id);
+    }
+    return members;
+  }, [hoveredId, selectedId, nodes]);
+
   const neighborIds = useMemo(() => {
+    // Boundary hover owns its own dimming (edges only) — no node focus set.
+    if (boundaryMembers) return null;
     const focus = hoveredId ?? selectedId;
     if (!focus) return null;
     const set = new Set<string>([focus]);
@@ -438,7 +508,7 @@ function Inner({
       if (e.to === focus) set.add(e.from);
     }
     return set;
-  }, [hoveredId, selectedId, edges]);
+  }, [hoveredId, selectedId, edges, boundaryMembers]);
 
   const selected = selectedId ? (frames.find((f) => f.id === selectedId) ?? null) : null;
 
@@ -458,35 +528,47 @@ function Inner({
         data: {
           ...(n.data as object),
           selected: selectedId === n.id,
-          dimmed: neighborIds ? !neighborIds.has(n.id) : false,
+          // Boundary hover dims everything outside the boundary; otherwise
+          // dim anything outside the focused node's neighbourhood.
+          dimmed: boundaryMembers
+            ? !boundaryMembers.has(n.id)
+            : neighborIds
+              ? !neighborIds.has(n.id)
+              : false,
           // Surviving parentId means ELK built this node's process frame —
           // the node renders nested, so a process box drops its redundant name.
           nested: (n as { parentId?: string }).parentId != null,
         },
       })),
-    [nodes, selectedId, neighborIds],
+    [nodes, selectedId, neighborIds, boundaryMembers],
   );
 
   const displayEdges = useMemo(
     () =>
       rfEdges.map((e) => {
-        const dimmed =
-          neighborIds != null &&
-          !(neighborIds.has(e.source) && neighborIds.has(e.target));
+        // Hovering a boundary keeps only the edges wholly inside it lit — a
+        // boundary-crossing edge has an endpoint outside, so it dims with the
+        // rest. Otherwise fall back to the node-focus rule.
+        const dimmed = boundaryMembers
+          ? !(boundaryMembers.has(e.source) && boundaryMembers.has(e.target))
+          : neighborIds != null &&
+            !(neighborIds.has(e.source) && neighborIds.has(e.target));
         return {
           ...e,
           style: { ...(e.style as object), opacity: dimmed ? 0.12 : 0.9 },
         };
       }),
-    [rfEdges, neighborIds],
+    [rfEdges, neighborIds, boundaryMembers],
   );
 
   return (
     <div style={{ position: 'relative', width: '100%', height: '100%', background: theme.colors.background }}>
+      <GraphLayerStyle />
       <ReactFlow
         nodes={displayNodes}
         edges={displayEdges}
         nodeTypes={nodeTypes}
+        className={GRAPH_CANVAS_CLASS}
         {...GRAPH_NAV_PROPS}
         onNodeClick={onNodeClick}
         onNodeMouseEnter={(_e, node) => setHoveredId(node.id)}
@@ -534,6 +616,94 @@ function Inner({
           {title}
         </div>
       )}
+      {processBoundaries.length > 1 && (
+        <div
+          style={{
+            position: 'absolute',
+            top: 12,
+            // Sits opposite the selection panel; shift clear of it while open.
+            right: selected ? 304 : 12,
+            maxHeight: '40%',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 3,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${theme.colors.border ?? '#333'}`,
+            borderRadius: 6,
+            padding: '6px 10px',
+            // Only the header toggles; the body must not eat canvas panning.
+            pointerEvents: 'none',
+          }}
+        >
+          <button
+            type="button"
+            onClick={() => setLegendOpen((v) => !v)}
+            aria-expanded={legendOpen}
+            style={{
+              pointerEvents: 'auto',
+              display: 'flex',
+              alignItems: 'center',
+              gap: 6,
+              padding: 0,
+              border: 'none',
+              background: 'none',
+              cursor: 'pointer',
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              letterSpacing: 0.5,
+              textTransform: 'uppercase',
+              color: muted,
+            }}
+          >
+            <span>{legendOpen ? '▾' : '▸'}</span>
+            <span>legend</span>
+          </button>
+          {legendOpen && (
+            <div
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 3,
+                maxHeight: '40vh',
+                overflowY: 'auto',
+              }}
+            >
+              {processBoundaries.map(([key, count]) => {
+                const color = boundaryColors.get(key) ?? muted;
+                return (
+                  <span
+                    key={key}
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: 6,
+                      fontFamily: theme.fonts.monospace,
+                      fontSize: theme.fontSizes[0],
+                      color: theme.colors.text,
+                      whiteSpace: 'nowrap',
+                    }}
+                  >
+                    <span
+                      style={{
+                        width: 10,
+                        height: 10,
+                        flexShrink: 0,
+                        borderRadius: 3,
+                        border: `2px dashed ${color}`,
+                        background: boundaryFill(color),
+                      }}
+                    />
+                    <span style={{ overflow: 'hidden', textOverflow: 'ellipsis', maxWidth: 160 }} title={key}>
+                      {key}
+                    </span>
+                    <span style={{ color: muted }}>{count}</span>
+                  </span>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      )}
       {selected && (
         <div
           style={{

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -62,7 +62,7 @@ import {
 } from './IssueList';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
-import { GRAPH_NAV_PROPS, GraphChrome } from './graphChrome';
+import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
 import { ComponentDeclaration } from './ComponentDeclaration';
 import type { ComponentVerificationState } from './ComponentDeclaration';
 import type { DeclarationSymbolRef, SymbolInspection } from './symbolRefs';
@@ -173,6 +173,14 @@ export interface SubsystemComponentGraphProps {
   maxNodeWidth?: number;
   /** Show edge labels (mechanism names) on the graph. @default true */
   showEdgeLabels?: boolean;
+  /**
+   * Keep boundary frames for 1-member process / module / package regions. The
+   * singleton rule (frames need 2+ members) drops these, which also hid quiet
+   * regions like a one-file process that owns real behaviour. Defaults to true
+   * here so the component graph matches the aggregate graph, which always keeps
+   * them; pass false to fall back to the 2+ member rule.
+   */
+  showSingletonFrames?: boolean;
   /**
    * Which edge vocabulary the canvas draws. The relation and walkthrough
    * vocabularies are disjoint, so a graph carrying both shows one or the
@@ -396,7 +404,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, relations, walkthroughs, initialWalkthroughId, onReorderWalkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, componentVerification, onInspectSymbol, persistKey }: InnerProps) {
+function Inner({ components, relations, walkthroughs, initialWalkthroughId, onReorderWalkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, componentVerification, onInspectSymbol, persistKey }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -657,7 +665,11 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
       relations: relationsRef.current,
       walkthroughs: walkthroughsRef.current,
     };
-    void buildSubsystemGraph(doc, { maxNodeWidth, showEdgeLabels })
+    void buildSubsystemGraph(doc, {
+      maxNodeWidth,
+      showEdgeLabels,
+      showSingletonFrames,
+    })
       .then(({ nodes, edges: e }) => {
         if (!alive) return;
         // Prune dims for removed leaves; keep measurements for stable ids so a
@@ -706,7 +718,7 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
     const gen = ++pass2GenRef.current;
     void buildSubsystemGraph(
       { components, relations, walkthroughs },
-      { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights },
+      { maxNodeWidth, showEdgeLabels, measuredWidths, measuredHeights, showSingletonFrames },
     )
       .then(({ nodes, edges: e }) => {
         if (gen !== pass2GenRef.current) return;
@@ -1974,12 +1986,14 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
         })}
       </div>
       )}
+      <GraphLayerStyle />
       <ReactFlow
         key={`${baseNodesKey}-${baseEdgesKey}`}
         nodes={dispNodes}
         edges={dispEdges}
         nodeTypes={nodeTypes}
         edgeTypes={edgeTypes}
+        className={GRAPH_CANVAS_CLASS}
         {...GRAPH_NAV_PROPS}
         onNodeClick={onNodeClick}
         onEdgeClick={onEdgeClick}

package/src/subsystem/SymbolInspectionCard.tsx

@@ -64,7 +64,15 @@ function WrappablePath({ path }: { path: string }) {
 }
 
 /** Label stacked above the value, so long values get the full width. */
-function StackedRow({ label, children }: { label: string; children: ReactNode }) {
+function StackedRow({
+  label,
+  children,
+  labelSize,
+}: {
+  label: string;
+  children: ReactNode;
+  labelSize?: number;
+}) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   return (
@@ -73,7 +81,7 @@ function StackedRow({ label, children }: { label: string; children: ReactNode })
         style={{
           color: muted,
           fontFamily: theme.fonts.body,
-          fontSize: theme.fontSizes[0],
+          fontSize: labelSize ?? theme.fontSizes[0],
           textTransform: 'uppercase',
           letterSpacing: 0.4,
         }}
@@ -261,6 +269,7 @@ export function SymbolInspectionCard({
   const mono = theme.fonts.monospace;
   const small = theme.fontSizes[0];
   const body = theme.fontSizes[1];
+  const [hoveredCandidate, setHoveredCandidate] = useState<string | null>(null);
 
   const info = inspection ?? undefined;
   const node = info?.node;
@@ -354,9 +363,14 @@ export function SymbolInspectionCard({
         )}
 
         {!error && !hasBody && (
-          <span style={{ color: theme.colors.accent ?? theme.colors.secondary, fontWeight: 600 }}>
-            {symbolRef.name}
-          </span>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+            <span style={{ color: theme.colors.accent ?? theme.colors.secondary, fontWeight: 600 }}>
+              {symbolRef.name}
+            </span>
+            <span style={{ color: muted, fontFamily: theme.fonts.body, fontSize: body }}>
+              {statusText}
+            </span>
+          </div>
         )}
       </div>
 
@@ -391,14 +405,8 @@ export function SymbolInspectionCard({
           </StackedRow>
         )}
 
-        {!hasBody && (
-          <span style={{ color: muted, fontFamily: theme.fonts.body, fontSize: body }}>
-            {statusText}
-          </span>
-        )}
-
         {info?.candidates && info.candidates.length > 0 && (
-          <StackedRow label="Candidates">
+          <StackedRow label="Candidates" labelSize={body}>
             <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
               {info.candidates.slice(0, 6).map((c) =>
                 // Ambiguous candidates share the symbol name, so the file is
@@ -409,11 +417,22 @@ export function SymbolInspectionCard({
                     role={onOpenFile ? 'button' : undefined}
                     tabIndex={onOpenFile ? 0 : undefined}
                     onClick={onOpenFile ? () => onOpenFile(c.sourceFile!, undefined) : undefined}
+                    onMouseEnter={
+                      onOpenFile ? () => setHoveredCandidate(c.nodeId) : undefined
+                    }
+                    onMouseLeave={
+                      onOpenFile
+                        ? () => setHoveredCandidate((h) => (h === c.nodeId ? null : h))
+                        : undefined
+                    }
                     style={{
                       fontFamily: mono,
                       fontSize: body,
                       color: theme.colors.accent ?? theme.colors.secondary,
                       cursor: onOpenFile ? 'pointer' : 'default',
+                      textDecorationLine:
+                        onOpenFile && hoveredCandidate === c.nodeId ? 'underline' : 'none',
+                      textUnderlineOffset: 2,
                     }}
                   >
                     <WrappablePath path={c.sourceFile} />

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: [