@principal-ai/subsystems-react 0.24.26 → 0.25.0

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -35,7 +35,7 @@ import {
   applyNodeChanges,
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
-import { ChevronDown, ChevronUp, Pause, Play, X } from 'lucide-react';
+import { FileText, Pause, Play, X } from 'lucide-react';
 import { IndustryMarkdownSlide } from 'themed-markdown';
 import {
   buildSubsystemGraph,
@@ -101,7 +101,7 @@ export interface SubsystemComponentGraphProps {
    * (unselected ones dimmed); everything else is hidden.
    */
   walkthroughs?: SubsystemWalkthrough[];
-  onSelect?: (componentId: string) => void;
+  onSelect?: (componentAlias: string) => void;
   /** Called when an edge is clicked (relationship / mechanism + refs seam). */
   onEdgeSelect?: (edge: SubsystemComponentEdge) => void;
   /** Upper bound for node width in px; nodes grow with content up to this,
@@ -217,7 +217,7 @@ export interface SubsystemComponentGraphProps {
    */
   onFileSelect?: (file: string) => void;
   /** Verify the selected component against graphify (declaration panel). */
-  onVerifyComponent?: (componentId: string) => void;
+  onVerifyComponent?: (componentAlias: string) => void;
   /** Live verification status for the selected component. */
   componentVerification?: ComponentVerificationState | null;
 }
@@ -335,7 +335,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   // Pending deferred fit after opening the drawer; cancelled on re-entry / unmount.
   const pendingFocusFitRef = useRef<number | null>(null);
   // Component the pointer is over (null on leave) → transient tree highlight.
-  const [hoveredComponentId, setHoveredComponentId] = useState<string | null>(null);
+  const [hoveredComponentAlias, setHoveredComponentId] = useState<string | null>(null);
   // Walkthrough focus — selected flow (or step) is full strength; other
   // opened-flow members stay visible but dimmed; everything else is hidden.
   const [focusedWalkthroughId, setFocusedWalkthroughId] = useState<string | null>(null);
@@ -496,7 +496,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   // writes back declarationRef).
   useEffect(() => {
     if (!selected) return;
-    const fresh = components.find((c) => c.id === selected.id);
+    const fresh = components.find((c) => c.alias === selected.alias);
     if (fresh && fresh !== selected) setSelected(fresh);
   }, [components, selected]);
 
@@ -646,12 +646,12 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   );
 
   useEffect(() => {
-    SUBSYSTEM_CALLBACKS.onSelect = (id: string) => {
-      const comp = components.find((c) => c.id === id);
+    SUBSYSTEM_CALLBACKS.onSelect = (alias: string) => {
+      const comp = components.find((c) => c.alias === alias);
       if (comp) {
         // Clicking the already-selected node unselects it (toggle off).
         // Selection is independent of the file drawer — nodes never open it.
-        if (selectedRef.current?.id === comp.id) {
+        if (selectedRef.current?.alias === comp.alias) {
           setSelected(null);
           setSelectedEdgeId(null);
           return;
@@ -660,7 +660,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
         setSelectedEdgeId(null);
         setFocusedWalkthroughId(null);
         setFocusedStepIndex(null);
-        onSelect?.(id);
+        onSelect?.(alias);
       }
     };
     SUBSYSTEM_CALLBACKS.onEdgeSelect = selectEdge;
@@ -800,15 +800,15 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
       // Boundary frames follow their members: hidden when no member is
       // visible, dimmed when members are dimmed. Never selectable.
       if (n.type === 'subsystem-group') {
-        const memberIds = ((n.data as { region?: { memberIds?: string[] } } | undefined)?.region?.memberIds) ?? [];
+        const memberAliases = ((n.data as { region?: { memberAliases?: string[] } } | undefined)?.region?.memberAliases) ?? [];
         const vis = flowElementVisibility({
-          inOpened: memberIds.some((id) => openedNodeIds?.has(id) === true),
-          inSelected: memberIds.some((id) => brightNodeIds?.has(id) === true),
+          inOpened: memberAliases.some((alias) => openedNodeIds?.has(alias) === true),
+          inSelected: memberAliases.some((alias) => brightNodeIds?.has(alias) === true),
           anyOpened: openedNodeIds != null,
           anySelected: brightNodeIds != null,
         });
         const dimmed = previewNodeIds
-          ? vis.hidden || !memberIds.some((id) => previewNodeIds.has(id))
+          ? vis.hidden || !memberAliases.some((alias) => previewNodeIds.has(alias))
           : vis.dimmed;
         const hidden = vis.hidden;
         return {
@@ -823,7 +823,7 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
       }
       const comp = (n.data as { component?: SubsystemComponent } | undefined)?.component;
       const fileMatch = fileMatchForNode(comp?.file, openFile, focusNodeIds?.has(n.id) === true);
-      const isSelected = selected?.id !== undefined && comp?.id === selected.id;
+      const isSelected = selected?.alias !== undefined && comp?.alias === selected.alias;
       const vis = flowElementVisibility({
         inOpened: openedNodeIds?.has(n.id) === true,
         inSelected: brightNodeIds?.has(n.id) === true,
@@ -944,12 +944,12 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
       if (node.type === 'subsystem-component' && comp) {
         // Clicking the already-selected node unselects it (toggle off).
         // Selection is independent of the file drawer — nodes never open it.
-        if (selected?.id === comp.id) {
+        if (selected?.alias === comp.alias) {
           setSelected(null);
           return;
         }
         setSelected(comp);
-        if (comp.id) onSelect?.(comp.id);
+        if (comp.alias) onSelect?.(comp.alias);
       }
     },
     [onSelect, selected],
@@ -1384,8 +1384,8 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   // Filename-badge clicks on nodes open the drawer through the same path as
   // the declaration panel's file link (toggle + tree sync, no start line).
   useEffect(() => {
-    SUBSYSTEM_CALLBACKS.onOpenFile = (componentId: string) => {
-      const comp = components.find((c) => c.id === componentId);
+    SUBSYSTEM_CALLBACKS.onOpenFile = (componentAlias: string) => {
+      const comp = components.find((c) => c.alias === componentAlias);
       if (comp?.file) onOpenDeclarationFile(comp.file);
     };
     return () => {
@@ -1394,23 +1394,23 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
   }, [components, onOpenDeclarationFile]);
 
   // Detail-panel links: related-name clicks select the matching component —
-  // resolved by id, name, or symbol (call labels may carry a trailing `()`).
+  // resolved by alias, name, or symbol (call labels may carry a trailing `()`).
   const resolveRelatedComponent = useCallback(
     (ref: string) => {
       const clean = ref.replace(/\(\)$/, '');
       const comp = components.find(
         (c) =>
-          c.id === clean ||
+          c.alias === clean ||
           c.name === clean ||
           c.symbol === clean ||
           c.symbol?.replace(/\(\)$/, '') === clean,
       );
-      if (!comp || comp.id === selectedRef.current?.id) return;
+      if (!comp || comp.alias === selectedRef.current?.alias) return;
       setSelected(comp);
       setSelectedEdgeId(null);
       setFocusedWalkthroughId(null);
       setFocusedStepIndex(null);
-      onSelect?.(comp.id);
+      onSelect?.(comp.alias);
     },
     [components, onSelect],
   );
@@ -1450,9 +1450,9 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
 
   // The hovered node's file (null when not hovering / file-less component).
   const hoveredFile = useMemo(() => {
-    if (!hoveredComponentId) return null;
-    return components.find((c) => c.id === hoveredComponentId)?.file ?? null;
-  }, [components, hoveredComponentId]);
+    if (!hoveredComponentAlias) return null;
+    return components.find((c) => c.alias === hoveredComponentAlias)?.file ?? null;
+  }, [components, hoveredComponentAlias]);
 
   // Drawer content renderer: prefer the path-keyed viewer; fall back to the
   // legacy component-keyed one via a file → first-component lookup.
@@ -1569,13 +1569,13 @@ function Inner({ components, relations, walkthroughs, onSelect, onEdgeSelect, me
                       padding: 0,
                       border: 'none',
                       borderRadius: 4,
-                      background: descToggleHover ? theme.colors.border : 'transparent',
-                      color: descToggleHover ? theme.colors.text : (theme.colors.textMuted ?? theme.colors.textSecondary),
+                      background: descriptionVisible || descToggleHover ? theme.colors.border : 'transparent',
+                      color: descriptionVisible || 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} />}
+                    <FileText size={14} />
                   </button>
                 )}
               </div>

package/src/subsystem/model.test.ts

@@ -9,6 +9,8 @@ import {
   processGroupNodeId,
   moduleGroupNodeId,
   moduleBadgeLabel,
+  moduleBadgeHoverLabel,
+  moduleBadgeWidth,
   moduleMinWidthForBadge,
   packageGroupNodeId,
   buildBoundaryLayoutGroups,
@@ -30,8 +32,8 @@ import {
 import type { SubsystemComponent, SubsystemComponentEdge } from './model';
 
 const comps: SubsystemComponent[] = [
-  { id: 'reader', name: 'SessionReader', construct: 'class', file: 'SessionReader.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
-  { id: 'transcript', name: 'transcript', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
+  { alias: 'reader', name: 'SessionReader', construct: 'class', file: 'SessionReader.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
+  { alias: 'transcript', name: 'transcript', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
 ];
 
 const relations = [
@@ -61,7 +63,7 @@ describe('subsystem graph model', () => {
     const withExternal: SubsystemComponent[] = [
       ...comps,
       {
-        id: "proposed-watcher",
+        alias: "proposed-watcher",
         name: "watchDir",
         construct: "external",
         // Intentionally omit file/purl — agents often leave these off for externals.
@@ -238,24 +240,24 @@ describe('subsystem graph model', () => {
   test('getSubsystemRegions groups by process, skipping process-less nodes', () => {
     const regions = getSubsystemRegions({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/acme/app', process: 'app/renderer' },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+        { 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: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/acme/app', process: 'app/renderer' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
     });
     expect(regions.map((r) => r.key)).toEqual(['app/host', 'app/renderer']);
     expect(regions.every((r) => r.kind === 'process')).toBe(true);
-    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+    expect(regions[0]!.memberAliases).toEqual(['a', 'b']);
   });
 
   test('getSubsystemModuleRegions groups by module, skipping module-less nodes', () => {
     const regions = getSubsystemModuleRegions({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
-        { id: 'b', name: 'b', construct: 'type_alias', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
-        { id: 'c', name: 'c', construct: 'function', file: 'paths.ts', purl: 'pkg:github/acme/app', module: 'src/session/paths.ts' },
-        { id: 'd', name: 'd', construct: 'function', file: 'other.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
+        { alias: 'b', name: 'b', construct: 'type_alias', file: 'transcript.ts', purl: 'pkg:github/acme/app', module: 'src/session/transcript.ts' },
+        { alias: 'c', name: 'c', construct: 'function', file: 'paths.ts', purl: 'pkg:github/acme/app', module: 'src/session/paths.ts' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'other.ts', purl: 'pkg:github/acme/app' },
       ],
     });
     expect(regions.map((r) => r.key)).toEqual([
@@ -263,14 +265,14 @@ describe('subsystem graph model', () => {
       'src/session/paths.ts',
     ]);
     expect(regions.every((r) => r.kind === 'module')).toBe(true);
-    expect(regions[0]!.memberIds).toEqual(['a', 'b']);
+    expect(regions[0]!.memberAliases).toEqual(['a', 'b']);
   });
 
   test('convertSubsystemToNodes prefers module parentId over process', () => {
     const nodes = convertSubsystemToNodes({
       components: [
         {
-          id: 'a',
+          alias: 'a',
           name: 'a',
           construct: 'function',
           file: 'a.ts',
@@ -278,7 +280,7 @@ describe('subsystem graph model', () => {
           process: 'app/host',
           module: 'src/a.ts',
         },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
       relations: [],
     });
@@ -291,8 +293,8 @@ describe('subsystem graph model', () => {
   test('convertSubsystemToNodes stamps parentId for process members only', () => {
     const nodes = convertSubsystemToNodes({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/acme/app' },
       ],
       relations: [],
     });
@@ -305,8 +307,8 @@ describe('subsystem graph model', () => {
   test('convertSubsystemToGroups emits one parent per process', () => {
     const groups = convertSubsystemToGroups({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
+        { 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' },
       ],
     });
     expect(groups).toHaveLength(1);
@@ -318,7 +320,7 @@ describe('subsystem graph model', () => {
     const groups = convertSubsystemToGroups({
       components: [
         {
-          id: 'a',
+          alias: 'a',
           name: 'a',
           construct: 'function',
           file: 'a.ts',
@@ -327,7 +329,7 @@ describe('subsystem graph model', () => {
           module: 'src/a.ts',
         },
         {
-          id: 'b',
+          alias: 'b',
           name: 'b',
           construct: 'function',
           file: 'a.ts',
@@ -350,7 +352,7 @@ describe('subsystem graph model', () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [
         {
-          id: 'boot',
+          alias: 'boot',
           name: 'boot',
           construct: 'function',
           file: 'main.ts',
@@ -360,7 +362,7 @@ describe('subsystem graph model', () => {
           symbol: 'boot',
         },
         {
-          id: 'create',
+          alias: 'create',
           name: 'createHost',
           construct: 'function',
           file: 'main.ts',
@@ -370,7 +372,7 @@ describe('subsystem graph model', () => {
           symbol: 'createHost',
         },
         {
-          id: 'write',
+          alias: 'write',
           name: 'writeSession',
           construct: 'function',
           file: 'store.ts',
@@ -380,7 +382,7 @@ describe('subsystem graph model', () => {
           symbol: 'writeSession',
         },
         {
-          id: 'store',
+          alias: 'store',
           name: 'SessionStore',
           construct: 'store',
           file: 'store.ts',
@@ -414,9 +416,9 @@ describe('subsystem graph model', () => {
   test('buildSubsystemGraph drops singleton process frames (no parentId, no group)', async () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app', process: 'app/host' },
-        { id: 'solo', name: 'solo', construct: 'function', file: 's.ts', purl: 'pkg:github/acme/app', process: 'app/lonely' },
+        { 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' },
       ],
       relations: [],
       walkthroughs: [{
@@ -434,7 +436,7 @@ describe('subsystem graph model', () => {
     const { nodes, regions } = await buildSubsystemGraph({
       components: [
         {
-          id: 'rec',
+          alias: 'rec',
           name: 'CodexRolloutRecord',
           construct: 'type_alias',
           file: 'transcript.ts',
@@ -443,7 +445,7 @@ describe('subsystem graph model', () => {
           symbol: 'CodexRolloutRecord',
         },
         {
-          id: 'parse',
+          alias: 'parse',
           name: 'parseTranscript',
           construct: 'function',
           file: 'transcript.ts',
@@ -452,7 +454,7 @@ describe('subsystem graph model', () => {
           symbol: 'parseTranscript',
         },
         {
-          id: 'solo',
+          alias: 'solo',
           name: 'lonely',
           construct: 'function',
           file: 'solo.ts',
@@ -475,10 +477,10 @@ describe('subsystem graph model', () => {
   test('getSubsystemPackageRegions groups by purl repo key, skipping externals', () => {
     const regions = getSubsystemPackageRegions({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app#a.ts' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
-        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
-        { id: 'ext', name: 'Stripe', construct: 'external', file: '', purl: 'pkg:npm/stripe' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app#a.ts' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { alias: 'ext', name: 'Stripe', construct: 'external', file: '', purl: 'pkg:npm/stripe' },
       ],
     });
     expect(regions.map((r) => r.key).sort()).toEqual([
@@ -492,8 +494,8 @@ describe('subsystem graph model', () => {
   test('buildBoundaryLayoutGroups skips package frames for single-repo graphs', () => {
     const groups = buildBoundaryLayoutGroups({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
       ],
     });
     expect(groups.filter((g) => g.region.kind === 'package')).toHaveLength(0);
@@ -502,10 +504,10 @@ describe('subsystem graph model', () => {
   test('buildBoundaryLayoutGroups frames packages when multi-repo', () => {
     const groups = buildBoundaryLayoutGroups({
       components: [
-        { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
-        { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
-        { id: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
-        { id: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/other/lib' },
+        { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+        { alias: 'c', name: 'c', construct: 'function', file: 'c.ts', purl: 'pkg:github/other/lib' },
+        { alias: 'd', name: 'd', construct: 'function', file: 'd.ts', purl: 'pkg:github/other/lib' },
       ],
     });
     const pkgs = groups.filter((g) => g.region.kind === 'package');
@@ -519,7 +521,7 @@ describe('subsystem graph model', () => {
     const groups = buildBoundaryLayoutGroups({
       components: [
         {
-          id: 'a',
+          alias: 'a',
           name: 'a',
           construct: 'function',
           file: 'a.ts',
@@ -527,7 +529,7 @@ describe('subsystem graph model', () => {
           process: 'app/host',
         },
         {
-          id: 'b',
+          alias: 'b',
           name: 'b',
           construct: 'function',
           file: 'b.ts',
@@ -535,7 +537,7 @@ describe('subsystem graph model', () => {
           process: 'app/host',
         },
         {
-          id: 'c',
+          alias: 'c',
           name: 'c',
           construct: 'function',
           file: 'c.ts',
@@ -543,7 +545,7 @@ describe('subsystem graph model', () => {
           process: 'lib/worker',
         },
         {
-          id: 'd',
+          alias: 'd',
           name: 'd',
           construct: 'function',
           file: 'd.ts',
@@ -560,7 +562,7 @@ describe('subsystem graph model', () => {
     const { nodes } = await buildSubsystemGraph({
       components: [
         {
-          id: 'a1',
+          alias: 'a1',
           name: 'a1',
           construct: 'function',
           file: 'a.ts',
@@ -569,7 +571,7 @@ describe('subsystem graph model', () => {
           module: 'src/a.ts',
         },
         {
-          id: 'a2',
+          alias: 'a2',
           name: 'a2',
           construct: 'function',
           file: 'a.ts',
@@ -578,7 +580,7 @@ describe('subsystem graph model', () => {
           module: 'src/a.ts',
         },
         {
-          id: 'b1',
+          alias: 'b1',
           name: 'b1',
           construct: 'function',
           file: 'b.ts',
@@ -587,7 +589,7 @@ describe('subsystem graph model', () => {
           module: 'src/b.ts',
         },
         {
-          id: 'b2',
+          alias: 'b2',
           name: 'b2',
           construct: 'function',
           file: 'b.ts',
@@ -615,8 +617,8 @@ describe('subsystem graph model', () => {
     const groups = buildBoundaryLayoutGroups(
       {
         components: [
-          { id: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
-          { id: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
+          { alias: 'a', name: 'a', construct: 'function', file: 'a.ts', purl: 'pkg:github/acme/app' },
+          { alias: 'b', name: 'b', construct: 'function', file: 'b.ts', purl: 'pkg:github/acme/app' },
         ],
       },
       { packageFrames: 'always' },
@@ -678,3 +680,53 @@ describe('isConstructsOnlyModel', () => {
     ).toBe(false);
   });
 });
+
+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');
+  });
+
+  test('moduleBadgeLabel keeps short paths even with a tiny module', () => {
+    expect(moduleBadgeLabel('main.ts', 0)).toBe('main.ts');
+  });
+
+  test('moduleBadgeLabel collapses deep paths to first and last segment', () => {
+    expect(moduleBadgeLabel('packages/subsystems-react/src/subsystem/nodes.tsx', 0))
+      .toBe('packages/…/nodes.tsx');
+    expect(moduleBadgeLabel('src/session/transcript.ts', 0)).toBe('src/…/transcript.ts');
+  });
+
+  test('moduleMinWidthForBadge is generous enough for the first + last segments', () => {
+    for (const path of ['main.ts', 'packages/subsystems-react/src/subsystem/nodes.tsx']) {
+      const min = moduleMinWidthForBadge(path);
+      expect(min).toBeGreaterThanOrEqual(moduleMinWidthForBadge('main.ts'));
+      // The min width reserves enough for an actual non-collapsed label.
+      expect(moduleBadgeLabel('main.ts', min)).toBe('main.ts');
+    }
+    // A deep path would still collapse at its own min width — that's the point.
+    expect(moduleBadgeLabel('packages/subsystems-react/src/subsystem/nodes.tsx', moduleMinWidthForBadge('packages/subsystems-react/src/subsystem/nodes.tsx')))
+      .toMatch(/^packages\/…\/nodes\.tsx$/);
+  });
+
+  test('moduleBadgeHoverLabel reveals more trailing segments as width allows, never the full path', () => {
+    const deep = 'packages/subsystems-react/src/subsystem/nodes.tsx';
+    const fullWidth = moduleBadgeWidth(deep);
+    // Enough room for one more middle segment, but not the full path.
+    const oneMore = 'packages/…/subsystem/nodes.tsx';
+    const roomy = moduleBadgeWidth(oneMore) + 10;
+    const hovered = moduleBadgeHoverLabel(deep, roomy);
+    expect(hovered).toContain('…');
+    expect(hovered).not.toBe(deep);
+    expect(hovered.startsWith('packages/…/')).toBe(true);
+    // Reveals more than the bare first + last, without passing the budget.
+    expect(moduleBadgeWidth(hovered)).toBeGreaterThan(moduleBadgeWidth('packages/…/nodes.tsx'));
+    expect(moduleBadgeWidth(hovered)).toBeLessThanOrEqual(roomy);
+    expect(moduleBadgeWidth(hovered)).toBeLessThanOrEqual(fullWidth);
+    // With plenty of room it returns the full path.
+    expect(moduleBadgeHoverLabel(deep, fullWidth + 8)).toBe(deep);
+  });
+
+  test('moduleBadgeWidth estimates a label strictly wider than its shorter precursor', () => {
+    expect(moduleBadgeWidth('src/…/nodes.tsx')).toBeLessThan(moduleBadgeWidth('packages/…/nodes.tsx'));
+  });
+});