@principal-ai/subsystems-react 0.20.4 → 0.20.6

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -236,8 +236,10 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   // `null` = whole flow focused; a number = that single step's edge focused.
   const [focusedStepIndex, setFocusedStepIndex] = useState<number | null>(null);
   // Hovered throughline in the flows panel: dims every canvas node/edge not
-  // involved. `stepIndex: null` = whole flow (collapsed title hover);
-  // a number = that step. Transient — no camera move, no drawer, no focus.
+  // involved in the hover preview (or selected ∪ hovered when a step is
+  // focused). `stepIndex: null` = whole flow (collapsed title hover);
+  // a number = that step. Transient — no drawer. Camera only reframes when
+  // a step is already selected.
   const [hoveredThroughlineStep, setHoveredThroughlineStep] = useState<{
     throughlineId: string;
     stepIndex: number | null;
@@ -605,7 +607,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     }
     return ids.size > 0 ? ids : null;
   };
-  // Edge/nodes involved in the hovered step or whole flow — dim everything else.
+  // Edge/nodes involved in the hovered step or whole flow.
   const hoverEdgeIds = useMemo(() => {
     if (!hoveredThroughlineStep || !throughlines) return null;
     const tl = throughlines.find((t) => t.id === hoveredThroughlineStep.throughlineId);
@@ -616,10 +618,20 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     const step = tl.steps[hoveredThroughlineStep.stepIndex];
     return step ? new Set([step.edgeId]) : null;
   }, [throughlines, hoveredThroughlineStep]);
-  const hoverNodeIds = useMemo(
-    () => endpointsOf(hoverEdgeIds),
+  // While hovering with a *step* already selected, brighten the union of
+  // selected + hovered participants. Whole-flow focus (or no focus) keeps
+  // the old hover-replace preview so a step hover still dims the rest.
+  const previewEdgeIds = useMemo(() => {
+    if (!hoverEdgeIds) return null;
+    if (focusedStepIndex == null || !focusEdgeIds) return hoverEdgeIds;
+    const ids = new Set(hoverEdgeIds);
+    for (const id of focusEdgeIds) ids.add(id);
+    return ids;
+  }, [hoverEdgeIds, focusEdgeIds, focusedStepIndex]);
+  const previewNodeIds = useMemo(
+    () => endpointsOf(previewEdgeIds),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [baseEdges, hoverEdgeIds],
+    [baseEdges, previewEdgeIds],
   );
   const openedNodeIds = useMemo(
     () => endpointsOf(openedEdgeIds),
@@ -654,9 +666,9 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   // `isSelected` rides in data because the node's stopPropagation() keeps
   // React Flow's own selection state from updating.
   const dispNodes = useMemo(() => {
-    // While a step/flow is hovered, only its participants stay bright;
-    // everything else among the currently-visible (opened-throughline) nodes
-    // is dimmed. Nodes outside the opened-throughline set stay hidden.
+    // While a step/flow is hovered, selected + hovered participants stay
+    // bright; everything else among the currently-visible (opened-throughline)
+    // nodes is dimmed. Nodes outside the opened-throughline set stay hidden.
     return xyflowNodesBase.map((n) => {
       // Boundary frames follow their members: hidden when no member is
       // visible, dimmed when members are dimmed. Never selectable.
@@ -668,8 +680,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
           anyOpened: openedNodeIds != null,
           anySelected: brightNodeIds != null,
         });
-        const dimmed = hoverNodeIds
-          ? vis.hidden || !memberIds.some((id) => hoverNodeIds.has(id))
+        const dimmed = previewNodeIds
+          ? vis.hidden || !memberIds.some((id) => previewNodeIds.has(id))
           : vis.dimmed;
         const hidden = vis.hidden;
         return {
@@ -691,8 +703,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         anyOpened: openedNodeIds != null,
         anySelected: brightNodeIds != null,
       });
-        const dimmed = hoverNodeIds ? (vis.hidden || !hoverNodeIds.has(n.id)) : vis.dimmed;
-        const hidden = vis.hidden;
+      const dimmed = previewNodeIds ? (vis.hidden || !previewNodeIds.has(n.id)) : vis.dimmed;
+      const hidden = vis.hidden;
       if (fileMatch === undefined && !isSelected && !dimmed) {
         const { fileMatch: _f, isSelected: _s, dimmed: _d, ...rest } = n.data as Record<string, unknown>;
         return { ...n, hidden, data: rest };
@@ -708,7 +720,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         },
       };
     });
-  }, [xyflowNodesBase, openFile, selected, focusNodeIds, openedNodeIds, brightNodeIds, hoverNodeIds]);
+  }, [xyflowNodesBase, openFile, selected, focusNodeIds, openedNodeIds, brightNodeIds, previewNodeIds]);
 
   const baseNodesKey = useMemo(() => nodes.map((n) => n.id).sort().join(','), [nodes]);
   const baseEdgesKey = useMemo(
@@ -729,7 +741,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         markerEnd: nextMarker,
       };
     };
-    if (openedEdgeIds || focusEdgeIds || hoverEdgeIds) {
+    if (openedEdgeIds || focusEdgeIds || previewEdgeIds) {
       return baseEdges.map((e) => {
         const vis = flowElementVisibility({
           inOpened: openedEdgeIds?.has(e.id) === true,
@@ -737,14 +749,14 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
           anyOpened: openedEdgeIds != null,
           anySelected: focusEdgeIds != null,
         });
-        const dimmed = hoverEdgeIds ? vis.hidden || !hoverEdgeIds.has(e.id) : vis.dimmed;
+        const dimmed = previewEdgeIds ? vis.hidden || !previewEdgeIds.has(e.id) : vis.dimmed;
         const hidden = vis.hidden;
         return { ...paint(e, dimmed), hidden };
       });
     }
     if (!selectedEdgeId) return baseEdges;
     return baseEdges.map((e) => paint(e, e.id !== selectedEdgeId));
-  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, hoverEdgeIds]);
+  }, [baseEdges, selectedEdgeId, openedEdgeIds, focusEdgeIds, previewEdgeIds]);
 
   const onNodesChange = useCallback(
     (changes: NodeChange[]) => {
@@ -934,7 +946,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   }, []);
 
   // Focus a single step's edge on the canvas and open/scroll the throughline
-  // drawer to that step's snippet.
+  // drawer to that step's snippet. Clicking the already-focused step clears
+  // step focus and returns to whole-flow (high-level) framing.
   // In `dim` mode: only dim non-participants (same as hovering a step) —
   // no camera move, no drawer, no hide.
   const focusThroughlineStep = useCallback(
@@ -950,6 +963,20 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
         return;
       }
+      // Toggle: clicking the selected step unselects it (back to whole flow).
+      if (focusedThroughlineId === tl.id && focusedStepIndex === stepIndex) {
+        setFocusedStepIndex(null);
+        // Pointer is still over the row — keep hover preview so dimming doesn't
+        // flash off until mouseleave.
+        setHoveredThroughlineStep({ throughlineId: tl.id, stepIndex });
+        setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
+        if (pendingFocusFitRef.current != null) {
+          window.clearTimeout(pendingFocusFitRef.current);
+          pendingFocusFitRef.current = null;
+        }
+        fitFocusBounds(new Set(tl.steps.map((s) => s.edgeId)));
+        return;
+      }
       setFocusedStepIndex(stepIndex);
       setFocusedThroughlineId(tl.id);
       setHoveredThroughlineStep(null);
@@ -983,7 +1010,13 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         }, FILE_DRAWER_HEIGHT_MS + 20);
       }
     },
-    [fitFocusBounds, renderThroughlineViewer, throughlineStepMode],
+    [
+      fitFocusBounds,
+      focusedStepIndex,
+      focusedThroughlineId,
+      renderThroughlineViewer,
+      throughlineStepMode,
+    ],
   );
 
   useEffect(() => {
@@ -994,6 +1027,37 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     };
   }, []);
 
+  // While a *step* is selected, hovering another step/flow reframes the
+  // camera to the selected ∪ hovered participants. Leaving hover snaps back
+  // to the selection alone. No step selected → hover only dims; camera stays
+  // at the high-level view. Click-to-focus still owns its own fit (including
+  // the drawer-open delay) — this only reacts to previewEdgeIds transitions.
+  const prevPreviewEdgeIdsRef = useRef<ReadonlySet<string> | null>(null);
+  useEffect(() => {
+    const prev = prevPreviewEdgeIdsRef.current;
+    prevPreviewEdgeIdsRef.current = previewEdgeIds;
+
+    if (!zoomOnThroughlineFocus || throughlineStepMode === 'dim') return;
+    // Camera follows hover only when a specific step is already focused.
+    if (focusedThroughlineId == null || focusedStepIndex == null) return;
+
+    if (previewEdgeIds) {
+      fitFocusBounds(previewEdgeIds);
+      return;
+    }
+    if (prev != null && focusEdgeIds) {
+      fitFocusBounds(focusEdgeIds);
+    }
+  }, [
+    previewEdgeIds,
+    focusEdgeIds,
+    focusedThroughlineId,
+    focusedStepIndex,
+    fitFocusBounds,
+    zoomOnThroughlineFocus,
+    throughlineStepMode,
+  ]);
+
   // Graph-only embeds: cycle throughline steps with hover-style dimming.
   useEffect(() => {
     if (!autoPlayThroughlines || !throughlines?.length || !layoutReady) return;
@@ -2037,7 +2101,13 @@ function ThroughlineFlow({
         )}
       </div>
       {!collapsed && (
-        <div style={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+        <div
+          style={{ display: 'flex', flexDirection: 'column' }}
+          onMouseLeave={() => {
+            setHoveredStep(null);
+            onLeaveStep();
+          }}
+        >
           {throughline.steps.map((step, i) => {
             const edge = edgeById.get(step.edgeId);
             const mech = edge?.mechanism;
@@ -2054,10 +2124,6 @@ function ThroughlineFlow({
                   setHoveredStep(i);
                   onHoverStep(throughline, i);
                 }}
-                onMouseLeave={() => {
-                  setHoveredStep(null);
-                  onLeaveStep();
-                }}
                 onClick={() => onFocusStep(throughline, i)}
                 style={{
                   display: 'flex',

package/src/subsystem/model.test.ts

@@ -8,6 +8,7 @@ import {
   buildSubsystemGraph,
   deriveNameFromSymbol,
   constructBadgeLabel,
+  rightBadgeLabel,
   nodeMinWidthForBadges,
   formatPurl,
   packageColor,
@@ -156,6 +157,27 @@ describe('subsystem graph model', () => {
       role: 'entry',
     });
     expect(withRole).toBeGreaterThan(stereotype);
+
+    const withProposed = nodeMinWidthForBadges({
+      construct: 'function',
+      proposed: true,
+    });
+    expect(withProposed).toBeGreaterThan(plain);
+
+    const withBoth = nodeMinWidthForBadges({
+      construct: 'function',
+      role: 'entry',
+      proposed: true,
+    });
+    // proposed-only label is shorter than entry · proposed; still wider than plain
+    expect(withBoth).toBe(withProposed);
+  });
+
+  test('rightBadgeLabel prefers proposed over role', () => {
+    expect(rightBadgeLabel({})).toBeNull();
+    expect(rightBadgeLabel({ proposed: true })).toBe('proposed');
+    expect(rightBadgeLabel({ role: 'entry' })).toBe('entry');
+    expect(rightBadgeLabel({ role: 'service', proposed: true })).toBe('proposed');
   });
 
   test('deriveNameFromSymbol falls back to file basename for modules', () => {

package/src/subsystem/model.ts

@@ -126,6 +126,13 @@ export interface SubsystemComponent {
   purl: string;
   /** One-line purpose shown on the node. */
   purpose?: string;
+  /**
+   * Design / migration placeholder — participates in edges and flows but is
+   * not a live source declaration yet. Verification skips source checks until
+   * promoted (`proposed` cleared, `file` + `symbol` filled). Orthogonal to
+   * `construct` (intended shape) and `role` (topology).
+   */
+  proposed?: boolean;
   /**
    * Semantic role — where the node sits in the topology (boundary element,
    * external system), orthogonal to `construct` (what it is). Drives the
@@ -179,13 +186,6 @@ export interface SubsystemComponent {
    * letting ELK guess the order.
    */
   layer?: number;
-  /**
-   * How this session *occupied* the component — `edited` (modified it) vs
-   * `analyzed` (read deeply / built an understanding) vs `referenced`
-   * (touched in passing). Drives clustering: edits strengthen a subsystem,
-   * but a read-only investigation can still form one around an analyzed seam.
-   */
-  capture?: 'edited' | 'analyzed' | 'referenced';
   /**
    * Graphify drill-down detail for this component, when the facet is anchored
    * to a graphify node. Discriminated by kind (class/function/type/module/store/
@@ -525,6 +525,33 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
   service: 'service',
 };
 
+/** Right-badge accent for `proposed: true` (no role, or combined with role). */
+export const PROPOSED_COLOR = '#b8860b'; // darkgoldenrod — not-yet-in-source
+
+/**
+ * Top-right badge label: proposed wins over role when both are set
+ * (proposed is the temporary exception to scan for; role stays on the model).
+ * Returns null when neither applies.
+ */
+export function rightBadgeLabel(component: {
+  role?: SubsystemComponentRole;
+  proposed?: boolean;
+}): string | null {
+  if (component.proposed) return 'proposed';
+  if (component.role != null) return ROLE_LABEL[component.role];
+  return null;
+}
+
+/** Color for the top-right badge (role and/or proposed). */
+export function rightBadgeColor(component: {
+  role?: SubsystemComponentRole;
+  proposed?: boolean;
+}): string | null {
+  if (component.proposed) return PROPOSED_COLOR;
+  if (component.role != null) return ROLE_COLOR[component.role];
+  return null;
+}
+
 /**
  * Primary badge text for a node: prefer framework stereotype over the
  * language construct so a React UI unit reads as "component" / "hook"
@@ -576,13 +603,15 @@ export function nodeMinWidthForBadges(component: {
   framework?: string;
   stereotype?: string;
   role?: SubsystemComponentRole;
+  proposed?: boolean;
   entityKind?: string;
 }): number {
   const left = estimateBadgeLabelWidth(constructBadgeLabel(component));
-  if (component.role == null) {
+  const rightLabel = rightBadgeLabel(component);
+  if (rightLabel == null) {
     return Math.max(NODE_CSS_MIN_WIDTH, BADGE_EDGE_INSET + left + BADGE_EDGE_INSET);
   }
-  const right = estimateBadgeLabelWidth(ROLE_LABEL[component.role]);
+  const right = estimateBadgeLabelWidth(rightLabel);
   return Math.max(
     NODE_CSS_MIN_WIDTH,
     BADGE_EDGE_INSET + left + BADGE_PAIR_GAP + right + BADGE_EDGE_INSET,

package/src/subsystem/nodes.tsx

@@ -19,9 +19,10 @@ import { useTheme } from '@principal-ade/industry-theme';
 import {
   MECHANISM_COLOR,
   MECHANISM_STYLE,
-  ROLE_COLOR,
-  ROLE_LABEL,
+  PROPOSED_COLOR,
   constructBadgeLabel,
+  rightBadgeLabel,
+  rightBadgeColor,
   deriveNameFromSymbol,
   BADGE_EDGE_INSET,
   nodeMinWidthForBadges,
@@ -92,11 +93,20 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   // `symbol` is the source of truth; `name` is derived from it consistently.
   const displayName = deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file, c.stereotype);
   // Top badges are absolutely positioned — widen the node so they nowrap
-  // instead of wrapping, including when construct + role badges share the top.
+  // instead of wrapping, including when construct + role/proposed share the top.
   const badgeMinWidth = nodeMinWidthForBadges(c);
+  const topRightLabel = rightBadgeLabel(c);
+  const topRightColor = rightBadgeColor(c);
   // Set while a file is open in the drawer: true → spotlight, false → dim,
   // absent (no file open) → neutral.
   const fileMatch = data.fileMatch as boolean | undefined;
+  // Border: proposed uses the goldenrod accent (dashed); construct color stays
+  // on the left badge. File-open spotlight still wins with primary.
+  const borderColor = fileMatch
+    ? theme.colors.primary
+    : c.proposed
+      ? PROPOSED_COLOR
+      : color;
   // Selection is stamped into data by the graph component — React Flow's own
   // `selected` never updates because the node stops click propagation.
   const isSelected = selected || (data.isSelected as boolean | undefined) === true;
@@ -129,10 +139,9 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         padding: '6px 10px',
         borderRadius: 8,
         background: theme.colors.backgroundSecondary ?? theme.colors.background,
-        // Selected / file-matched nodes get a thicker border; kind colors are
-        // kept for selection (thickness only). The file-open spotlight keeps
-        // its primary tint.
-        border: `${isSelected || fileMatch ? 4 : 2}px solid ${fileMatch ? theme.colors.primary : color}`,
+        // Selected / file-matched nodes get a thicker border. Proposed nodes
+        // use a dashed goldenrod border; left construct badge keeps construct color.
+        border: `${isSelected || fileMatch ? 4 : 2}px ${c.proposed ? 'dashed' : 'solid'} ${borderColor}`,
         boxShadow: fileMatch
           ? `0 1px 4px rgba(0,0,0,0.25), 0 0 12px ${theme.colors.primary}55`
           : '0 1px 4px rgba(0,0,0,0.25)',
@@ -167,10 +176,8 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         {constructBadgeLabel(c)}
       </div>
 
-      {/* Role badge — top-right, only when the node carries a topology role.
-          Role color (entry orange / service blue) on the badge; the node
-          border stays construct-colored. */}
-      {c.role != null && (
+      {/* Right badge — proposed wins over role when both are set. */}
+      {topRightLabel != null && topRightColor != null && (
         <div
           style={{
             position: 'absolute',
@@ -183,14 +190,14 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
             textTransform: 'uppercase',
             lineHeight: '17px',
             whiteSpace: 'nowrap',
-            color: ROLE_COLOR[c.role],
+            color: topRightColor,
             background: theme.colors.backgroundSecondary ?? theme.colors.background,
-            border: `1px solid ${ROLE_COLOR[c.role]}`,
+            border: `1px solid ${topRightColor}`,
             borderRadius: 4,
             padding: '0 5px',
           }}
         >
-          {ROLE_LABEL[c.role]}
+          {topRightLabel}
         </div>
       )}