@principal-ai/subsystems-react 0.25.1 → 0.26.1

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -20,9 +20,6 @@ import type { MouseEvent as ReactMouseEvent, ReactNode } from 'react';
 import {
   ReactFlow,
   ReactFlowProvider,
-  Background,
-  BackgroundVariant,
-  Controls,
   useReactFlow,
   useViewport,
   type NodeTypes,
@@ -61,6 +58,7 @@ import { SubsystemDiagnosticToggle, type SubsystemDiagnostic } from './Diagnosti
 import { SubsystemIssueList, type SubsystemIssue } from './IssueList';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
+import { GRAPH_NAV_PROPS, GraphChrome } from './graphChrome';
 import { ComponentDeclaration } from './ComponentDeclaration';
 import type { ComponentVerificationState } from './ComponentDeclaration';
 import { FileDrawer, FILE_DRAWER_HEIGHT_MS } from './FileDrawer';
@@ -101,6 +99,14 @@ export interface SubsystemComponentGraphProps {
    * (unselected ones dimmed); everything else is hidden.
    */
   walkthroughs?: SubsystemWalkthrough[];
+  /**
+   * Deep-link target: when set, the matching walkthrough is selected on mount
+   * — its steps expanded and its flow focused on the canvas. Hosts use this
+   * when opening the graph from a walkthrough row in a list. Re-applies on a
+   * new id (or a remount); in-tab selection afterwards stays owned by the
+   * graph.
+   */
+  initialWalkthroughId?: string | null;
   onSelect?: (componentAlias: string) => void;
   /** Called when an edge is clicked (relationship / mechanism + refs seam). */
   onEdgeSelect?: (edge: SubsystemComponentEdge) => void;
@@ -307,7 +313,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, diagnostic, issues, showIssues, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, relations, walkthroughs, initialWalkthroughId, 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();
@@ -1138,6 +1144,23 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
     setDrawerTarget((prev) => (prev?.kind === 'walkthrough' ? null : prev));
   }, []);
 
+  // Host deep-link: opening the graph from a walkthrough row selects that
+  // flow — expand its steps, focus its edges, and switch the sidebar to
+  // Walkthroughs. Guarded by a ref so a later in-tab selection isn't yanked
+  // back; a remount (or a new id) re-applies it.
+  const appliedInitialWalkthroughRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!initialWalkthroughId) return;
+    if (appliedInitialWalkthroughRef.current === initialWalkthroughId) return;
+    if (!layoutReady || !walkthroughs?.length) return;
+    const tl = walkthroughs.find((t) => t.id === initialWalkthroughId);
+    if (!tl) return;
+    appliedInitialWalkthroughRef.current = initialWalkthroughId;
+    setSidebarView('walkthroughs');
+    setExpandedWalkthroughs((prev) => new Set(prev).add(tl.id));
+    focusWalkthroughEdges(tl);
+  }, [initialWalkthroughId, layoutReady, walkthroughs, focusWalkthroughEdges]);
+
   // Switching sidebar panels also switches the edge vocabulary. Leaving the
   // Walkthroughs panel drops its canvas state (focus, expanded flows, selected
   // edge) so the Files view's topology edges aren't gated by a flow the user
@@ -1847,24 +1870,13 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
         edges={dispEdges}
         nodeTypes={nodeTypes}
         edgeTypes={edgeTypes}
-        minZoom={0.05}
-        maxZoom={4}
+        {...GRAPH_NAV_PROPS}
         onNodeClick={onNodeClick}
         onEdgeClick={onEdgeClick}
         onNodesChange={onNodesChange}
         onEdgesChange={onEdgesChange}
         proOptions={{ hideAttribution: true }}
-        nodesDraggable={false}
-        elementsSelectable
-        selectNodesOnDrag={false}
-        nodesConnectable={false}
-        edgesReconnectable={false}
         onPaneClick={onPaneClick}
-        panOnDrag
-        panOnScroll
-        zoomOnScroll={false}
-        zoomOnPinch
-        zoomOnDoubleClick={false}
         style={{
           width: '100%',
           height: '100%',
@@ -1873,8 +1885,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
           background: theme.colors.background,
         }}
       >
-        <Background variant={BackgroundVariant.Dots} gap={16} size={1} />
-        <Controls showZoom showFitView showInteractive />
+        <GraphChrome />
       </ReactFlow>
       {/* Graph / walkthrough / step titles — non-interactive chips at the top
           of the canvas. Graph-only embeds use these without opening the sidebar. */}

package/src/subsystem/graphChrome.tsx

@@ -0,0 +1,41 @@
+/**
+ * Shared navigation surface for read-only graph canvases.
+ *
+ * Every graph in this package (component graph, aggregate graph) is a React
+ * Flow wrapper and must present the same interaction language: drag/scroll to
+ * pan, pinch to zoom (never scroll-zoom or double-click-zoom), and the
+ * Background + Controls chrome. Spreading `GRAPH_NAV_PROPS` and rendering
+ * `<GraphChrome />` keeps them from drifting apart.
+ */
+
+import {
+  Background,
+  BackgroundVariant,
+  Controls,
+  type ReactFlowProps,
+} from '@xyflow/react';
+
+export const GRAPH_NAV_PROPS = {
+  minZoom: 0.05,
+  maxZoom: 4,
+  panOnDrag: true,
+  panOnScroll: true,
+  zoomOnScroll: false,
+  zoomOnPinch: true,
+  zoomOnDoubleClick: false,
+  nodesDraggable: false,
+  elementsSelectable: true,
+  selectNodesOnDrag: false,
+  nodesConnectable: false,
+  edgesReconnectable: false,
+} satisfies Partial<ReactFlowProps>;
+
+/** Background dots + zoom/fit/interactive widget; render inside `<ReactFlow>`. */
+export function GraphChrome() {
+  return (
+    <>
+      <Background variant={BackgroundVariant.Dots} gap={16} size={1} />
+      <Controls showZoom showFitView showInteractive />
+    </>
+  );
+}

package/src/subsystem/model.test.ts

@@ -28,6 +28,7 @@ import {
   formatPurl,
   packageColor,
   subsystemGraphLayoutKey,
+  describeConstructBreakdown,
 } from './model';
 import type { SubsystemComponent, SubsystemComponentEdge } from './model';
 
@@ -727,6 +728,22 @@ describe('isConstructsOnlyModel', () => {
   });
 });
 
+describe('describeConstructBreakdown', () => {
+  test('counts by construct, most common first', () => {
+    expect(describeConstructBreakdown(['function', 'class', 'function'])).toBe(
+      '2 functions · 1 class',
+    );
+  });
+
+  test('ignores blank constructs and handles empties', () => {
+    expect(describeConstructBreakdown(['', '  ', 'store'])).toBe('1 store');
+    expect(describeConstructBreakdown([])).toBe('empty');
+    expect(describeConstructBreakdown(['interface', 'type_alias', 'enum', 'custom_entity'])).toBe(
+      '1 custom_entity · 1 enum · 1 interface · +1 more',
+    );
+  });
+});
+
 describe('module badge labels', () => {
   test('moduleBadgeLabel keeps the full path when it fits the module width', () => {
     expect(moduleBadgeLabel('src/main.ts', 1000)).toBe('src/main.ts');

package/src/subsystem/model.ts

@@ -435,6 +435,40 @@ export function deriveNameFromSymbol(
   return name;
 }
 
+const CONSTRUCT_PLURALS: Record<string, string> = {
+  class: 'classes',
+  function: 'functions',
+  method: 'methods',
+  interface: 'interfaces',
+  type_alias: 'type aliases',
+  enum: 'enums',
+  store: 'stores',
+  external: 'externals',
+  custom_entity: 'custom entities',
+};
+
+/**
+ * One-line summary of what a group of declarations contains, e.g.
+ * `6 functions · 2 classes`. Used for aggregate frame boxes, which describe
+ * their contents (constructs) rather than their container. Empty/blank
+ * constructs are ignored. At most three groups; the rest folds into `+N more`.
+ */
+export function describeConstructBreakdown(constructs: readonly string[]): string {
+  const counts = new Map<string, number>();
+  for (const raw of constructs) {
+    const c = (raw ?? '').trim();
+    if (!c) continue;
+    counts.set(c, (counts.get(c) ?? 0) + 1);
+  }
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const parts = ranked.slice(0, 3).map(([c, n]) => {
+    if (n === 1) return `1 ${c}`;
+    return `${n} ${CONSTRUCT_PLURALS[c] ?? `${c}s`}`;
+  });
+  if (ranked.length > 3) parts.push(`+${ranked.length - 3} more`);
+  return parts.join(' · ') || 'empty';
+}
+
 /**
  * Human-readable purl identity — drops the `pkg:<type>/` scheme wrapper and
  * trailing version, keeping the package / owner-repo identity: