@principal-ai/subsystems-react 0.24.0 → 0.24.2

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 && (
@@ -1507,7 +1554,6 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
                 theme={theme}
                 disableScroll={true}
                 disableBasePadding
-                fontSizeScale={0.9}
                 enableKeyboardScrolling={false}
                 autoFocusOnVisible={false}
               />
@@ -1515,7 +1561,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 +1573,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 +1695,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"
@@ -2352,7 +2409,7 @@ function WalkthroughFlow({
                   style={{
                     flexShrink: 0,
                     width: 14,
-                    fontSize: theme.fontSizes[0] * 0.8,
+                    fontSize: theme.fontSizes[0],
                     fontFamily: theme.fonts.monospace,
                     color: stepActive ? theme.colors.text : muted,
                   }}
@@ -2435,6 +2492,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 +2511,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/SubsystemFileTree.tsx

@@ -153,7 +153,7 @@ export function SubsystemFileTree({ files, selectedFile, hoveredFile, onSelectFi
         >
           <span
             style={{
-              fontSize: theme.fontSizes[0] * 0.8,
+              fontSize: theme.fontSizes[0],
               fontFamily: theme.fonts.monospace,
               textTransform: 'uppercase',
               color: muted,
@@ -162,7 +162,7 @@ export function SubsystemFileTree({ files, selectedFile, hoveredFile, onSelectFi
           >
             Files
           </span>
-          <span style={{ fontSize: theme.fontSizes[0] * 0.8, fontFamily: theme.fonts.monospace, color: muted }}>
+          <span style={{ fontSize: theme.fontSizes[0], fontFamily: theme.fonts.monospace, color: muted }}>
             {paths.length}
           </span>
         </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.
  *

package/src/subsystem/nodes.tsx

@@ -174,7 +174,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
           left: BADGE_EDGE_INSET,
           zIndex: 1,
           fontFamily: theme.fonts.monospace,
-          fontSize: theme.fontSizes[0] * 1.1,
+          fontSize: theme.fontSizes[1],
           letterSpacing: 0.5,
           textTransform: 'uppercase',
           lineHeight: '17px',
@@ -208,7 +208,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
             <span
               style={{
                 fontFamily: theme.fonts.monospace,
-                fontSize: theme.fontSizes[0] * 1.1,
+                fontSize: theme.fontSizes[1],
                 letterSpacing: 0.5,
                 textTransform: 'uppercase',
                 lineHeight: '17px',
@@ -226,7 +226,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
             <span
               style={{
                 fontFamily: theme.fonts.monospace,
-                fontSize: theme.fontSizes[0] * 1.1,
+                fontSize: theme.fontSizes[1],
                 letterSpacing: 0.5,
                 textTransform: 'uppercase',
                 lineHeight: '17px',
@@ -255,7 +255,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
             transform: 'translateX(-50%)',
             zIndex: 1,
             fontFamily: theme.fonts.monospace,
-            fontSize: theme.fontSizes[0] * 1.1,
+            fontSize: theme.fontSizes[1],
             letterSpacing: 0.5,
             lineHeight: '17px',
             whiteSpace: 'nowrap',
@@ -311,7 +311,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
             .replace(/\(\)$/, '') && (
         <div
           style={{
-            fontSize: theme.fontSizes[0] * 0.82,
+            fontSize: theme.fontSizes[0],
             fontFamily: theme.fonts.monospace,
             color: color,
             marginTop: 1,