@principal-ai/subsystems-react 0.24.26 → 0.25.0

package/src/subsystem/model.ts

@@ -127,7 +127,13 @@ export type SubsystemEdgeView = 'relations' | 'walkthroughs';
 
 /** A component node — the named unit, construct-tagged; `file` is its location. */
 export interface SubsystemComponent {
-  id: string;
+  /**
+   * Model-local stable alias, unique per model. Referenced by relation /
+   * walkthrough `from` / `to`; edges point at the alias, not the location.
+   * Code identity (for composed multi-model views) lives on
+   * `purl` + `file` + `symbol`, not here.
+   */
+  alias: string;
   name: string;
   /**
    * The node's construct — what it IS as a declaration (class, function,
@@ -268,8 +274,8 @@ export interface SubsystemRelation {
  */
 export interface SubsystemComponentEdge {
   id: string;
-  from: string; // component id
-  to: string; // component id or external target label
+  from: string; // component alias
+  to: string; // component alias or external target label
   mechanism: SubsystemEdgeMechanism;
   /** Concrete file/symbol refs backing the edge (the seam). */
   refs?: string[];
@@ -374,7 +380,7 @@ export function deriveGraphEdges(doc: {
  * Those snapshots are a catalog of declarations, not a graph.
  */
 export function isConstructsOnlyModel(doc: {
-  components: readonly { id: string }[];
+  components: readonly { alias: string }[];
   relations?: readonly SubsystemRelation[];
   walkthroughs?: readonly SubsystemWalkthrough[];
 }): boolean {
@@ -473,7 +479,7 @@ export interface SubsystemProcessRegion {
   /** Display label for the boundary frame. */
   label: string;
   /** Component ids that are members of this region. */
-  memberIds: string[];
+  memberAliases: string[];
 }
 
 /** Options for which boundary frames are kept. */
@@ -516,10 +522,44 @@ export function moduleBadgeLabel(path: string, availableWidth = 0): string {
   return `${parts[0]}/…/${parts[parts.length - 1]}`;
 }
 
+/**
+ * Hover form of the badge: the collapsed `first/…/last` plus as many trailing
+ * path segments as fit in `availableWidth`. Greedily pulls segments off the
+ * tail so hovering reveals the path without ever distorting the glyphs or
+ * spilling past the frame's inner width. Falls back to the full path (no
+ * collapse) if everything fits.
+ */
+export function moduleBadgeHoverLabel(path: string, availableWidth = 0): string {
+  if (path.length * MODULE_BADGE_CHAR_WIDTH + MODULE_BADGE_CHROME <= availableWidth) {
+    return path;
+  }
+  const parts = path.split(/[\\/]/).filter((part) => part !== '' && part !== '.');
+  if (parts.length <= 2) return path;
+  let tailStart = parts.length - 1;
+  while (tailStart > 1) {
+    const candidate = `${parts[0]}/…/${parts.slice(tailStart - 1).join('/')}`;
+    if (candidate.length * MODULE_BADGE_CHAR_WIDTH + MODULE_BADGE_CHROME <= availableWidth) {
+      tailStart -= 1;
+    } else {
+      break;
+    }
+  }
+  return `${parts[0]}/…/${parts.slice(tailStart).join('/')}`;
+}
+
+/** Estimated render width (px) of the badge for `path` in the badge font. */
+export function moduleBadgeWidth(path: string): number {
+  return Math.ceil(path.length * MODULE_BADGE_CHAR_WIDTH + MODULE_BADGE_CHROME);
+}
+
 export function moduleMinWidthForBadge(path: string): number {
+  const collapsed = moduleBadgeLabel(path);
+  // `…` renders ~1.4× a regular char in the bold badge font — account for it
+  // so a path that just crosses the fit threshold doesn't collapse in vain.
+  const expanded = path[0] === '…' ? 0 : 1;
+  const glyphWidth = collapsed.length * MODULE_BADGE_CHAR_WIDTH + 4 * expanded;
   return Math.ceil(
-    moduleBadgeLabel(path).length * MODULE_BADGE_CHAR_WIDTH +
-      MODULE_BADGE_CHROME + MODULE_BADGE_INSET * 2 + MODULE_FRAME_BORDER,
+    glyphWidth + MODULE_BADGE_CHROME + MODULE_BADGE_INSET * 2 + MODULE_FRAME_BORDER,
   );
 }
 
@@ -564,14 +604,14 @@ export function getSubsystemRegions(
     const p = c.process?.trim();
     if (!p) continue;
     const list = byProcess.get(p) ?? [];
-    list.push(c.id);
+    list.push(c.alias);
     byProcess.set(p, list);
   }
-  return [...byProcess.entries()].map(([key, memberIds]) => ({
+  return [...byProcess.entries()].map(([key, memberAliases]) => ({
     kind: 'process' as const,
     key,
     label: key,
-    memberIds,
+    memberAliases,
   }));
 }
 
@@ -587,14 +627,14 @@ export function getSubsystemModuleRegions(
     const m = c.module?.trim();
     if (!m) continue;
     const list = byModule.get(m) ?? [];
-    list.push(c.id);
+    list.push(c.alias);
     byModule.set(m, list);
   }
-  return [...byModule.entries()].map(([key, memberIds]) => ({
+  return [...byModule.entries()].map(([key, memberAliases]) => ({
     kind: 'module' as const,
     key,
     label: key,
-    memberIds,
+    memberAliases,
   }));
 }
 
@@ -611,14 +651,14 @@ export function getSubsystemPackageRegions(
     const key = componentPackageKey(c);
     if (!key) continue;
     const list = byPackage.get(key) ?? [];
-    list.push(c.id);
+    list.push(c.alias);
     byPackage.set(key, list);
   }
-  return [...byPackage.entries()].map(([key, memberIds]) => ({
+  return [...byPackage.entries()].map(([key, memberAliases]) => ({
     kind: 'package' as const,
     key,
     label: packageRegionLabel(key),
-    memberIds,
+    memberAliases,
   }));
 }
 
@@ -628,7 +668,7 @@ export function getSubsystemPackageRegions(
  */
 export interface BoundaryLayoutGroup {
   id: string;
-  memberIds: string[];
+  memberAliases: string[];
   /** When set, this group is a child of another boundary group. */
   parentId?: string;
   region: SubsystemProcessRegion;
@@ -638,7 +678,7 @@ function keepRegion(
   r: SubsystemProcessRegion,
   showSingletons: boolean,
 ): boolean {
-  return showSingletons || r.memberIds.length >= 2;
+  return showSingletons || r.memberAliases.length >= 2;
 }
 
 /**
@@ -655,7 +695,7 @@ export function buildBoundaryLayoutGroups(
 ): BoundaryLayoutGroup[] {
   const showSingletons = opts.showSingletonFrames === true;
   const packageMode = opts.packageFrames ?? 'multi-repo';
-  const byId = new Map(doc.components.map((c) => [c.id, c]));
+  const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
 
   const allPackages = getSubsystemPackageRegions(doc);
   const packageEligible =
@@ -680,8 +720,8 @@ export function buildBoundaryLayoutGroups(
   const moduleGroups: BoundaryLayoutGroup[] = modules.map((r) => {
     const processesOfMembers = new Set<string>();
     const packagesOfMembers = new Set<string>();
-    for (const id of r.memberIds) {
-      const c = byId.get(id);
+    for (const alias of r.memberAliases) {
+      const c = byAlias.get(alias);
       const p = c?.process?.trim();
       if (p) processesOfMembers.add(p);
       const pkg = c ? componentPackageKey(c) : undefined;
@@ -698,7 +738,7 @@ export function buildBoundaryLayoutGroups(
     }
     return {
       id: moduleGroupNodeId(r.key),
-      memberIds: [...r.memberIds],
+      memberAliases: [...r.memberAliases],
       parentId,
       region: r,
     };
@@ -708,15 +748,15 @@ export function buildBoundaryLayoutGroups(
     const processId = processGroupNodeId(r.key);
     const nestedModules = moduleGroups.filter((m) => m.parentId === processId);
     const nestedModuleKeys = new Set(nestedModules.map((m) => m.region.key));
-    const directLeaves = r.memberIds.filter((id) => {
-      const mod = byId.get(id)?.module?.trim();
+    const directLeaves = r.memberAliases.filter((alias) => {
+      const mod = byAlias.get(alias)?.module?.trim();
       if (!mod) return true;
       return !nestedModuleKeys.has(mod);
     });
 
     const packagesOfMembers = new Set<string>();
-    for (const id of r.memberIds) {
-      const c = byId.get(id);
+    for (const alias of r.memberAliases) {
+      const c = byAlias.get(alias);
       const pkg = c ? componentPackageKey(c) : undefined;
       if (pkg) packagesOfMembers.add(pkg);
     }
@@ -728,7 +768,7 @@ export function buildBoundaryLayoutGroups(
 
     return {
       id: processId,
-      memberIds: [...nestedModules.map((m) => m.id), ...directLeaves],
+      memberAliases: [...nestedModules.map((m) => m.id), ...directLeaves],
       parentId,
       region: r,
     };
@@ -740,15 +780,15 @@ export function buildBoundaryLayoutGroups(
     const nestedModules = moduleGroups.filter((m) => m.parentId === packageId);
     const claimed = new Set<string>();
     for (const p of nestedProcesses) {
-      for (const id of p.region.memberIds) claimed.add(id);
+      for (const alias of p.region.memberAliases) claimed.add(alias);
     }
     for (const m of nestedModules) {
-      for (const id of m.region.memberIds) claimed.add(id);
+      for (const alias of m.region.memberAliases) claimed.add(alias);
     }
-    const directLeaves = r.memberIds.filter((id) => !claimed.has(id));
+    const directLeaves = r.memberAliases.filter((alias) => !claimed.has(alias));
     return {
       id: packageId,
-      memberIds: [
+      memberAliases: [
         ...nestedProcesses.map((p) => p.id),
         ...nestedModules.map((m) => m.id),
         ...directLeaves,
@@ -1175,7 +1215,7 @@ export function convertSubsystemToNodes(
           ? processGroupNodeId(processKey)
           : undefined;
       nodes.push({
-        id: c.id,
+        id: c.alias,
         type: 'subsystem-component',
         ...(parentId ? { parentId } : {}),
         position: { x: PAD + col * COL_W, y: cursorY + row * ROW_H },
@@ -1211,18 +1251,18 @@ export function convertSubsystemToGroups(
 
 /**
  * Convert a subsystem graph document into React Flow edges. Edges whose target
- * is an external label (not a component id) point at a synthetic stub so the
+ * is an external label (not a component alias) point at a synthetic stub so the
  * relationship is visible without a member node.
  */
 export function convertSubsystemToEdges(doc: SubsystemModelDocument): SubsystemGraphEdge[] {
-  const compIds = new Set(doc.components.map((c) => c.id));
+  const compAliases = new Set(doc.components.map((c) => c.alias));
   const edges: SubsystemGraphEdge[] = [];
 
   for (const e of deriveGraphEdges(doc)) {
     const color = MECHANISM_COLOR[e.mechanism];
     const style = MECHANISM_STYLE[e.mechanism];
     // If `to` is a real component, connect directly; otherwise point at a stub node.
-    const isExternal = !compIds.has(e.to);
+    const isExternal = !compAliases.has(e.to);
     const targetId = isExternal ? `external:${e.to}` : e.to;
 
     edges.push({
@@ -1248,8 +1288,8 @@ export function subsystemGraphLayoutKey(
   doc: Pick<SubsystemModelDocument, 'components' | 'relations' | 'walkthroughs'>,
 ): string {
   const components = doc.components
-    .map(({ id, purl, name, symbol, construct, file, purpose, process, module }) =>
-      [id, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? '', module ?? ''].join('\0'))
+    .map(({ alias, purl, name, symbol, construct, file, purpose, process, module }) =>
+      [alias, purl, name, symbol ?? '', construct, file, purpose ?? '', process ?? '', module ?? ''].join('\0'))
     .sort()
     .join('\n');
   const edgeKey = deriveGraphEdges(doc)
@@ -1292,7 +1332,7 @@ export async function buildSubsystemGraph(
   const layoutGroups = buildBoundaryLayoutGroups(doc, frameOpts);
   const regions = layoutGroups.map((g) => g.region);
   const regionIds = new Set(layoutGroups.map((g) => g.id));
-  const byId = new Map(doc.components.map((c) => [c.id, c]));
+  const byAlias = new Map(doc.components.map((c) => [c.alias, c]));
 
   // Resolve leaf parentIds against kept frames: module → process → package.
   // Stamp package parents here (not in convertSubsystemToNodes) so single-repo
@@ -1301,7 +1341,7 @@ export async function buildSubsystemGraph(
     if (n.type !== 'subsystem-component') continue;
     const parentId = (n as { parentId?: string }).parentId;
     if (parentId && regionIds.has(parentId)) continue;
-    const comp = (n.data as SubsystemGraphNodeData).component ?? byId.get(n.id);
+    const comp = (n.data as SubsystemGraphNodeData).component ?? byAlias.get(n.id);
     const processKey = comp?.process?.trim();
     const processId = processKey ? processGroupNodeId(processKey) : undefined;
     if (processId && regionIds.has(processId)) {
@@ -1319,10 +1359,10 @@ export async function buildSubsystemGraph(
 
   // External edge targets that aren't real components → create stub nodes so
   // cross-package edges have something to land on.
-  const realIds = new Set(doc.components.map((c) => c.id));
+  const realAliases = new Set(doc.components.map((c) => c.alias));
   const externalIds: string[] = [];
   for (const e of deriveGraphEdges(doc)) {
-    if (!realIds.has(e.to)) {
+    if (!realAliases.has(e.to)) {
       const extId = `external:${e.to}`;
       if (!externalIds.includes(extId)) externalIds.push(extId);
     }
@@ -1338,7 +1378,7 @@ export async function buildSubsystemGraph(
       height: 60,
       data: {
         component: {
-          id: extId,
+          alias: extId,
           name: label,
           construct: 'external',
           purl: 'external',
@@ -1382,7 +1422,7 @@ export async function buildSubsystemGraph(
         edgeLabels: showEdgeLabels === false ? { enabled: false } : { enabled: true, placement: 'CENTER' },
         groups: layoutGroups.map((g) => ({
           id: g.id,
-          memberIds: g.memberIds,
+          memberIds: g.memberAliases,
           parentId: g.parentId,
           minWidth: g.region.kind === 'module' ? moduleMinWidthForBadge(g.region.label) : undefined,
         })),

package/src/subsystem/nodes.tsx

@@ -31,6 +31,8 @@ import {
   nodeMinWidthForBadges,
   MODULE_BADGE_INSET,
   moduleBadgeLabel,
+  moduleBadgeHoverLabel,
+  moduleBadgeWidth,
   packageColor,
   type SubsystemGraphNodeData,
   type SubsystemGroupNodeData,
@@ -67,14 +69,14 @@ function breakWords(s: string): string {
 
 export interface SubsystemGraphCallbacks {
   /** Click a component — open its file/entry point. */
-  onSelect?: (componentId: string) => void;
+  onSelect?: (componentAlias: string) => void;
   /** Click the filename badge — open that component's file in the drawer
    *  (same path as clicking the file link in the declaration panel). */
-  onOpenFile?: (componentId: string) => void;
+  onOpenFile?: (componentAlias: string) => void;
   /** Click an edge (or its label) — select the relationship. */
   onEdgeSelect?: (edgeId: string) => void;
   /** Hover a component (null on leave) — associates it with the file tree. */
-  onHover?: (componentId: string | null) => void;
+  onHover?: (componentAlias: string | null) => void;
   /** Upper bound for node width; nodes grow with content up to this, then wrap. */
   maxNodeWidth?: number;
 }
@@ -129,7 +131,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
     <div
       onMouseEnter={() => {
         setHover(true);
-        SUBSYSTEM_CALLBACKS.onHover?.(c.id);
+        SUBSYSTEM_CALLBACKS.onHover?.(c.alias);
       }}
       onMouseLeave={() => {
         setHover(false);
@@ -137,7 +139,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
       }}
       onClick={(e) => {
         e.stopPropagation();
-        SUBSYSTEM_CALLBACKS.onSelect?.(c.id);
+        SUBSYSTEM_CALLBACKS.onSelect?.(c.alias);
       }}
       style={{
         position: 'relative',
@@ -273,7 +275,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
           onClick={(e) => {
             // Open the file directly; don't also toggle node selection.
             e.stopPropagation();
-            SUBSYSTEM_CALLBACKS.onOpenFile?.(c.id);
+            SUBSYSTEM_CALLBACKS.onOpenFile?.(c.alias);
           }}
         >
           {c.file.split('/').pop()}
@@ -356,13 +358,18 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
   const label = region?.label ?? '';
   const [expandedLabel, setExpandedLabel] = useState<string | null>(null);
   const isModule = region?.kind === 'module';
+  const isProcess = region?.kind === 'process';
   const expanded = isModule && expandedLabel === label;
   const availableBadgeWidth = Math.max(0, (width ?? 400) - MODULE_BADGE_INSET * 2 - 4);
   const collapsedLabel = isModule ? moduleBadgeLabel(label, availableBadgeWidth) : label;
-  const canExpand = isModule && collapsedLabel !== label;
-  // Process frames match external nodes — square corners (outside the soft
-  // component language). Module / package frames keep the rounded look.
-  const isProcess = region?.kind === 'process';
+  // A module badge is collapsible while something collapsed, and stays
+  // togglable while expanded (so the full path can collapse back).
+  const canToggle = isModule && (expanded || collapsedLabel !== label);
+  // Hover affords clickability by revealing more of the path — the badge
+  // widens to fit real text (never stretched), hinting before the click.
+  const [hover, setHover] = useState(false);
+  const hoveredLabel =
+    isModule && canToggle ? moduleBadgeHoverLabel(label, availableBadgeWidth) : label;
   const frameRadius = isProcess ? 0 : 12;
   const badgeRadius = isProcess ? 0 : 4;
   // Processes are deployment units — solid frame. Modules/packages stay dashed
@@ -391,16 +398,17 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
     >
       <div
         className={isModule ? 'nodrag nopan' : undefined}
-        role={canExpand ? 'button' : undefined}
-        tabIndex={canExpand && !hidden ? 0 : undefined}
-        aria-expanded={canExpand ? expanded : undefined}
-        aria-label={canExpand ? `${expanded ? 'Collapse' : 'Expand'} module path: ${label}` : undefined}
-        title={isModule ? label : undefined}
-        onClick={canExpand ? (event) => {
+        role={canToggle ? 'button' : undefined}
+        tabIndex={canToggle && !hidden ? 0 : undefined}
+        aria-expanded={canToggle ? expanded : undefined}
+        aria-label={canToggle ? `${expanded ? 'Collapse' : 'Expand'} module path: ${label}` : undefined}
+        onMouseEnter={canToggle ? () => setHover(true) : undefined}
+        onMouseLeave={canToggle ? () => setHover(false) : undefined}
+        onClick={canToggle ? (event) => {
           event.stopPropagation();
           setExpandedLabel(expanded ? null : label);
         } : undefined}
-        onKeyDown={canExpand ? (event) => {
+        onKeyDown={canToggle ? (event) => {
           if (event.key === 'Enter' || event.key === ' ') {
             event.preventDefault();
             event.stopPropagation();
@@ -420,6 +428,18 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           top: isProcess ? 0 : -19,
           left: isProcess ? '50%' : 12,
           transform: isProcess ? 'translateX(-50%)' : 'none',
+          zIndex: canToggle ? 10 : undefined,
+          // Width is explicit while collapsible so hover-reveal of more path
+          // text animates; the cap keeps both states inside the frame.
+          width:
+            isModule && canToggle && !expanded
+              ? hover
+                ? Math.min(availableBadgeWidth, moduleBadgeWidth(hoveredLabel))
+                : Math.min(availableBadgeWidth, moduleBadgeWidth(collapsedLabel))
+              : undefined,
+          transition: 'width 140ms ease, box-shadow 120ms ease',
+          cursor: canToggle ? 'pointer' : undefined,
+          boxShadow: canToggle && hover ? `0 2px 10px ${color}55` : undefined,
           fontFamily: theme.fonts.monospace,
           fontSize: theme.fontSizes[3],
           fontWeight: 700,
@@ -431,9 +451,28 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           borderRadius: badgeRadius,
           padding: '1px 7px',
           whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+          boxSizing: 'border-box',
+          pointerEvents: hidden ? 'none' : 'auto',
+          ...(isModule
+            ? {
+                // Cap the collapsed badge at the frame's inner width so it
+                // never spills past the module — it gets the `…`/click-to-
+                // expand treatment instead. Expanding lifts the cap so the
+                // full path grows the badge past the frame's edge.
+                maxWidth: expanded ? undefined : availableBadgeWidth,
+              }
+            : undefined),
         }}
       >
-        {label}
+        {canToggle ? (
+          <span style={{ whiteSpace: 'nowrap' }}>
+            {expanded ? label : hover ? hoveredLabel : collapsedLabel}
+          </span>
+        ) : (
+          label
+        )}
       </div>
     </div>
   );

package/src/subsystem/paths.ts

@@ -5,7 +5,7 @@
  * by its `purl` (`pkg:github/<owner>/<name>[#<path>]`) — never to the machine.
  * When a graph spans several repos the sidebar tree needs synthetic
  * `<owner>/<name>/` prefixes to keep same-named paths apart; hosts resolve
- * each file against `repoRoots[purlRepo] ?? repoRoot`.
+ * each file against its own purl's checkout (via the Alexandria registry).
  */
 
 /** Normalize a purl to its repo key: fragment and surrounding whitespace stripped. */