pkgviz 0.7.7 → 0.8.0

package/src/features/project-tree/utils/findProjectTreeNodeByGraphPackage.ts

@@ -0,0 +1,21 @@
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Finds the deepest directory representing a graph package, falling back to a matching file. */
+export function findProjectTreeNodeByGraphPackage(
+  nodes: readonly ProjectTreeNode[],
+  graphPackage: string
+): ProjectTreeNode | null {
+  const matches = collectProjectTreePackageMatches(nodes, graphPackage);
+  return matches.find(node => node.kind === 'directory') ?? matches.at(0) ?? null;
+}
+
+/*** Collects package matches depth-first so nested directories outrank their ancestors. */
+function collectProjectTreePackageMatches(
+  nodes: readonly ProjectTreeNode[],
+  graphPackage: string
+): readonly ProjectTreeNode[] {
+  return nodes.flatMap(node => [
+    ...(node.children ? collectProjectTreePackageMatches(node.children, graphPackage) : []),
+    ...(node.graphPackage === graphPackage ? [node] : []),
+  ]);
+}

package/src/features/project-tree/utils/getProjectTreeAncestorIds.ts

@@ -0,0 +1,26 @@
+import type { ProjectTreeNode } from '@/types/projectTree';
+
+/*** Returns every directory id that must be expanded to reveal one tree node. */
+export function getProjectTreeAncestorIds(
+  nodes: readonly ProjectTreeNode[],
+  targetId: string
+): readonly string[] {
+  return findProjectTreeAncestorIds(nodes, targetId, []) ?? [];
+}
+
+/*** Finds one target recursively while carrying its directory ancestry. */
+function findProjectTreeAncestorIds(
+  nodes: readonly ProjectTreeNode[],
+  targetId: string,
+  ancestors: readonly string[]
+): readonly string[] | null {
+  for (const node of nodes) {
+    if (node.id === targetId) return ancestors;
+    if (!node.children) continue;
+
+    const match = findProjectTreeAncestorIds(node.children, targetId, [...ancestors, node.id]);
+    if (match !== null) return match;
+  }
+
+  return null;
+}

package/src/features/settings/utils/readSettingsEnvironment.ts

@@ -0,0 +1,53 @@
+import { readEnvBoolean, readEnvNumber, readEnvString } from '@ankhorage/utility/node/env';
+import type { LayoutOptions } from 'cytoscape';
+
+/*** Reads and validates PKGViz viewer defaults from public settings environment variables. */
+export function readSettingsEnvironment(): SettingsEnvironment {
+  const environment = {
+    NEXT_PUBLIC_SETTINGS_SHOW_CYCLES: process.env.NEXT_PUBLIC_SETTINGS_SHOW_CYCLES,
+    NEXT_PUBLIC_SETTINGS_LAYOUT: process.env.NEXT_PUBLIC_SETTINGS_LAYOUT,
+    NEXT_PUBLIC_SETTINGS_LAYOUT_SPACING: process.env.NEXT_PUBLIC_SETTINGS_LAYOUT_SPACING,
+    NEXT_PUBLIC_SETTINGS_SHOW_COMPOUNDNODES: process.env.NEXT_PUBLIC_SETTINGS_SHOW_COMPOUNDNODES,
+    NEXT_PUBLIC_SETTINGS_SHOW_VENDORPACKAGES: process.env.NEXT_PUBLIC_SETTINGS_SHOW_VENDORPACKAGES,
+    NEXT_PUBLIC_SETTINGS_SUBPACKAGE_DEPTH: process.env.NEXT_PUBLIC_SETTINGS_SUBPACKAGE_DEPTH,
+  };
+
+  const layout = readEnvString('NEXT_PUBLIC_SETTINGS_LAYOUT', environment);
+  const layoutSpacing = readEnvNumber('NEXT_PUBLIC_SETTINGS_LAYOUT_SPACING', environment);
+  const subPackageDepth = readEnvNumber('NEXT_PUBLIC_SETTINGS_SUBPACKAGE_DEPTH', environment);
+
+  return {
+    showCycles: readEnvBoolean('NEXT_PUBLIC_SETTINGS_SHOW_CYCLES', environment) ?? false,
+    cytoscapeLayout: isSupportedLayout(layout) ? layout : 'concentric',
+    cytoscapeLayoutSpacing:
+      layoutSpacing !== undefined && layoutSpacing >= 0.1 && layoutSpacing <= 1 ? layoutSpacing : 1,
+    showCompoundNodes:
+      readEnvBoolean('NEXT_PUBLIC_SETTINGS_SHOW_COMPOUNDNODES', environment) ?? true,
+    showVendorPackages:
+      readEnvBoolean('NEXT_PUBLIC_SETTINGS_SHOW_VENDORPACKAGES', environment) ?? false,
+    subPackageDepth:
+      subPackageDepth !== undefined && Number.isInteger(subPackageDepth) && subPackageDepth >= 1
+        ? subPackageDepth
+        : 1,
+  };
+}
+
+/*** Determines whether an environment value names a supported Cytoscape layout. */
+function isSupportedLayout(value: string | undefined): value is LayoutOptions['name'] {
+  return (
+    value === 'breadthfirst' ||
+    value === 'circle' ||
+    value === 'concentric' ||
+    value === 'elk' ||
+    value === 'grid'
+  );
+}
+
+interface SettingsEnvironment {
+  readonly showCycles: boolean;
+  readonly cytoscapeLayout: LayoutOptions['name'];
+  readonly cytoscapeLayoutSpacing: number;
+  readonly showCompoundNodes: boolean;
+  readonly showVendorPackages: boolean;
+  readonly subPackageDepth: number;
+}

package/src/i18n/en.ts

@@ -7,15 +7,34 @@ const en: ILanguage = {
 
   // Settings
   'settings.title': 'Settings',
+  'settings.tree': 'Tree',
+  'settings.rules': 'Rules',
+  'settings.export': 'Export',
+  'sidebar.tools': 'Sidebar tools',
   'settings.showCompoundNodes': 'Show Compound Nodes',
   'settings.showVendorPackages': 'Show Vendor',
   'settings.subPackageDepth': 'Subpackage depth',
-  'settings.audit': 'Audit',
-  'settings.download': 'Download',
   'settings.layout': 'Layout',
   'settings.layoutSpacing': 'Layout Spacing',
   'settings.filter': 'Filter',
 
+  // Audit
+  'audit.rules': 'Audit rules',
+  'audit.loading': 'Loading audit…',
+  'audit.loadError': 'Unable to load audit details.',
+  'audit.noRules': 'No audit rules are enabled.',
+  'audit.cycle': 'Cycle',
+  'audit.cycles': 'cycles',
+  'audit.findings': 'findings',
+  'audit.imports': 'imports',
+  'audit.cyclePath': 'Cycle path',
+  'audit.dependencyEvidence': 'Dependency evidence',
+  'audit.packages': 'packages',
+  'audit.dependencyEdges': 'dependency edges',
+  'audit.noEvidence': 'No source/import evidence available.',
+  'audit.closeInspector': 'Close cycle inspector',
+  'audit.rule.cyclicDependencies': 'Cyclic Dependencies',
+
   // Layouts
   breadthfirst: 'Breadthfirst',
   circle: 'Circle',

package/src/i18n/i18n.ts

@@ -3,10 +3,9 @@ import en from '@/i18n/en';
 const languages = { en };
 const activeLang = languages.en;
 
+/*** Returns the localized string for a translation key. */
 export function t(term: string) {
   return activeLang[term] || `{${term}}`;
 }
 
-export interface ILanguage {
-  readonly [key: string]: string;
-}
+export type ILanguage = Readonly<Record<string, string>>;

package/src/layouts/breadthfirst/style.ts

@@ -1,6 +1,7 @@
 import type { StylesheetJson } from 'cytoscape';
 
 // No specific 'breadthfirst' styles for now
+/*** Returns Cytoscape style overrides for this layout. */
 export function getStyle() {
   const style: StylesheetJson = [];
 

package/src/layouts/circle/style.ts

@@ -1,5 +1,6 @@
 import type { StylesheetJson } from 'cytoscape';
 
+/*** Returns Cytoscape style overrides for this layout. */
 export function getStyle() {
   const styles: StylesheetJson = [
     {

package/src/layouts/concentric/style.ts

@@ -1,6 +1,7 @@
 import type { /* NodeSingular, */ StylesheetJson } from 'cytoscape';
 
 // No specific 'concentric' styles for now
+/*** Returns Cytoscape style overrides for this layout. */
 export function getStyle() {
   const style: StylesheetJson = [
     {

package/src/layouts/elk/layout.ts

@@ -1,6 +1,4 @@
-import cytoscape from 'cytoscape';
-import elk from 'cytoscape-elk';
-cytoscape.use(elk as cytoscape.Ext);
+import type cytoscape from 'cytoscape';
 
 type ElkLayoutOptions = cytoscape.BaseLayoutOptions &
   cytoscape.AnimatedLayoutOptions & {

package/src/layouts/elk/style.ts

@@ -1,5 +1,6 @@
 import type { StylesheetJson } from 'cytoscape';
 
+/*** Returns Cytoscape style overrides for this layout. */
 export function getStyle() {
   const style: StylesheetJson = [
     {

package/src/layouts/getWeightBuckets.ts

@@ -1,5 +1,6 @@
 import type { ElementsDefinition } from 'cytoscape';
 
+/*** Computes edge-weight thresholds and bucket counts. */
 export function getWeightBuckets(
   categoryCount: number,
   algorithm: 'linear' | 'log' | 'quantile' = 'linear',
@@ -49,7 +50,8 @@ export function getWeightBuckets(
   };
 }
 
-export function getMaxEdgeWeight(filteredElements: ElementsDefinition) {
+/*** Returns the largest edge weight in the graph. */
+function getMaxEdgeWeight(filteredElements: ElementsDefinition) {
   return (
     filteredElements?.edges.reduce((max, edge) => {
       return edge.data.weight > max ? edge.data.weight : max;

package/src/layouts/grid/style.ts

@@ -1,5 +1,6 @@
 import type { StylesheetJson } from 'cytoscape';
 
+/*** Returns Cytoscape style overrides for this layout. */
 export function getStyle() {
   const style: StylesheetJson = [
     {

package/src/layouts/index.ts

@@ -1,14 +1,10 @@
 export { layout as breadthfirstLayout } from '@/layouts/breadthfirst/layout';
 export { getStyle as getBreadthfirstStyle } from '@/layouts/breadthfirst/style';
-
 export { layout as circleLayout } from '@/layouts/circle/layout';
 export { getStyle as getCircleStyle } from '@/layouts/circle/style';
-
 export { layout as concentricLayout } from '@/layouts/concentric/layout';
 export { getStyle as getConcentricStyle } from '@/layouts/concentric/style';
-
 export { layout as elkLayout } from '@/layouts/elk/layout';
 export { getStyle as getElkStyle } from '@/layouts/elk/style';
-
 export { layout as gridLayout } from '@/layouts/grid/layout';
 export { getStyle as getGridStyle } from '@/layouts/grid/style';

package/src/layouts/style.ts

@@ -1,5 +1,6 @@
-import type { ElementsDefinition, NodeSingular, StylesheetJson } from 'cytoscape';
+import type { ElementsDefinition, StylesheetJson } from 'cytoscape';
 
+import { createCompoundOpacityIndex } from '@/features/graph-view/utils/createCompoundOpacityIndex';
 import { getWeightBuckets } from '@/layouts/getWeightBuckets';
 
 export type ThemeKey = 'dark' | 'light';
@@ -7,7 +8,6 @@ export type ThemeKey = 'dark' | 'light';
 const palette = {
   light: {
     canvasBg: '#ffffff',
-    // edge: '#9E9E9E',
     edge: '#000',
     weightXs: '#000',
     weightMd: '#000',
@@ -18,6 +18,7 @@ const palette = {
     nodeBorderVendor: '#E2D5FF',
     nodeBgVendor: '#D1C4FF',
     nodeText: '#0B5FFF',
+    compoundBg: '#7892B3',
 
     selectedFill: '#0B5FFF',
     selectedFillVendor: '#a025aa',
@@ -36,6 +37,7 @@ const palette = {
     nodeBorder: '#2A3A4A',
     nodeBorderVendor: '#351542',
     nodeText: '#E8F0FF',
+    compoundBg: '#A9BCD5',
 
     selectedFill: '#2E6FFF',
     selectedFillVendor: '#4E25AA',
@@ -44,12 +46,55 @@ const palette = {
   },
 } as const;
 
+/*** Returns the canvas background for the active theme. */
 export const getCanvasBg = (theme: ThemeKey) => palette[theme].canvasBg;
 
+/*** Builds the shared Cytoscape styles for the active theme. */
 export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey): StylesheetJson {
   const colors = palette[theme];
   const { thresholds } = getWeightBuckets(3, 'linear', filteredElements);
 
+  return [
+    ...getNodeBaseStyles(colors),
+    ...getNodeInteractionStyles(colors),
+    ...getNodeStateStyles(colors),
+    ...getCompoundStyles(colors),
+    ...getCompoundOpacityStyles(filteredElements),
+    ...getEdgeBaseStyles(colors),
+    ...getEdgeWeightStyles(colors, thresholds),
+    ...getCycleEdgeStyles(colors),
+  ];
+}
+
+type Palette = (typeof palette)[ThemeKey];
+
+/***
+ * Shows leaf neighborhoods without changing layout geometry or dimming compound descendants.
+ * @performance Use paint-only interaction styles; border size, labels and dimensions stay stable.
+ */
+function getNodeInteractionStyles(colors: Palette): StylesheetJson {
+  return [
+    { selector: 'node:childless.hushed', style: { opacity: 0.2 } },
+    {
+      selector: 'node.highlight-outgoer, node.highlight-incomer',
+      style: { 'border-color': colors.selectedRing, opacity: 1 },
+    },
+    {
+      selector: 'node:childless.highlight',
+      style: { 'background-color': colors.selectedFill, color: colors.selectedText, opacity: 1 },
+    },
+  ];
+}
+
+/***
+ * Maps prepared node presentation data without per-element style callbacks.
+ * @performance
+ * Preserve data(label): createGraphViewModel prepares labels outside Cytoscape style recalculation.
+ * ZORA owns measured label width. Keep height independent of the previous rendered height, otherwise repeated
+ * style updates can change geometry and trigger further layout work. The style regression tests
+ * cover stable dimensions across theme changes and updates to prepared label data.
+ */
+function getNodeBaseStyles(colors: Palette): StylesheetJson {
   return [
     {
       selector: 'node',
@@ -58,16 +103,12 @@ export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey):
         'background-color': colors.nodeBg,
         'border-color': colors.nodeBorder,
         color: colors.nodeText,
-        label: 'data(name)',
+        label: 'data(label)',
         'text-valign': 'center',
         'text-halign': 'center',
-        width: (node: NodeSingular) => {
-          return node.data('name').length * 7;
-        },
-        height: (node: NodeSingular) => {
-          return node.height() / 2 + 10;
-        },
-        padding: '8px 8px',
+        width: 24,
+        height: 24,
+        padding: '12px',
         'border-width': 1,
         'font-size': '14px',
         'overlay-opacity': 0, // avoid gray overlay
@@ -79,14 +120,36 @@ export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey):
         'background-color': colors.nodeBgVendor,
       },
     },
-    { selector: 'node.packageCycle', style: { 'border-color': '#d80303', 'border-width': 3 } },
+  ];
+}
+
+/***
+ * Preserves selected-node and audit-cycle presentation.
+ * @performance Selection uses an outline: changing border width changes layout dimensions.
+ * Audit overlays retain their existing geometry and remain separate from transient interactions.
+ */
+function getNodeStateStyles(colors: Palette): StylesheetJson {
+  return [
+    {
+      selector: 'node.auditCycle',
+      style: {
+        'border-color': 'data(auditCycleColor)',
+        'border-width': 5,
+        opacity: 1,
+        'underlay-color': 'data(auditCycleColor)',
+        'underlay-opacity': 0.18,
+        'underlay-padding': 4,
+        'z-index': 999,
+      },
+    },
     { selector: 'node.isParent', style: { 'font-weight': 'bold' } },
     {
       selector: 'node:selected',
       style: {
         'background-color': colors.selectedFill,
         'border-color': colors.selectedRing,
-        'border-width': 3,
+        'outline-color': colors.selectedRing,
+        'outline-width': 2,
         color: colors.selectedText,
         'background-opacity': 1,
         opacity: 1,
@@ -97,23 +160,35 @@ export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey):
       selector: 'node.isVendor:selected',
       style: { 'background-color': colors.selectedFillVendor },
     },
+  ];
+}
+
+/***
+ * Shows softly tinted compound boundaries with bounded, prepared nested-depth opacity.
+ * @performance Keep grouping paint-only; do not add nested DOM surfaces or extra graph elements.
+ */
+function getCompoundStyles(colors: Palette): StylesheetJson {
+  return [
     {
       selector: 'node:parent, node:parent:selected',
       style: {
-        'background-opacity': 0.3,
-        'background-color': colors.selectedFill,
+        'background-opacity': 0.04,
+        'background-color': colors.compoundBg,
         color: colors.nodeText,
-        'border-width': 2,
+        'border-width': 1,
+        'border-opacity': 0.35,
         'border-color': colors.nodeBorder,
         'text-valign': 'top',
         'text-margin-y': -5,
-        padding: '10px',
-        'padding-top': '20px',
+        padding: '16px',
+        'text-background-color': colors.canvasBg,
+        'text-background-opacity': 0.85,
+        'text-background-padding': '3px',
         'text-halign': 'center',
         'font-size': 14,
         'font-weight': 'bold',
         'font-style': 'italic',
-        label: 'data(name)',
+        label: 'data(label)',
       },
     },
     {
@@ -123,6 +198,50 @@ export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey):
         'border-color': colors.nodeBorderVendor,
       },
     },
+    {
+      selector: 'node:parent.auditCycle, node:parent.auditCycle:selected',
+      style: {
+        'underlay-opacity': 0,
+        'border-color': 'data(auditCycleColor)',
+        'border-opacity': 0.8,
+        'outline-color': 'data(auditCycleColor)',
+        'outline-width': 2,
+        color: 'data(auditCycleColor)',
+      },
+    },
+  ];
+}
+
+/***
+ * Emits one numeric paint rule per visible depth, including depths created by detached endpoints.
+ * @performance Bound stylesheet size by hierarchy depth, not node count; no style callbacks.
+ */
+function getCompoundOpacityStyles(elements: ElementsDefinition): StylesheetJson {
+  const ids = new Set(elements.nodes.map(node => node.data.id));
+  const parents = new Map(
+    elements.nodes.flatMap(node => {
+      const { id, parent } = node.data;
+      return typeof id === 'string' && typeof parent === 'string' && ids.has(parent)
+        ? [[id, parent] as const]
+        : [];
+    })
+  );
+  const opacities = createCompoundOpacityIndex(parents, new Set());
+  return [...new Set(opacities.values())].map(opacity => ({
+    selector: `node:parent[compoundFillOpacity = ${opacity}]`,
+    style: { 'background-opacity': opacity },
+  }));
+}
+
+/***
+ * Keeps ordinary directed edges opaque to avoid the extra rendering cost of translucent arrows.
+ * @performance
+ * Hushed edges are an intentional interaction state, not the base rendering policy. Retain arrows
+ * and loop-capable routing: cheaper edge styles must not silently remove dependency direction or
+ * lifted self-loops. Measure and discuss those visual tradeoffs before changing this baseline.
+ */
+function getEdgeBaseStyles(colors: Palette): StylesheetJson {
+  return [
     {
       selector: 'edge',
       style: {
@@ -131,7 +250,10 @@ export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey):
         'target-arrow-shape': 'chevron',
         'target-arrow-fill': 'filled',
         'line-color': colors.edge,
-        'curve-style': 'straight',
+        // Bezier routing keeps lifted self-loops renderable; line endpoints avoid invalid compound overlaps.
+        'curve-style': 'bezier',
+        'source-endpoint': 'outside-to-line',
+        'target-endpoint': 'outside-to-line',
         opacity: 1,
         'line-opacity': 1,
       },
@@ -153,6 +275,12 @@ export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey):
         'source-arrow-color': colors.weightXl,
       },
     },
+  ];
+}
+
+/*** Applies the existing aggregate dependency-weight buckets. */
+function getEdgeWeightStyles(colors: Palette, thresholds: readonly number[]): StylesheetJson {
+  return [
     { selector: 'edge[weight <= 1]', style: { label: '' } },
     {
       selector: `edge[weight > 1][weight <= ${thresholds[0]}]`,
@@ -179,13 +307,32 @@ export function getStyle(filteredElements: ElementsDefinition, theme: ThemeKey):
         'target-arrow-color': colors.weightXl,
       },
     },
+  ];
+}
+
+/*** Shows audit steps above compound content only for active cycle edges. */
+function getCycleEdgeStyles(colors: Palette): StylesheetJson {
+  return [
     {
-      selector: 'edge.packageCycle',
-      style: { 'line-color': '#d80303', 'target-arrow-color': '#d80303' },
-    },
-    {
-      selector: 'edge.packageCycle',
-      style: { 'line-color': '#d80303', 'target-arrow-color': '#d80303' },
+      selector: 'edge.auditCycle',
+      style: {
+        width: 6,
+        opacity: 1,
+        'line-opacity': 1,
+        'arrow-scale': 1.5,
+        'line-color': 'data(auditCycleColor)',
+        'target-arrow-color': 'data(auditCycleColor)',
+        color: 'data(auditCycleColor)',
+        label: 'data(auditCycleStep)',
+        'font-size': 12,
+        'font-weight': 'bold',
+        'text-background-color': colors.canvasBg,
+        'text-background-opacity': 0.9,
+        'text-background-padding': '3px',
+        'z-compound-depth': 'top',
+        'z-index-compare': 'manual',
+        'z-index': 9999,
+      },
     },
   ];
 }

package/src/screens/home/Home.tsx

@@ -1,48 +1,96 @@
 'use client';
-import type { ElementsDefinition } from 'cytoscape';
+import { useState } from 'react';
 
-import { useEffect, useState } from 'react';
-import { getGraphAction } from '@/app/actions/graph.actions';
 import Breadcrumb from '@/components/Breadcrumb';
 import Header from '@/components/Header';
-import Loader from '@/components/Loader';
-import Settings from '@/components/Settings';
-import { Cytoscape } from '@/components/Cytoscape';
+import ProjectLoadError from '@/components/ProjectLoadError';
 import { SettingsProvider } from '@/contexts/SettingsContext';
+import { useCycleSelection } from '@/features/audit/adapters/inbound/react/useCycleSelection';
+import { resolveProjectTreeNavigation } from '@/features/project-tree/application/use-cases/resolveProjectTreeNavigation';
+import { findProjectTreeNodeByGraphPackage } from '@/features/project-tree/utils/findProjectTreeNodeByGraphPackage';
+import { HomeGraph } from '@/screens/home/HomeGraph';
+import { HomeSidebar } from '@/screens/home/HomeSidebar';
+import type { Audit } from '@/types/audit';
+import type { CycleInspection } from '@/types/auditVisualization';
+import type { ProjectOverview } from '@/types/projectAnalysis';
+import type { ProjectAnalysisActionResult } from '@/types/projectAnalysisActionResult';
+import type { ProjectTreeNode } from '@/types/projectTree';
 
-export default function HomeScreen() {
+/*** Renders the PKGViz home screen and composes project navigation, diagnostics, and the graph. */
+export default function HomeScreen({ project }: HomeScreenProps) {
   const [currentPackage, setCurrentPackage] = useState<string>('');
-  const [packageGraph, setPackageGraph] = useState<ElementsDefinition | null>(null);
+  const packageGraph = project.ok ? project.value.graph : null;
+  const projectTree = project.ok ? project.value.tree : [];
+  const [selectedTreeId, setSelectedTreeId] = useState<string | null>(null);
+  const auditEvaluation = project.ok ? project.value.evaluation : null;
+  const projectError = project.ok ? null : project.error;
+  const cycleSelection = useCycleSelection(auditEvaluation?.cyclicPackages ?? EMPTY_CYCLES);
+  const [cycleInspection, setCycleInspection] = useState<CycleInspection | null>(null);
 
-  useEffect(() => {
-    if (!packageGraph) {
-      getGraphAction().then(setPackageGraph);
-    }
-  }, [packageGraph]);
+  /*** Navigates graph scope and mirrors the matching package selection in the project tree. */
+  const navigateToPackage = (path: string) => {
+    const packageName = normalizeGraphPackage(path);
+    const matchingTreeNode = findProjectTreeNodeByGraphPackage(projectTree, packageName);
+    setCurrentPackage(packageName);
+    setSelectedTreeId(matchingTreeNode?.id ?? null);
+  };
+
+  /*** Navigates only into packages with graph descendants; selecting a leaf keeps the current view. */
+  const selectProjectTreeNode = (node: ProjectTreeNode) => {
+    setSelectedTreeId(node.id);
+    setCurrentPackage(
+      resolveProjectTreeNavigation(
+        node,
+        packageGraph?.nodes.map(candidate => String(candidate.data.id ?? '')) ?? [],
+        currentPackage
+      )
+    );
+  };
 
   return (
     <>
       <Header title="nav.packages">
-        <Breadcrumb
-          path={currentPackage.replace(/\./g, '/')}
-          onNavigate={(path: string) => setCurrentPackage(path.replace(/\//g, '.'))}
-        />
+        <Breadcrumb path={currentPackage.replace(/\./g, '/')} onNavigate={navigateToPackage} />
       </Header>
-
       <SettingsProvider>
-        <main data-testid="main" className="flex flex-1 flex-row dark:bg-[#171717]">
-          <Settings />
-          {packageGraph ? (
-            <Cytoscape
+        <main
+          data-testid="main"
+          className="flex min-h-0 min-w-0 flex-1 flex-row overflow-hidden dark:bg-[#171717]"
+        >
+          <HomeSidebar
+            evaluation={auditEvaluation}
+            projectTree={projectTree}
+            selectedTreeId={selectedTreeId}
+            onProjectTreeSelect={selectProjectTreeNode}
+            cycleSelection={cycleSelection}
+            inspectedCycleId={cycleInspection?.id ?? null}
+            onCycleInspectionChange={setCycleInspection}
+          />
+          {projectError ? (
+            <ProjectLoadError message={projectError} />
+          ) : (
+            <HomeGraph
               currentPackage={currentPackage}
-              setCurrentPackage={setCurrentPackage}
+              cycleHighlights={cycleSelection.highlights}
+              cycleInspection={cycleInspection}
               packageGraph={packageGraph}
+              setCurrentPackage={navigateToPackage}
+              onCloseInspection={() => setCycleInspection(null)}
             />
-          ) : (
-            <Loader />
           )}
         </main>
       </SettingsProvider>
     </>
   );
 }
+
+const EMPTY_CYCLES: NonNullable<Audit['evaluation']>['cyclicPackages'] = [];
+
+interface HomeScreenProps {
+  readonly project: ProjectAnalysisActionResult<ProjectOverview>;
+}
+
+/*** Normalizes graph navigation paths to the package-id representation used by Cytoscape. */
+function normalizeGraphPackage(path: string): string {
+  return path.replaceAll('/', '.').replace(/^\.+|\.+$/g, '');
+}