HenriqueCSJ · HenriqueCSJ · Jan 10, 2026 · Jan 10, 2026 · Jan 10, 2026 · Jan 10, 2026
diff --git a/.zenodo.json b/.zenodo.json
@@ -1,6 +1,6 @@
 {
   "title": "Q-Shape - Quantitative Shape Analyzer",
-  "version": "v1.4.0",
+  "version": "v1.5.0",
   "description": "Q-Shape: Advanced coordination geometry analysis using Continuous Shape Measures (CShM). A web-based tool for analyzing molecular coordination geometries with 92 reference geometries (CN 2-12, 20, 24, 48, 60), real-time 3D visualization, and comprehensive quality metrics.",
   "creators": [
     {

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,10 +9,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 🎯 Overview
 
-**Piano Stool Complex Support** - This release adds comprehensive support for half-sandwich (piano stool) complexes, a major class of organometallic compounds that were previously not properly analyzed by the software.
+**Multi-Structure Batch Analysis & Piano Stool Complex Support** - This major release introduces comprehensive batch analysis for multi-structure files (XYZ and CIF), along with support for half-sandwich (piano stool) complexes.
 
 ### ✨ New Features
 
+#### Multi-Structure Batch Analysis (Major Feature)
+- **Problem:** Users could only analyze one structure at a time, making it tedious to analyze files with multiple conformers or structures
+- **Solution:** Full batch analysis mode with parallel structure handling
+- **Implementation:**
+  - New `useFileUpload` hook with multi-structure support
+  - New `useBatchAnalysis` hook for orchestrating batch operations
+  - Unified input parser supporting multi-structure XYZ and CIF files
+  - New data model with `Structure` and `ParsedFile` types
+
+**New Components:**
+- `BatchModePanel.jsx` - Structure selector and batch controls
+- `BatchSummaryTable.jsx` - Visual overview of all analyzed structures
+- `ManualOverridePanel.jsx` - Per-structure parameter overrides
+
+**Batch Report Features:**
+- Comprehensive batch PDF report with per-structure details
+- Q-Shape analysis overview for each structure
+- Quality Metrics, Bond Statistics, Coordinating Atoms tables
+- Ligand Groups Analysis section
+- Wide summary CSV export (one row per structure)
+- Long detailed CSV export (all geometries for all structures)
+
+**UI Improvements:**
+- Context-aware action buttons (batch vs single mode)
+- Progress tracking for batch operations
+- Softer color scheme for selected rows
+- TrackballControls for unrestricted 360° 3D rotation
+
 #### Piano Stool (Half-Sandwich) Complex Recognition
 - **Problem:** Piano stool complexes like [CpMn(CO)₃] were analyzed as CN=8 (all atoms separately), giving poor CShM values (>15.0)
 - **Solution:** Automatic pattern detection and geometry-aware analysis

diff --git a/CITATION.cff b/CITATION.cff
@@ -10,7 +10,7 @@ authors:
 repository-code: "https://github.com/HenriqueCSJ/q-shape"
 url: "https://henriquecsj.github.io/q-shape"
 license: MIT
-version: "v1.4.0"
+version: "v1.5.0"
 date-released: "2025-11-25"
 keywords:
   - "coordination chemistry"
@@ -26,7 +26,7 @@ identifiers:
 preferred-citation:
   type: software
   title: "Q-Shape - Quantitative Shape Analyzer"
-  version: "v1.4.0"
+  version: "v1.5.0"
   year: 2025
   authors:
     - given-names: Henrique

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 ![Q-Shape Logo](https://img.shields.io/badge/Q--Shape-Molecular%20Geometry%20Analysis-blue?style=for-the-badge&logo=react&logoColor=white)
 
-[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg?style=flat-square)](https://github.com/HenriqueCSJ/q-shape/releases/tag/v1.4.0)
+[![Version](https://img.shields.io/badge/version-1.5.0-blue.svg?style=flat-square)](https://github.com/HenriqueCSJ/q-shape/releases/tag/v1.5.0)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17717110.svg)](https://doi.org/10.5281/zenodo.17717110)
 [![MIT License](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://choosealicense.com/licenses/mit/)
 [![Website](https://img.shields.io/website?down_color=red&down_message=offline&style=flat-square&up_color=green&up_message=online&url=https%3A%2F%2Fhenriquecsj.github.io%2Fq-shape)](https://henriquecsj.github.io/q-shape)
@@ -46,6 +46,16 @@
 ✅ **Comprehensive Metrics** - Bond statistics, angular distortion, quality scoring
 ✅ **PDF Reports** - Professional output suitable for publication
 
+### Multi-Structure Batch Analysis (v1.5.0)
+
+✅ **Batch Processing** - Analyze multiple structures from a single file
+✅ **Multi-Structure XYZ/CIF Support** - Load files with multiple conformers or structures
+✅ **Batch Summary Table** - Visual overview of all analyzed structures at a glance
+✅ **Parallel Analysis** - Run intensive analysis on all structures with progress tracking
+✅ **Batch PDF Reports** - Comprehensive reports with per-structure details
+✅ **CSV Export** - Wide summary or detailed geometry results for all structures
+✅ **Structure Selector** - Navigate between structures with instant visualization updates
+
 ### Analysis Modes
 
 **Standard Mode** (~5-10 seconds)
@@ -70,13 +80,21 @@ Visit **[https://henriquecsj.github.io/q-shape](https://henriquecsj.github.io/q-
 
 ### Basic Workflow
 
-1. **Upload** your XYZ file (drag-and-drop or file picker)
+1. **Upload** your XYZ or CIF file (drag-and-drop or file picker)
 2. **Select** metal center (auto-detected or manual selection)
 3. **Adjust** coordination sphere radius if needed
 4. **Run** analysis (standard or intensive mode)
 5. **Visualize** results in 3D and review shape measures
 6. **Export** PDF report for your records
 
+### Batch Analysis Workflow (v1.5.0)
+
+1. **Upload** a multi-structure XYZ or CIF file
+2. **Review** the batch summary table showing all structures
+3. **Run Batch Analysis** to analyze all structures with intensive mode
+4. **Navigate** between structures using the structure selector
+5. **Export** batch PDF report or CSV files with all results
+
 ---
 
 ## Scientific Basis
@@ -339,7 +357,7 @@ If you use Q-Shape in your research, please cite:
 
 **APA:**
 ```
-Castro Silva Junior, H. (2025). Q-Shape - Quantitative Shape Analyzer (v1.4.0).
+Castro Silva Junior, H. (2025). Q-Shape - Quantitative Shape Analyzer (v1.5.0).
 Zenodo. https://doi.org/10.5281/zenodo.17717110
 ```
 
@@ -348,7 +366,7 @@ Zenodo. https://doi.org/10.5281/zenodo.17717110
 @software{qshape2025,
   author = {Castro Silva Junior, Henrique},
   title = {Q-Shape - Quantitative Shape Analyzer},
-  version = {1.4.0},
+  version = {1.5.0},
   year = {2025},
   doi = {10.5281/zenodo.17717110},
   url = {https://doi.org/10.5281/zenodo.17717110},

diff --git a/TESTING.md b/TESTING.md
@@ -0,0 +1,151 @@
+# Q-Shape v1.5.0 Testing Checklist
+
+## Automated Tests
+
+Run all tests with:
+```bash
+npm test
+```
+
+### Unit Test Coverage
+
+#### 1. File Parser (`src/utils/parseInput.test.js`)
+- [x] Single XYZ parsing
+- [x] Multi-frame XYZ parsing (frame count, IDs, warnings)
+- [x] CIF parsing with Cartesian coordinates
+- [x] CIF parsing with fractional coordinates (unit cell conversion)
+- [x] Multiple CIF data blocks handling
+- [x] Format auto-detection from content and extension
+- [x] Error handling for malformed files
+- [x] Element symbol normalization
+- [x] Large coordinate warnings
+
+#### 2. Batch Analysis
+- [x] Batch run returns results per structure
+- [x] Progress tracking during batch operations
+- [x] Structure override storage and retrieval
+- [x] Apply override to all structures
+
+#### 3. Report Generation
+- [x] Long-format CSV contains all (structure, geometry) rows
+- [x] Wide-format CSV contains one row per structure
+- [x] Batch PDF includes all geometries per structure
+
+---
+
+## Manual E2E Checklist
+
+### Setup
+1. Run `npm start`
+2. Open browser to http://localhost:3000
+
+### A. Single Structure XYZ Upload
+- [ ] Upload a single-structure `.xyz` file
+- [ ] Verify metal center auto-detection
+- [ ] Verify coordination radius auto-detection
+- [ ] Verify geometry analysis completes
+- [ ] Verify 3D visualization renders correctly
+- [ ] Verify "Single Structure Mode" indicator shows
+- [ ] Run intensive analysis
+- [ ] Generate PDF report - verify ALL geometries are included
+- [ ] Export CSV - verify all geometry results are included
+
+### B. Multi-Structure XYZ Upload
+- [ ] Upload a multi-frame `.xyz` file (trajectory)
+- [ ] Verify "Batch Mode: X structures detected" message appears
+- [ ] Verify structure selector dropdown appears with all frames
+- [ ] Switch between structures using selector
+- [ ] Verify 3D visualization updates on each structure switch
+- [ ] Verify analysis results update for each structure
+- [ ] Verify structure ID shows in results panel
+- [ ] Click "Analyze All Structures"
+- [ ] Verify progress indicator shows
+- [ ] Verify batch summary table populates with results
+- [ ] Verify clicking a row in summary table selects that structure
+- [ ] Verify selected row is highlighted in batch summary
+
+### C. CIF File Upload
+- [ ] Upload a single-block `.cif` file
+- [ ] Verify atoms are NOT cramped together (proper Cartesian conversion)
+- [ ] Verify metal center and geometry detection work
+- [ ] Upload a multi-block `.cif` file
+- [ ] Verify all blocks appear as separate structures
+- [ ] Verify batch mode activates
+
+### D. Manual Override Panel
+- [ ] Click "Show Manual Overrides"
+- [ ] Change metal center
+- [ ] Verify analysis reruns with new metal
+- [ ] Change coordination radius
+- [ ] Verify CN updates
+- [ ] Use "Find Radius for Target CN" feature
+- [ ] In batch mode: click "Apply to all" for metal
+- [ ] In batch mode: click "Apply to all" for radius
+
+### E. Batch Export (Batch Mode Only)
+- [ ] Click "Batch PDF Report"
+- [ ] Verify PDF contains batch summary table
+- [ ] Verify PDF contains per-structure detail sections with ALL geometries
+- [ ] Click "Summary CSV (Wide)"
+- [ ] Verify one row per structure with best match
+- [ ] Click "All Geometries CSV (Long)"
+- [ ] Verify multiple rows per structure (all geometries)
+- [ ] Verify structure IDs are correct in CSV
+
+### F. State Reset on New Upload
+- [ ] Upload file A
+- [ ] Run analysis, get results
+- [ ] Upload file B (different file)
+- [ ] Verify batch results from file A are cleared
+- [ ] Verify selected structure resets to 0
+- [ ] Verify no lingering data from previous file
+
+### G. 3D Visualization Re-render
+- [ ] Upload multi-structure file
+- [ ] Select structure 1 - verify 3D renders correctly
+- [ ] Select structure 2 - verify 3D updates/realigns
+- [ ] Select structure 3 - verify 3D updates/realigns
+- [ ] Select geometry 2 in results - verify ideal polyhedron updates
+- [ ] Select geometry 1 in results - verify ideal polyhedron updates
+
+### H. Intensive Analysis in Batch Mode
+- [ ] Upload multi-structure file
+- [ ] Select structure 2
+- [ ] Run intensive analysis
+- [ ] Verify intensive analysis runs for structure 2 (not structure 1)
+- [ ] Verify results show for structure 2
+- [ ] Verify batch results for structure 2 are updated
+
+---
+
+## Regression Checklist
+
+These are bugs that occurred during development and must be prevented:
+
+1. [ ] CIF upload does NOT produce "Invalid atom count in XYZ header" error
+2. [ ] Batch UI controls appear BEFORE batch results exist (not gated on batchResults.length > 0)
+3. [ ] No JSX syntax errors ("Adjacent JSX elements must be wrapped")
+4. [ ] No reportGenerator.js syntax errors on build
+5. [ ] No ESLint undefined variable errors (additionalMetrics, permCount)
+6. [ ] No runtime error "prev is not iterable" after CIF load
+7. [ ] Report/CSV exports include ALL geometries, not just best match
+8. [ ] Batch results clear on new file upload
+9. [ ] Polyhedra alignment updates for ALL structures/geometries selected
+
+---
+
+## Performance Notes
+
+- Multi-frame files with >50 structures may be slow to batch analyze
+- Intensive analysis takes ~5-30 seconds per structure depending on CN
+- Batch PDF generation may take a few seconds for many structures
+
+---
+
+## Browser Compatibility
+
+Tested on:
+- [ ] Chrome (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Edge (latest)
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "q-shape",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Quantitative Shape Analyzer for Coordination Geometry Analysis",
   "homepage": "https://HenriqueCSJ.github.io/q-shape",
   "private": true,