@principal-ai/subsystems-react 0.24.0 → 0.24.1

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -7,6 +7,9 @@
  * inside one labeled boundary frame; nodes without one sit outside every
  * boundary. Clicking a component invokes `onSelect`.
  *
+ * When the model has components but no topology or walkthrough edges, the
+ * canvas is a constructs catalog (list + signature) instead of a graph.
+ *
  * This is a focused fork of the package's `GraphRenderer` pipeline (same ELK
  * edge routing, delayed fitView, Background/Controls/MiniMap, node/edge type
  * injection, onNodeClick) adapted to the subsystem model — read-only.
@@ -37,6 +40,7 @@ import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
   buildSubsystemGraph,
   deriveGraphEdges,
+  isConstructsOnlyModel,
   isRelationMechanism,
   isWalkthroughMechanism,
   MECHANISM_COLOR,
@@ -50,8 +54,11 @@ import {
   type SubsystemRelation,
   type SubsystemWalkthrough,
 } from './model';
+import { ConstructsCatalog } from './ConstructsCatalog';
 import type { SubsystemOpenFileOptions } from './declarationRef';
 import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
+import { SubsystemDiagnosticToggle, type SubsystemDiagnostic } from './DiagnosticToggle';
+import { SubsystemIssueList, type SubsystemIssue } from './IssueList';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { ComponentDeclaration } from './ComponentDeclaration';
@@ -160,6 +167,29 @@ export interface SubsystemComponentGraphProps {
   sidebarExtra?: ReactNode;
   /** Rendered in the sidebar under the description (e.g. selection inspector). */
   sidebarAfterDescription?: ReactNode;
+  /**
+   * Diagnostics status chip in the sidebar title row (beside the description
+   * toggle). Shows the last verification pass's state as an icon color + count;
+   * `onOpen` opens the full report. Omit to hide the chip.
+   */
+  diagnostic?: SubsystemDiagnostic;
+  /**
+   * Verification issues for this graph (audit findings). When diagnostics are
+   * active (see `showIssues`) the sidebar's bottom panel becomes the issue
+   * list instead of the file tree / walkthroughs.
+   */
+  issues?: SubsystemIssue[];
+  /**
+   * Force the sidebar into diagnostics mode. Defaults to `true` whenever
+   * `issues` is non-empty (and nothing else has been forced).
+   */
+  showIssues?: boolean;
+  /** Click an issue — focus its target on the graph / open detail. */
+  onSelectIssue?: (issue: SubsystemIssue) => void;
+  /** Apply an issue's deterministic fix. */
+  onApplyIssueFix?: (issue: SubsystemIssue) => void;
+  /** Hover an issue — transiently highlight its target (null on leave). */
+  onHoverIssue?: (issue: SubsystemIssue | null) => void;
   /**
    * Host-injected reader/renderer for the bottom file drawer, keyed by
    * repo-root-relative path. Opening happens on declaration/file-tree clicks.
@@ -274,7 +304,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, relations, walkthroughs, 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, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, relations, walkthroughs, 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, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -935,6 +965,10 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   // own owner-avatar header. Clicking a header collapses that repo's tree.
   const repoGroups = useMemo(() => buildRepoGroups(components), [components]);
   const hasWalkthroughs = useMemo(() => (walkthroughs?.length ?? 0) > 0, [walkthroughs]);
+  // Diagnostics mode: the bottom panel shows the issue list instead of the
+  // file tree / walkthroughs. Explicit `showIssues` wins; otherwise any issues
+  // present turn it on.
+  const issuesActive = showIssues ?? (issues?.length ?? 0) > 0;
   const [collapsedRepos, setCollapsedRepos] = useState<Set<string>>(new Set());
   const toggleRepoCollapsed = useCallback((key: string) => {
     setCollapsedRepos((prev) => {
@@ -1426,7 +1460,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
       {/* Sidebar: scrollable title/description on top, files or flows pinned below.
           The description hides by default so files/flows get the room; the
           title-row toggle reveals it, and the lower panel yields back to 50%. */}
-      {!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
+      {!hideSidebar && (title || description || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
         <div
           style={{
             width: sidebarWidth,
@@ -1450,7 +1484,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
             }}
           >
           {sidebarExtra}
-          {(title || description) && (
+          {(title || description || diagnostic) && (
             <div style={{ display: 'flex', alignItems: 'flex-start', gap: 8 }}>
               {title && (
                 <h2
@@ -1467,34 +1501,47 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
                   {title}
                 </h2>
               )}
-              {description && (
-                <button
-                  type="button"
-                  aria-expanded={descriptionVisible}
-                  aria-label={descriptionVisible ? 'Hide description' : 'Show description'}
-                  title={descriptionVisible ? 'Hide description' : 'Show description'}
-                  onMouseEnter={() => setDescToggleHover(true)}
-                  onMouseLeave={() => setDescToggleHover(false)}
-                  onClick={() => setDescriptionVisible((v) => !v)}
-                  style={{
-                    display: 'inline-flex',
-                    alignItems: 'center',
-                    justifyContent: 'center',
-                    flexShrink: 0,
-                    width: 22,
-                    height: 22,
-                    padding: 0,
-                    border: 'none',
-                    borderRadius: 4,
-                    background: descToggleHover ? theme.colors.border : 'transparent',
-                    color: descToggleHover ? theme.colors.text : (theme.colors.textMuted ?? theme.colors.textSecondary),
-                    cursor: 'pointer',
-                    transition: 'background 120ms ease, color 120ms ease',
-                  }}
-                >
-                  {descriptionVisible ? <ChevronUp size={14} /> : <ChevronDown size={14} />}
-                </button>
-              )}
+              <div
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 4,
+                  flexShrink: 0,
+                  // Title's flex:1 already pushes this cluster right; without a
+                  // title, keep the actions flush right instead of flush-left.
+                  marginLeft: title ? undefined : 'auto',
+                }}
+              >
+                {diagnostic && <SubsystemDiagnosticToggle {...diagnostic} />}
+                {description && (
+                  <button
+                    type="button"
+                    aria-expanded={descriptionVisible}
+                    aria-label={descriptionVisible ? 'Hide description' : 'Show description'}
+                    title={descriptionVisible ? 'Hide description' : 'Show description'}
+                    onMouseEnter={() => setDescToggleHover(true)}
+                    onMouseLeave={() => setDescToggleHover(false)}
+                    onClick={() => setDescriptionVisible((v) => !v)}
+                    style={{
+                      display: 'inline-flex',
+                      alignItems: 'center',
+                      justifyContent: 'center',
+                      flexShrink: 0,
+                      width: 22,
+                      height: 22,
+                      padding: 0,
+                      border: 'none',
+                      borderRadius: 4,
+                      background: descToggleHover ? theme.colors.border : 'transparent',
+                      color: descToggleHover ? theme.colors.text : (theme.colors.textMuted ?? theme.colors.textSecondary),
+                      cursor: 'pointer',
+                      transition: 'background 120ms ease, color 120ms ease',
+                    }}
+                  >
+                    {descriptionVisible ? <ChevronUp size={14} /> : <ChevronDown size={14} />}
+                  </button>
+                )}
+              </div>
             </div>
           )}
           {description && descriptionVisible && (
@@ -1515,7 +1562,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
           )}
           {sidebarAfterDescription}
           </div>
-          {(treeFilePaths.length > 0 || hasWalkthroughs) && (
+          {(treeFilePaths.length > 0 || hasWalkthroughs || issuesActive) && (
             <div
               style={{
                 ...(showDesc ? { height: '50%' as const } : { flex: 1, minHeight: 0 }),
@@ -1527,6 +1574,15 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
                 overflow: 'hidden',
               }}
             >
+              {issuesActive ? (
+                <SubsystemIssueList
+                  issues={issues ?? []}
+                  onSelectIssue={onSelectIssue}
+                  onApplyFix={onApplyIssueFix}
+                  onHoverIssue={onHoverIssue}
+                />
+              ) : (
+                <>
               {hasWalkthroughs && (
                 <div
                   role="tablist"
@@ -1640,13 +1696,15 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
               })}
               </>
               ) : null}
+                </>
+              )}
             </div>
           )}
         </div>
       )}
       
       {/* Drag handle between sidebar and canvas — resize the left panel. */}
-      {!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
+      {!hideSidebar && (title || description || diagnostic || issuesActive || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasWalkthroughs) && (
         <div
           onMouseDown={onSidebarResizeStart}
           aria-label="Resize sidebar"
@@ -2435,6 +2493,12 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
     return () => ro.disconnect();
   }, []);
 
+  const constructsOnly = isConstructsOnlyModel({
+    components: props.components,
+    relations: props.relations,
+    walkthroughs: props.walkthroughs,
+  });
+
   return (
     <div
       ref={wrapRef}
@@ -2448,9 +2512,27 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
       }}
     >
       <div style={{ flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }}>
-        <ReactFlowProvider>
-          <Inner {...props} measured={size} />
-        </ReactFlowProvider>
+        {constructsOnly ? (
+          <ConstructsCatalog
+            components={props.components}
+            onSelect={props.onSelect}
+            title={props.title}
+            hideSidebar={props.hideSidebar}
+            description={props.description}
+            diagnostic={props.diagnostic}
+            sidebarExtra={props.sidebarExtra}
+            sidebarAfterDescription={props.sidebarAfterDescription}
+            renderFileViewer={props.renderFileViewer}
+            renderFileView={props.renderFileView}
+            onFileSelect={props.onFileSelect}
+            onVerifyComponent={props.onVerifyComponent}
+            componentVerification={props.componentVerification}
+          />
+        ) : (
+          <ReactFlowProvider>
+            <Inner {...props} measured={size} />
+          </ReactFlowProvider>
+        )}
       </div>
     </div>
   );

package/src/subsystem/model.test.ts

@@ -13,6 +13,7 @@ import {
   buildSubsystemGraph,
   componentPackageKey,
   deriveNameFromSymbol,
+  isConstructsOnlyModel,
   constructBadgeLabel,
   constructBadgeColor,
   FRAMEWORK_BADGE_COLOR,
@@ -642,3 +643,36 @@ describe('subsystem graph model', () => {
     expect(subsystemGraphLayoutKey(base)).toBe(subsystemGraphLayoutKey(withRef));
   });
 });
+
+describe('isConstructsOnlyModel', () => {
+  test('true when components exist and there are no edges', () => {
+    expect(isConstructsOnlyModel({ components: comps, relations: [], walkthroughs: [] })).toBe(true);
+    expect(isConstructsOnlyModel({ components: comps })).toBe(true);
+  });
+
+  test('false when empty, or when relations or walkthrough hops exist', () => {
+    expect(isConstructsOnlyModel({ components: [], relations: [] })).toBe(false);
+    expect(isConstructsOnlyModel({ components: comps, relations })).toBe(false);
+    expect(
+      isConstructsOnlyModel({
+        components: comps,
+        relations: [],
+        walkthroughs: [
+          {
+            id: 'wt',
+            title: 'flow',
+            steps: [
+              {
+                from: 'transcript',
+                to: 'reader',
+                mechanism: 'calls',
+                file: 'transcript.ts',
+                line: 1,
+              },
+            ],
+          },
+        ],
+      }),
+    ).toBe(false);
+  });
+});

package/src/subsystem/model.ts

@@ -331,8 +331,8 @@ export function walkthroughStepGraphEdgeId(
 }
 
 export function deriveGraphEdges(doc: {
-  relations?: SubsystemRelation[];
-  walkthroughs?: SubsystemWalkthrough[];
+  relations?: readonly SubsystemRelation[];
+  walkthroughs?: readonly SubsystemWalkthrough[];
 }): SubsystemComponentEdge[] {
   const byId = new Map<string, SubsystemComponentEdge>();
   for (const r of doc.relations ?? []) {
@@ -363,6 +363,22 @@ export function deriveGraphEdges(doc: {
   return [...byId.values()];
 }
 
+/**
+ * True when the model has components but no topology or walkthrough edges.
+ * Those snapshots are a catalog of declarations, not a graph.
+ */
+export function isConstructsOnlyModel(doc: {
+  components: readonly { id: string }[];
+  relations?: readonly SubsystemRelation[];
+  walkthroughs?: readonly SubsystemWalkthrough[];
+}): boolean {
+  if (doc.components.length === 0) return false;
+  return deriveGraphEdges({
+    relations: doc.relations,
+    walkthroughs: doc.walkthroughs,
+  }).length === 0;
+}
+
 /**
  * Derive a consistent display `name` from a code `symbol` + construct.
  *