fix: resolve 11 bugs from full codebase audit

- fix: `not self.df` crash in _auto_map_fields (ValueError on every data load)
- fix: template load without re-analysis silently producing wrong output
- fix: combed field crash when field.length is None
- fix: date serial strings ("45000") not converted to DD/MM/YYYY
- fix: startup crash on locked-down school networks (fallback makedirs)
- fix: Excel file handle leak locking .xlsx on Windows
- fix: AppSettings encoding mismatch (non-ASCII school names corrupted)
- fix: TemplateConfig.from_file() unhandled OSError
- fix: orphaned .tmp files on os.replace() failure (network drives)
- fix: stale preview cache across different PDFs (added hash key)
- fix: Windows download URL 404 in GitHub Releases (EXE rename)
- fix: clear_cache() filter updated for new cache filename format
- docs: update release notes for v2.10

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mrdavearms

.github/workflows/release.yml

@@ -45,20 +45,22 @@ jobs:
       - name: Build .exe
         run: python -m PyInstaller BulkPDFGenerator.spec --clean --noconfirm
 
-      - name: Verify build output
+      - name: Verify build output and rename
         run: |
           if (!(Test-Path "dist/Bulk PDF Generator.exe")) {
             Write-Error "Build failed — .exe not found"
             exit 1
           }
-          $size = (Get-Item "dist/Bulk PDF Generator.exe").Length / 1MB
-          Write-Host "Built: Bulk PDF Generator.exe ($([math]::Round($size, 1)) MB)"
+          # Rename to dotted form so GitHub Release download URLs match
+          Rename-Item "dist/Bulk PDF Generator.exe" "Bulk.PDF.Generator.exe"
+          $size = (Get-Item "dist/Bulk.PDF.Generator.exe").Length / 1MB
+          Write-Host "Built: Bulk.PDF.Generator.exe ($([math]::Round($size, 1)) MB)"
         shell: pwsh
 
       - uses: actions/upload-artifact@v4
         with:
           name: windows-exe
-          path: dist/Bulk PDF Generator.exe
+          path: dist/Bulk.PDF.Generator.exe
           retention-days: 1
 
   # ── macOS .app build ────────────────────────────────────────
@@ -239,5 +241,5 @@ jobs:
 
             </details>
           files: |
-            artifacts/Bulk PDF Generator.exe
+            artifacts/Bulk.PDF.Generator.exe
             artifacts/Bulk.PDF.Generator.macOS.dmg

RELEASE_NOTES.md

@@ -11,16 +11,28 @@
      comment and start fresh for the next version.
 -->
 
-## What's new in v2.9
+## What's new in v2.10
 
-### Major performance improvements — especially on Mac
+### Reliability and stability fixes
 
-- **Fixed: app freezing and lagging on macOS** — The app was nearly unusable on Mac, with tabs not responding, field selection freezing the window, and general sluggishness throughout. This release completely fixes those issues. Field previews now render in the background instead of freezing the window, and all bulk operations (Select All, loading data, switching tabs) are dramatically faster.
+This release fixes a number of issues discovered during a full codebase audit. Most of these affect edge cases that teachers on school networks are most likely to encounter.
 
-- **Smoother field preview** — Clicking through fields in the Analyse tab now feels instant. A fast preview appears immediately, then a high-quality version follows a moment later — no more waiting for each click.
+- **Fixed: "Failed to load data" error after loading a spreadsheet** — A bug caused the app to show a confusing error message every time you loaded an Excel file after analysing a template. Auto-mapping of fields now works correctly.
 
-- **Faster data loading** — Loading a spreadsheet with hundreds of rows no longer causes a visible pause. The "Select All" operation and field mapping panel both update much more efficiently.
+- **Fixed: loading a saved template could produce wrong output** — If you loaded a saved template on a fresh launch without re-analysing, the app would silently skip your saved field mappings, data types, and combed field settings. Templates now restore all settings automatically.
 
-- **Smoother scrolling and hover effects** — Mouse hover highlighting and scrolling in all lists and dialogs is now throttled to prevent unnecessary work, making the whole app feel more responsive.
+- **Fixed: date fields showing numbers instead of dates** — Date columns stored as serial numbers in Excel (e.g. "45000" instead of "17/03/2023") were being written as-is into the PDF. They are now correctly converted to DD/MM/YYYY format.
 
-- **Dialogs no longer flicker** — The School Setup, Template Name, and Field Type dialogs now appear cleanly without the brief flicker that was visible on macOS.
+- **Fixed: app crashing on startup on some school networks** — On machines where both the Documents folder and the local app data folder are unavailable (common with GPO-locked school networks), the app would crash before any window appeared. It now falls back gracefully.
+
+- **Fixed: Excel file stays locked after loading** — On Windows, the Excel file remained locked after you loaded it, preventing you from editing or re-saving it until you restarted the app. The file is now released immediately after loading.
+
+- **Fixed: combed fields crashing on certain PDFs** — Combed fields where the PDF didn't report a character limit could crash the app. These are now handled safely.
+
+- **Fixed: settings corruption with non-ASCII school names** — If your school name contained accented or special characters, it could become garbled after restarting the app on Windows. Settings are now always read and written as UTF-8.
+
+- **Fixed: preview cache showing wrong PDF** — If you switched between two PDF templates with the same number of pages, the preview could show pages from the previous template. Each PDF now has its own cache.
+
+- **Fixed: Windows download link on GitHub Releases** — The download link for the Windows .exe in previous releases could return a 404 error. This is now fixed.
+
+- **Improved: template file and settings resilience** — Saved templates and settings files are now more resilient to file system errors on network drives. Temporary files are cleaned up properly if a save is interrupted.

combed_filler.py

@@ -54,17 +54,20 @@ def fill_field(
         # Clean and prepare text
         text = str(text_value).strip()
 
+        # Use combed_fields count as the canonical capacity
+        capacity = len(field.combed_fields) if field.combed_fields else (field.length or 0)
+
         # Truncate if too long
-        if len(text) > field.length:
-            text = text[:field.length]
+        if capacity and len(text) > capacity:
+            text = text[:capacity]
 
         # Determine alignment
-        if self.align == 'right' and len(text) < field.length:
+        if self.align == 'right' and capacity and len(text) < capacity:
             # Right-align by padding left
-            text = text.rjust(field.length)
-        elif self.padding and len(text) < field.length:
+            text = text.rjust(capacity)
+        elif self.padding and capacity and len(text) < capacity:
             # Pad with spaces to fill all boxes
-            text = text.ljust(field.length)
+            text = text.ljust(capacity)
 
         # Create field mapping
         field_values = {}
@@ -76,7 +79,7 @@ def fill_field(
                 field_values[field_name] = char
 
         # Fill remaining boxes with empty string (or spaces if padding)
-        for idx in range(len(text), field.length):
+        for idx in range(len(text), capacity):
             if idx < len(field.combed_fields):
                 field_name = field.combed_fields[idx]
                 field_values[field_name] = ' ' if self.padding else ''
@@ -157,10 +160,11 @@ def validate_overflow(
             # Not a combed field - no overflow possible
             return result
 
-        if len(text) > field.length:
+        capacity = len(field.combed_fields) if field.combed_fields else (field.length or 0)
+        if capacity and len(text) > capacity:
             result['is_valid'] = False
             result['will_truncate'] = True
-            result['truncated_text'] = text[:field.length]
+            result['truncated_text'] = text[:capacity]
 
         return result
 

models.py

@@ -118,6 +118,8 @@ def from_file(cls, filepath: str) -> 'TemplateConfig':
             raise ValueError(f"Template file is not valid JSON: {filepath}") from e
         except (TypeError, KeyError) as e:
             raise ValueError(f"Template file has missing or invalid fields: {filepath}") from e
+        except OSError as e:
+            raise ValueError(f"Cannot read template file: {filepath}") from e
 
     def save_to_file(self, filepath: str):
         """Save to JSON file atomically to prevent corruption on crash."""
@@ -128,7 +130,14 @@ def save_to_file(self, filepath: str):
                                          encoding='utf-8') as tmp:
             tmp.write(self.to_json())
             tmp_path = tmp.name
-        os.replace(tmp_path, filepath)
+        try:
+            os.replace(tmp_path, filepath)
+        except OSError:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
 
 
 @dataclass
@@ -171,7 +180,7 @@ def from_json(cls, json_str: str) -> 'AppSettings':
     def from_file(cls, filepath: str) -> 'AppSettings':
         """Load from JSON file."""
         try:
-            with open(filepath, 'r') as f:
+            with open(filepath, 'r', encoding='utf-8') as f:
                 return cls.from_json(f.read())
         except (FileNotFoundError, PermissionError, OSError,
                 json.JSONDecodeError, TypeError, KeyError):
@@ -186,7 +195,14 @@ def save_to_file(self, filepath: str):
                                          encoding='utf-8') as tmp:
             tmp.write(self.to_json())
             tmp_path = tmp.name
-        os.replace(tmp_path, filepath)
+        try:
+            os.replace(tmp_path, filepath)
+        except OSError:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
 
     @classmethod
     def get_defaults(cls) -> 'AppSettings':

pdf_generator.py

@@ -160,8 +160,13 @@ def _resolve_data_dir() -> str:
             os.environ.get('LOCALAPPDATA', os.path.expanduser('~')),
             'BulkPDFGenerator'
         )
-        os.makedirs(fallback, exist_ok=True)
-        return fallback
+        try:
+            os.makedirs(fallback, exist_ok=True)
+            return fallback
+        except OSError:
+            # Last resort: use a temp directory so the app can still launch
+            import tempfile
+            return tempfile.mkdtemp(prefix='BulkPDFGenerator_')
 
 
 # Import our new modules
@@ -1515,6 +1520,36 @@ def load_template_config(self, filepath: str):
             self.pdf_template_path.set(self.current_template.pdf_path)
             self.template_name_var.set(self.current_template.template_name)
 
+            # If analyzed_fields is empty, silently re-analyze the PDF so that
+            # data types, mappings, and combed logic are all functional.
+            pdf_path = self.current_template.pdf_path
+            if not self.analyzed_fields and pdf_path and os.path.exists(pdf_path):
+                with PDFAnalyzer(pdf_path) as analyzer:
+                    self.analyzed_fields = analyzer.analyze_fields()
+
+                # Restore field type overrides from the template
+                if self.current_template.field_type_overrides:
+                    for field in self.analyzed_fields:
+                        override = self.current_template.field_type_overrides.get(field.field_name)
+                        if override:
+                            field.field_type = override.get('field_type', field.field_type)
+                            if override.get('length') is not None:
+                                field.length = override['length']
+                                field.is_combed = (field.field_type == 'Text-Combed')
+
+                # Initialize preview generator for the loaded PDF
+                self._close_preview_generator()
+                cache_dir = os.path.join(self.settings.templates_directory, '.preview_cache')
+                self.preview_generator = VisualPreviewGenerator(pdf_path, cache_dir)
+                self.preview_generator.__enter__()
+
+                def _on_preview_complete(photo):
+                    self.preview_image = photo
+                self._preview_renderer = PreviewRenderer(
+                    self.preview_generator, self.root,
+                    self.preview_canvas, _on_preview_complete,
+                )
+
             # Restore saved data types to analyzed fields if they exist
             saved_types = self.current_template.field_data_types or {}
             if saved_types and self.analyzed_fields:
@@ -1539,6 +1574,9 @@ def load_template_config(self, filepath: str):
                     if field.field_name in saved_critical:
                         field.is_critical = True
 
+            # Enable Tab 2 and refresh mappings
+            if self.analyzed_fields:
+                self.notebook.tab(2, state='normal')
             self._refresh_tab2_mappings()
 
             # Show template-specific banner message if mappings were restored
@@ -2531,7 +2569,7 @@ def _on_mapping_changed(self, field_name: str, combo: ttk.Combobox, status_lbl:
 
     def _auto_map_fields(self):
         """Apply smart-guess mappings to all fields, overwriting existing mappings."""
-        if not self.df or not self.analyzed_fields:
+        if self.df is None or not self.analyzed_fields:
             return
         column_lower = {col.lower(): col for col in self.df.columns}
         for field in self.analyzed_fields:
@@ -2902,15 +2940,15 @@ def load_data_tab3(self):
                 except UnicodeDecodeError:
                     self.df = pd.read_csv(excel_path, encoding='latin-1')
             else:
-                xl = pd.ExcelFile(excel_path)
-                sheet_names = xl.sheet_names
-                if len(sheet_names) == 1:
-                    chosen_sheet = sheet_names[0]
-                else:
-                    chosen_sheet = self._pick_excel_sheet(sheet_names)
-                    if chosen_sheet is None:
-                        return  # User cancelled the dialog
-                self.df = xl.parse(chosen_sheet, dtype=str)
+                with pd.ExcelFile(excel_path) as xl:
+                    sheet_names = xl.sheet_names
+                    if len(sheet_names) == 1:
+                        chosen_sheet = sheet_names[0]
+                    else:
+                        chosen_sheet = self._pick_excel_sheet(sheet_names)
+                        if chosen_sheet is None:
+                            return  # User cancelled the dialog
+                    self.df = xl.parse(chosen_sheet, dtype=str)
 
             # Clean column names (strip whitespace, lowercase for matching)
             self.df.columns = [str(col).strip() for col in self.df.columns]
@@ -3399,11 +3437,22 @@ def format_value_tab3(val, data_type: str = "text"):
         # Date type: handle pandas-stringified datetimes e.g. "2024-05-01 00:00:00"
         # (occurs when dtype=str is used on read_excel — Timestamps become strings)
         if data_type == "date" and isinstance(val, str):
-            for fmt in ('%Y-%m-%d %H:%M:%S', '%Y-%m-%d'):
+            for fmt in ('%Y-%m-%d %H:%M:%S.%f', '%Y-%m-%d %H:%M:%S', '%Y-%m-%d'):
                 try:
                     return datetime.strptime(val.strip(), fmt).strftime('%d/%m/%Y')
                 except ValueError:
                     pass
+            # Handle numeric serial strings produced by dtype=str
+            # (e.g. "45000" or "45000.0" instead of a formatted date)
+            try:
+                serial = int(float(val.strip()))
+                if 1 <= serial <= 2958465:
+                    from datetime import timedelta
+                    excel_epoch = datetime(1899, 12, 30)
+                    date_obj = excel_epoch + timedelta(days=serial)
+                    return date_obj.strftime('%d/%m/%Y')
+            except (ValueError, TypeError):
+                pass
 
         # Date type: convert Excel serial numbers to DD/MM/YYYY
         if data_type == "date" and isinstance(val, (int, float)):

visual_preview.py

@@ -4,6 +4,7 @@
 Handles PDF page rendering and field highlighting for visual preview.
 """
 
+import hashlib
 import os
 import tempfile
 from collections import OrderedDict
@@ -158,8 +159,9 @@ def _get_page_image(self, page_num: int, dpi: int) -> Image.Image:
             self._cached_pages.move_to_end(cache_key)
             return self._cached_pages[cache_key]
 
-        # Check disk cache
-        cache_filename = f"page_{page_num}_dpi_{dpi}.png"
+        # Check disk cache (include PDF identity to prevent stale cross-PDF hits)
+        pdf_hash = hashlib.md5(self.pdf_path.encode()).hexdigest()[:8]
+        cache_filename = f"{pdf_hash}_page_{page_num}_dpi_{dpi}.png"
         cache_path = os.path.join(self.cache_dir, cache_filename)
 
         if os.path.exists(cache_path):
@@ -192,7 +194,7 @@ def clear_cache(self):
         # Clear disk cache (only app-generated files, with error handling)
         if os.path.exists(self.cache_dir):
             for file in os.listdir(self.cache_dir):
-                if file.startswith('page_') and file.endswith('.png'):
+                if file.endswith('.png') and '_page_' in file:
                     try:
                         os.remove(os.path.join(self.cache_dir, file))
                     except OSError: