{
    "sourceFile": "Documentation/02_Developer_Guide/06_GUI_Internals.md",
    "activeCommit": 0,
    "commits": [
        {
            "activePatchIndex": 11,
            "patches": [
                {
                    "date": 1745494847187,
                    "content": "Index: \n===================================================================\n--- \n+++ \n"
                },
                {
                    "date": 1745498111583,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -43,8 +43,41 @@\n *   Data is managed by a custom model (`PreviewTableModel`, inheriting `QAbstractTableModel`) which holds the structured prediction data.\r\n *   A `PreviewSortFilterProxyModel` is used to enable sorting and potentially filtering of the data displayed in the table.\r\n *   The table is updated asynchronously by the `PredictionHandler` via signals. Rows are color-coded based on predicted file status for easy visual identification.\r\n \r\n+### Preview Table Data Handling\r\n+\r\n+The `PreviewTableModel` receives a flat list of file prediction dictionaries from the `PredictionHandler` via the `prediction_results_ready` signal. Each dictionary in this list represents a single file and includes details such as its original path, predicted status, and the source asset it belongs to.\r\n+\r\n+Instead of directly displaying this flat list, the `PreviewTableModel` processes and transforms it into a structured list of rows (`self._table_rows`). This transformation involves:\r\n+\r\n+1.  **Grouping:** Files are grouped based on their `source_asset`.\r\n+2.  **Separation:** Within each asset group, files are separated into `main_files` (Mapped, Model, Error) and `additional_files` (Ignored, Extra, Unrecognised, Unmatched Extra).\r\n+3.  **Structuring Rows:** Rows are created for `self._table_rows` to represent the grouped data. Each row can contain information about a main file and/or an additional file, allowing for the display of additional files in a separate column aligned with the main files of the same asset. Empty rows are created if there are more additional files than main files for an asset to maintain alignment.\r\n+\r\n+The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display, handling the different columns and roles (Display, Tooltip, Foreground).\r\n+\r\n+The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n+\r\n+**Data Flow Diagram:**\r\n+\r\n+```mermaid\r\n+graph LR\r\n+    A[PredictionHandler] -- prediction_results_ready(flat_list) --> B(PreviewTableModel);\r\n+    subgraph PreviewTableModel\r\n+        C[set_data] -- Processes flat_list --> D{Internal Grouping & Transformation};\r\n+        D -- Creates --> E[_table_rows (Structured List)];\r\n+        F[data()] -- Reads from --> E;\r\n+    end\r\n+    B -- Provides data via data() --> G(QTableView via Proxy);\r\n+\r\n+    style B fill:#f9f,stroke:#333,stroke-width:2px\r\n+    style C fill:#ccf,stroke:#333,stroke-width:1px\r\n+    style D fill:#lightgrey,stroke:#333,stroke-width:1px\r\n+    style E fill:#ccf,stroke:#333,stroke-width:1px\r\n+    style F fill:#ccf,stroke:#333,stroke-width:1px\r\n+```\r\n+\r\n ## Logging\r\n \r\n A custom `QtLogHandler` is used to redirect log messages from the standard Python `logging` module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.\r\n \r\n"
                },
                {
                    "date": 1745502492623,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -41,9 +41,9 @@\n \r\n *   It uses a `QTableView` widget.\r\n *   Data is managed by a custom model (`PreviewTableModel`, inheriting `QAbstractTableModel`) which holds the structured prediction data.\r\n *   A `PreviewSortFilterProxyModel` is used to enable sorting and potentially filtering of the data displayed in the table.\r\n-*   The table is updated asynchronously by the `PredictionHandler` via signals. Rows are color-coded based on predicted file status for easy visual identification.\r\n+*   The table is updated asynchronously by the `PredictionHandler` via signals. Rows are color-coded based on predicted file status for easy visual identification, and also use alternating background colors per asset group for visual separation.\r\n \r\n ### Preview Table Data Handling\r\n \r\n The `PreviewTableModel` receives a flat list of file prediction dictionaries from the `PredictionHandler` via the `prediction_results_ready` signal. Each dictionary in this list represents a single file and includes details such as its original path, predicted status, and the source asset it belongs to.\r\n@@ -53,9 +53,9 @@\n 1.  **Grouping:** Files are grouped based on their `source_asset`.\r\n 2.  **Separation:** Within each asset group, files are separated into `main_files` (Mapped, Model, Error) and `additional_files` (Ignored, Extra, Unrecognised, Unmatched Extra).\r\n 3.  **Structuring Rows:** Rows are created for `self._table_rows` to represent the grouped data. Each row can contain information about a main file and/or an additional file, allowing for the display of additional files in a separate column aligned with the main files of the same asset. Empty rows are created if there are more additional files than main files for an asset to maintain alignment.\r\n \r\n-The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display, handling the different columns and roles (Display, Tooltip, Foreground).\r\n+The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display. It handles different columns and roles (Display, Tooltip, Foreground, and Background). The `Qt.ItemDataRole.BackgroundRole` is used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets.\r\n \r\n The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n \r\n **Data Flow Diagram:**\r\n@@ -76,8 +76,12 @@\n     style E fill:#ccf,stroke:#333,stroke-width:1px\r\n     style F fill:#ccf,stroke:#333,stroke-width:1px\r\n ```\r\n \r\n+### Application Styling\r\n+\r\n+The application style is explicitly set to 'Fusion' in `gui/main_window.py` to provide a more consistent look and feel across different operating systems, particularly to address styling inconsistencies observed on Windows 11. A custom `QPalette` is also applied to the application to adjust default colors within the 'Fusion' style, specifically to change the background color of list-like widgets and potentially other elements from a default dark blue to a more neutral grey.\r\n+\r\n ## Logging\r\n \r\n A custom `QtLogHandler` is used to redirect log messages from the standard Python `logging` module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.\r\n \r\n"
                },
                {
                    "date": 1745503615701,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -41,9 +41,9 @@\n \r\n *   It uses a `QTableView` widget.\r\n *   Data is managed by a custom model (`PreviewTableModel`, inheriting `QAbstractTableModel`) which holds the structured prediction data.\r\n *   A `PreviewSortFilterProxyModel` is used to enable sorting and potentially filtering of the data displayed in the table.\r\n-*   The table is updated asynchronously by the `PredictionHandler` via signals. Rows are color-coded based on predicted file status for easy visual identification, and also use alternating background colors per asset group for visual separation.\r\n+*   The table is updated asynchronously by the `PredictionHandler` via signals. Text colors are applied on a cell-by-cell basis to indicate the status of the specific file in that cell, and rows use alternating background colors per asset group for visual separation.\r\n \r\n ### Preview Table Data Handling\r\n \r\n The `PreviewTableModel` receives a flat list of file prediction dictionaries from the `PredictionHandler` via the `prediction_results_ready` signal. Each dictionary in this list represents a single file and includes details such as its original path, predicted status, and the source asset it belongs to.\r\n@@ -53,10 +53,13 @@\n 1.  **Grouping:** Files are grouped based on their `source_asset`.\r\n 2.  **Separation:** Within each asset group, files are separated into `main_files` (Mapped, Model, Error) and `additional_files` (Ignored, Extra, Unrecognised, Unmatched Extra).\r\n 3.  **Structuring Rows:** Rows are created for `self._table_rows` to represent the grouped data. Each row can contain information about a main file and/or an additional file, allowing for the display of additional files in a separate column aligned with the main files of the same asset. Empty rows are created if there are more additional files than main files for an asset to maintain alignment.\r\n \r\n-The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display. It handles different columns and roles (Display, Tooltip, Foreground, and Background). The `Qt.ItemDataRole.BackgroundRole` is used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets.\r\n+The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display. It handles different columns and roles (Display, Tooltip, Foreground, and Background).\r\n \r\n+*   `Qt.ItemDataRole.ForegroundRole`: Used to set the text color of individual cells based on the status of the file they represent. The \"Status\" column's text color indicates the status of the main file in that row, while the \"Additional Files\" column's text color indicates the status of the additional file in that row.\r\n+*   `Qt.ItemDataRole.BackgroundRole`: Used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets, improving visual separation between different asset groups.\r\n+\r\n The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n \r\n **Data Flow Diagram:**\r\n \r\n"
                },
                {
                    "date": 1745504735486,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -60,8 +60,25 @@\n *   `Qt.ItemDataRole.BackgroundRole`: Used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets, improving visual separation between different asset groups.\r\n \r\n The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n \r\n+### Preview Table Column Configuration\r\n+\r\n+The display and behavior of the columns in the `QTableView` are configured in `gui/main_window.py`. The current configuration is as follows:\r\n+\r\n+*   **Column Order (from left to right):**\r\n+    1.  Status\r\n+    2.  Predicted Asset\r\n+    3.  Details\r\n+    4.  Original Path\r\n+    5.  Additional Files\r\n+*   **Column Resizing:**\r\n+    *   Status: Resizes to content.\r\n+    *   Predicted Asset: Resizes to content.\r\n+    *   Details: Resizes to content.\r\n+    *   Original Path: Resizes to content (fixed width behavior).\r\n+    *   Additional Files: Stretches to fill available space.\r\n+\r\n **Data Flow Diagram:**\r\n \r\n ```mermaid\r\n graph LR\r\n"
                },
                {
                    "date": 1745505111225,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -55,9 +55,9 @@\n 3.  **Structuring Rows:** Rows are created for `self._table_rows` to represent the grouped data. Each row can contain information about a main file and/or an additional file, allowing for the display of additional files in a separate column aligned with the main files of the same asset. Empty rows are created if there are more additional files than main files for an asset to maintain alignment.\r\n \r\n The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display. It handles different columns and roles (Display, Tooltip, Foreground, and Background).\r\n \r\n-*   `Qt.ItemDataRole.ForegroundRole`: Used to set the text color of individual cells based on the status of the file they represent. The \"Status\" column's text color indicates the status of the main file in that row, while the \"Additional Files\" column's text color indicates the status of the additional file in that row.\r\n+*   `Qt.ItemDataRole.ForegroundRole`: Used to set the text color of individual cells based on the status of the file they represent. Coloring is applied to cells corresponding to a main file based on the main file's status, and to cells in the \"Additional Files\" column based on the additional file's status.\r\n *   `Qt.ItemDataRole.BackgroundRole`: Used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets, improving visual separation between different asset groups.\r\n \r\n The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n \r\n"
                },
                {
                    "date": 1745511665332,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -60,8 +60,11 @@\n *   `Qt.ItemDataRole.BackgroundRole`: Used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets, improving visual separation between different asset groups.\r\n \r\n The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n \r\n+\r\n+The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n+\r\n ### Preview Table Column Configuration\r\n \r\n The display and behavior of the columns in the `QTableView` are configured in `gui/main_window.py`. The current configuration is as follows:\r\n \r\n"
                },
                {
                    "date": 1745511707959,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -36,17 +36,30 @@\n The GUI includes an integrated preset editor panel. This allows users to interactively create, load, modify, and save preset `.json` files directly within the application. The editor typically uses standard UI widgets to display and edit the key fields of the preset structure.\r\n \r\n ## Preview Table\r\n \r\n+\r\n+## Preview Table\r\n+\r\n The preview table displays information about the queued input assets and the predicted classification of their files.\r\n \r\n *   It uses a `QTableView` widget.\r\n *   Data is managed by a custom model (`PreviewTableModel`, inheriting `QAbstractTableModel`) which holds the structured prediction data.\r\n *   A `PreviewSortFilterProxyModel` is used to enable sorting and potentially filtering of the data displayed in the table.\r\n *   The table is updated asynchronously by the `PredictionHandler` via signals. Text colors are applied on a cell-by-cell basis to indicate the status of the specific file in that cell, and rows use alternating background colors per asset group for visual separation.\r\n+*   A separate `QLabel` is used to display placeholder text (\"Please select a preset...\") when no preset is selected or no data is available. The visibility of the `QTableView` and this placeholder label are managed to show one or the other. Note that `QTableView` does not support `setPlaceholderText` directly.\r\n \r\n+### Preset Selection and Preview Triggering\r\n+\r\n+To prevent accidental processing with an unintended preset and ensure the user explicitly selects a configuration, the GUI does not select a preset by default on startup.\r\n+\r\n+*   The `populate_presets` method, which loads available presets into the `editor_preset_list` (`QListWidget`), is designed to add a special \"-- Select a Preset --\" item at the beginning of the list. This item serves as a visual indicator and a selectable \"no preset\" state.\r\n+*   After populating the list with actual presets, the `populate_presets` method explicitly sets the current item to this \"-- Select a Preset --\" placeholder. This is necessary because `QListWidget` implicitly selects the first item added if no selection is made, which would otherwise trigger the loading of the first available preset.\r\n+*   The `_load_selected_preset_for_editing` slot, connected to the `currentItemChanged` signal of the `editor_preset_list`, checks if the selected item is the placeholder.\r\n+*   If the placeholder is selected, the editor panel is cleared, the preview model's data is cleared, the placeholder label is made visible, and the `QTableView` is hidden. The `update_preview` method is *not* called in this case.\r\n+*   If a real preset item is selected, the corresponding preset file is loaded into the editor, the placeholder label is hidden, the `QTableView` is shown, and the `update_preview` method is called to generate and display the detailed preview based on the selected preset and currently added assets.\r\n+\r\n ### Preview Table Data Handling\r\n-\r\n The `PreviewTableModel` receives a flat list of file prediction dictionaries from the `PredictionHandler` via the `prediction_results_ready` signal. Each dictionary in this list represents a single file and includes details such as its original path, predicted status, and the source asset it belongs to.\r\n \r\n Instead of directly displaying this flat list, the `PreviewTableModel` processes and transforms it into a structured list of rows (`self._table_rows`). This transformation involves:\r\n \r\n"
                },
                {
                    "date": 1745511766750,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -37,29 +37,8 @@\n \r\n ## Preview Table\r\n \r\n \r\n-## Preview Table\r\n-\r\n-The preview table displays information about the queued input assets and the predicted classification of their files.\r\n-\r\n-*   It uses a `QTableView` widget.\r\n-*   Data is managed by a custom model (`PreviewTableModel`, inheriting `QAbstractTableModel`) which holds the structured prediction data.\r\n-*   A `PreviewSortFilterProxyModel` is used to enable sorting and potentially filtering of the data displayed in the table.\r\n-*   The table is updated asynchronously by the `PredictionHandler` via signals. Text colors are applied on a cell-by-cell basis to indicate the status of the specific file in that cell, and rows use alternating background colors per asset group for visual separation.\r\n-*   A separate `QLabel` is used to display placeholder text (\"Please select a preset...\") when no preset is selected or no data is available. The visibility of the `QTableView` and this placeholder label are managed to show one or the other. Note that `QTableView` does not support `setPlaceholderText` directly.\r\n-\r\n-### Preset Selection and Preview Triggering\r\n-\r\n-To prevent accidental processing with an unintended preset and ensure the user explicitly selects a configuration, the GUI does not select a preset by default on startup.\r\n-\r\n-*   The `populate_presets` method, which loads available presets into the `editor_preset_list` (`QListWidget`), is designed to add a special \"-- Select a Preset --\" item at the beginning of the list. This item serves as a visual indicator and a selectable \"no preset\" state.\r\n-*   After populating the list with actual presets, the `populate_presets` method explicitly sets the current item to this \"-- Select a Preset --\" placeholder. This is necessary because `QListWidget` implicitly selects the first item added if no selection is made, which would otherwise trigger the loading of the first available preset.\r\n-*   The `_load_selected_preset_for_editing` slot, connected to the `currentItemChanged` signal of the `editor_preset_list`, checks if the selected item is the placeholder.\r\n-*   If the placeholder is selected, the editor panel is cleared, the preview model's data is cleared, the placeholder label is made visible, and the `QTableView` is hidden. The `update_preview` method is *not* called in this case.\r\n-*   If a real preset item is selected, the corresponding preset file is loaded into the editor, the placeholder label is hidden, the `QTableView` is shown, and the `update_preview` method is called to generate and display the detailed preview based on the selected preset and currently added assets.\r\n-\r\n-### Preview Table Data Handling\r\n The `PreviewTableModel` receives a flat list of file prediction dictionaries from the `PredictionHandler` via the `prediction_results_ready` signal. Each dictionary in this list represents a single file and includes details such as its original path, predicted status, and the source asset it belongs to.\r\n \r\n Instead of directly displaying this flat list, the `PreviewTableModel` processes and transforms it into a structured list of rows (`self._table_rows`). This transformation involves:\r\n \r\n@@ -74,10 +53,8 @@\n \r\n The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n \r\n \r\n-The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n-\r\n ### Preview Table Column Configuration\r\n \r\n The display and behavior of the columns in the `QTableView` are configured in `gui/main_window.py`. The current configuration is as follows:\r\n \r\n"
                },
                {
                    "date": 1745933710211,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -0,0 +1,103 @@\n+# Developer Guide: GUI Internals\r\n+\r\n+This document provides technical details about the implementation of the Graphical User Interface (GUI) for developers.\r\n+\r\n+## Framework\r\n+\r\n+The GUI is built using `PySide6`, which provides Python bindings for the Qt framework.\r\n+\r\n+## Main Window (`gui/main_window.py`)\r\n+\r\n+The `MainWindow` class is the central component of the GUI application. It is responsible for:\r\n+\r\n+*   Defining the main application window structure and layout using PySide6 widgets.\r\n+*   Arranging the Preset Editor panel (left) and the Processing panel (right).\r\n+*   Setting up the menu bar, including the \"View\" menu for toggling the Log Console and Detailed File Preview.\r\n+*   Connecting user interactions (button clicks, drag-and-drop events, checkbox states, spinbox values) to corresponding methods (slots) within the `MainWindow` or other handler classes.\r\n+*   Managing the display of application logs in the UI console using a custom `QtLogHandler`.\r\n+*   Interacting with background handlers (`ProcessingHandler`, `PredictionHandler`) via Qt signals and slots to ensure thread-safe updates to the UI during long-running operations.\r\n+\r\n+## Threading and Background Tasks\r\n+\r\n+To keep the UI responsive during intensive operations like asset processing and file preview generation, the GUI utilizes background threads managed by `QThread`.\r\n+\r\n+*   **`ProcessingHandler` (`gui/processing_handler.py`):** This class is designed to run in a separate `QThread`. It manages the execution of the main asset processing pipeline for multiple assets concurrently using `concurrent.futures.ProcessPoolExecutor`. It submits individual asset processing tasks to the pool and monitors their completion. It uses Qt signals to communicate progress updates, file status changes, and overall processing completion back to the `MainWindow` on the main UI thread. It also handles the execution of optional Blender scripts via subprocess calls after processing. This handler now processes and utilizes enhanced data structures received from the core processing engine.\r\n+*   **`PredictionHandler` (`gui/prediction_handler.py`):** This class also runs in a separate `QThread`. It is responsible for generating the detailed file classification previews displayed in the preview table. It calls methods on the `AssetProcessor` (`get_detailed_file_predictions`) to perform the analysis in the background. It uses a `ThreadPoolExecutor` for potentially concurrent prediction tasks. Results are sent back to the `MainWindow` via Qt signals to update the preview table data. This handler also works with the enhanced data structures.\r\n+\r\n+## Communication (Signals and Slots)\r\n+\r\n+Communication between the main UI thread (`MainWindow`) and the background threads (`ProcessingHandler`, `PredictionHandler`) relies heavily on Qt's signals and slots mechanism. This is a thread-safe way for objects in different threads to communicate.\r\n+\r\n+*   Background handlers emit signals to indicate events (e.g., progress updated, file status changed, task finished).\r\n+*   The `MainWindow` connects slots (methods) to these signals. When a signal is emitted, the connected slot is invoked on the thread that owns the receiving object (the main UI thread for `MainWindow`), ensuring UI updates happen safely.\r\n+\r\n+## Preset Editor\r\n+\r\n+The GUI includes an integrated preset editor panel. This allows users to interactively create, load, modify, and save preset `.json` files directly within the application. The editor typically uses standard UI widgets to display and edit the key fields of the preset structure.\r\n+\r\n+## Preview Table\r\n+\r\n+\r\n+The `PreviewTableModel` receives enhanced data structures containing detailed file prediction information from the `PredictionHandler` via the `prediction_results_ready` signal. This richer data includes comprehensive details about each file and the asset set it belongs to.\r\n+\r\n+The `PreviewTableModel` is designed to process and display this enhanced file prediction data. Instead of directly displaying a flat list, it processes and transforms the richer data into a structured list of rows (`self._table_rows`). This transformation involves:\r\n+\r\n+1.  **Grouping:** Files are grouped based on their `source_asset`.\r\n+2.  **Separation:** Within each asset group, files are separated into `main_files` (Mapped, Model, Error) and `additional_files` (Ignored, Extra, Unrecognised, Unmatched Extra).\r\n+3.  **Structuring Rows:** Rows are created for `self._table_rows` to represent the grouped data. Each row can contain information about a main file and/or an additional file, allowing for the display of additional files in a separate column aligned with the main files of the same asset. Empty rows are created if there are more additional files than main files for an asset to maintain alignment.\r\n+\r\n+The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display. It handles different columns and roles (Display, Tooltip, Foreground, and Background).\r\n+\r\n+*   `Qt.ItemDataRole.ForegroundRole`: Used to set the text color of individual cells based on the status of the file they represent. Coloring is applied to cells corresponding to a main file based on the main file's status, and to cells in the \"Additional Files\" column based on the additional file's status.\r\n+*   `Qt.ItemDataRole.BackgroundRole`: Used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets, improving visual separation between different asset groups.\r\n+\r\n+The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n+\r\n+\r\n+### Preview Table Column Configuration\r\n+\r\n+The display and behavior of the columns in the `QTableView` are configured in `gui/main_window.py`. The current configuration is as follows:\r\n+\r\n+*   **Column Order (from left to right):**\r\n+    1.  Status\r\n+    2.  Predicted Asset\r\n+    3.  Details\r\n+    4.  Original Path\r\n+    5.  Additional Files\r\n+*   **Column Resizing:**\r\n+    *   Status: Resizes to content.\r\n+    *   Predicted Asset: Resizes to content.\r\n+    *   Details: Resizes to content.\r\n+    *   Original Path: Resizes to content (fixed width behavior).\r\n+    *   Additional Files: Stretches to fill available space.\r\n+\r\n+**Data Flow Diagram:**\r\n+\r\n+```mermaid\r\n+graph LR\r\n+    A[PredictionHandler] -- prediction_results_ready(flat_list) --> B(PreviewTableModel);\r\n+    subgraph PreviewTableModel\r\n+        C[set_data] -- Processes flat_list --> D{Internal Grouping & Transformation};\r\n+        D -- Creates --> E[_table_rows (Structured List)];\r\n+        F[data()] -- Reads from --> E;\r\n+    end\r\n+    B -- Provides data via data() --> G(QTableView via Proxy);\r\n+\r\n+    style B fill:#f9f,stroke:#333,stroke-width:2px\r\n+    style C fill:#ccf,stroke:#333,stroke-width:1px\r\n+    style D fill:#lightgrey,stroke:#333,stroke-width:1px\r\n+    style E fill:#ccf,stroke:#333,stroke-width:1px\r\n+    style F fill:#ccf,stroke:#333,stroke-width:1px\r\n+```\r\n+\r\n+### Application Styling\r\n+\r\n+The application style is explicitly set to 'Fusion' in `gui/main_window.py` to provide a more consistent look and feel across different operating systems, particularly to address styling inconsistencies observed on Windows 11. A custom `QPalette` is also applied to the application to adjust default colors within the 'Fusion' style, specifically to change the background color of list-like widgets and potentially other elements from a default dark blue to a more neutral grey.\r\n+\r\n+## Logging\r\n+\r\n+A custom `QtLogHandler` is used to redirect log messages from the standard Python `logging` module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.\r\n+\r\n+## Cancellation\r\n+\r\n+The GUI provides a \"Cancel\" button to stop ongoing processing. The `ProcessingHandler` implements logic to handle cancellation requests. This typically involves setting an internal flag and attempting to shut down the `ProcessPoolExecutor`. However, it's important to note that this does not immediately terminate worker processes that are already executing; it primarily prevents new tasks from starting and stops processing results from completed futures once the cancellation flag is checked.\n\\ No newline at end of file\n"
                },
                {
                    "date": 1745933975472,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -20,10 +20,10 @@\n ## Threading and Background Tasks\r\n \r\n To keep the UI responsive during intensive operations like asset processing and file preview generation, the GUI utilizes background threads managed by `QThread`.\r\n \r\n-*   **`ProcessingHandler` (`gui/processing_handler.py`):** This class is designed to run in a separate `QThread`. It manages the execution of the main asset processing pipeline for multiple assets concurrently using `concurrent.futures.ProcessPoolExecutor`. It submits individual asset processing tasks to the pool and monitors their completion. It uses Qt signals to communicate progress updates, file status changes, and overall processing completion back to the `MainWindow` on the main UI thread. It also handles the execution of optional Blender scripts via subprocess calls after processing. This handler now processes and utilizes enhanced data structures received from the core processing engine.\r\n-*   **`PredictionHandler` (`gui/prediction_handler.py`):** This class also runs in a separate `QThread`. It is responsible for generating the detailed file classification previews displayed in the preview table. It calls methods on the `AssetProcessor` (`get_detailed_file_predictions`) to perform the analysis in the background. It uses a `ThreadPoolExecutor` for potentially concurrent prediction tasks. Results are sent back to the `MainWindow` via Qt signals to update the preview table data. This handler also works with the enhanced data structures.\r\n+*   **`ProcessingHandler` (`gui/processing_handler.py`):** This class is designed to run in a separate `QThread`. It manages the execution of the main asset processing pipeline for multiple assets concurrently using `concurrent.futures.ProcessPoolExecutor`. It submits individual asset processing tasks to the pool and monitors their completion. It uses Qt signals to communicate progress updates, file status changes, and overall processing completion back to the `MainWindow` on the main UI thread. It also handles the execution of optional Blender scripts via subprocess calls after processing. This handler processes and utilizes data structures received from the core processing engine, such as status summaries.\r\n+*   **`PredictionHandler` (`gui/prediction_handler.py`):** This class also runs in a separate `QThread`. It is responsible for generating the detailed file classification previews displayed in the preview table. It calls methods on the `AssetProcessor` (`get_detailed_file_predictions`) to perform the analysis in the background. It uses a `ThreadPoolExecutor` for potentially concurrent prediction tasks. Results are sent back to the `MainWindow` via Qt signals to update the preview table data. This handler works with data structures containing file prediction details.\r\n \r\n ## Communication (Signals and Slots)\r\n \r\n Communication between the main UI thread (`MainWindow`) and the background threads (`ProcessingHandler`, `PredictionHandler`) relies heavily on Qt's signals and slots mechanism. This is a thread-safe way for objects in different threads to communicate.\r\n@@ -37,11 +37,11 @@\n \r\n ## Preview Table\r\n \r\n \r\n-The `PreviewTableModel` receives enhanced data structures containing detailed file prediction information from the `PredictionHandler` via the `prediction_results_ready` signal. This richer data includes comprehensive details about each file and the asset set it belongs to.\r\n+The `PreviewTableModel` receives a list of file prediction dictionaries from the `PredictionHandler` via the `prediction_results_ready` signal. This list contains dictionaries for each file with details such as original path, predicted asset name, status, and other relevant information.\r\n \r\n-The `PreviewTableModel` is designed to process and display this enhanced file prediction data. Instead of directly displaying a flat list, it processes and transforms the richer data into a structured list of rows (`self._table_rows`). This transformation involves:\r\n+The `PreviewTableModel` is designed to process and display this file prediction data. Instead of directly displaying the flat list, it processes and transforms the data into a structured list of rows (`self._table_rows`). This transformation involves:\r\n \r\n 1.  **Grouping:** Files are grouped based on their `source_asset`.\r\n 2.  **Separation:** Within each asset group, files are separated into `main_files` (Mapped, Model, Error) and `additional_files` (Ignored, Extra, Unrecognised, Unmatched Extra).\r\n 3.  **Structuring Rows:** Rows are created for `self._table_rows` to represent the grouped data. Each row can contain information about a main file and/or an additional file, allowing for the display of additional files in a separate column aligned with the main files of the same asset. Empty rows are created if there are more additional files than main files for an asset to maintain alignment.\r\n@@ -99,108 +99,5 @@\n A custom `QtLogHandler` is used to redirect log messages from the standard Python `logging` module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.\r\n \r\n ## Cancellation\r\n \r\n-The GUI provides a \"Cancel\" button to stop ongoing processing. The `ProcessingHandler` implements logic to handle cancellation requests. This typically involves setting an internal flag and attempting to shut down the `ProcessPoolExecutor`. However, it's important to note that this does not immediately terminate worker processes that are already executing; it primarily prevents new tasks from starting and stops processing results from completed futures once the cancellation flag is checked.\n-# Developer Guide: GUI Internals\r\n-\r\n-This document provides technical details about the implementation of the Graphical User Interface (GUI) for developers.\r\n-\r\n-## Framework\r\n-\r\n-The GUI is built using `PySide6`, which provides Python bindings for the Qt framework.\r\n-\r\n-## Main Window (`gui/main_window.py`)\r\n-\r\n-The `MainWindow` class is the central component of the GUI application. It is responsible for:\r\n-\r\n-*   Defining the main application window structure and layout using PySide6 widgets.\r\n-*   Arranging the Preset Editor panel (left) and the Processing panel (right).\r\n-*   Setting up the menu bar, including the \"View\" menu for toggling the Log Console and Detailed File Preview.\r\n-*   Connecting user interactions (button clicks, drag-and-drop events, checkbox states, spinbox values) to corresponding methods (slots) within the `MainWindow` or other handler classes.\r\n-*   Managing the display of application logs in the UI console using a custom `QtLogHandler`.\r\n-*   Interacting with background handlers (`ProcessingHandler`, `PredictionHandler`) via Qt signals and slots to ensure thread-safe updates to the UI during long-running operations.\r\n-\r\n-## Threading and Background Tasks\r\n-\r\n-To keep the UI responsive during intensive operations like asset processing and file preview generation, the GUI utilizes background threads managed by `QThread`.\r\n-\r\n-*   **`ProcessingHandler` (`gui/processing_handler.py`):** This class is designed to run in a separate `QThread`. It manages the execution of the main asset processing pipeline for multiple assets concurrently using `concurrent.futures.ProcessPoolExecutor`. It submits individual asset processing tasks to the pool and monitors their completion. It uses Qt signals to communicate progress updates, file status changes, and overall processing completion back to the `MainWindow` on the main UI thread. It also handles the execution of optional Blender scripts via subprocess calls after processing.\r\n-*   **`PredictionHandler` (`gui/prediction_handler.py`):** This class also runs in a separate `QThread`. It is responsible for generating the detailed file classification previews displayed in the preview table. It calls methods on the `AssetProcessor` (`get_detailed_file_predictions`) to perform the analysis in the background. It uses a `ThreadPoolExecutor` for potentially concurrent prediction tasks. Results are sent back to the `MainWindow` via Qt signals to update the preview table data.\r\n-\r\n-## Communication (Signals and Slots)\r\n-\r\n-Communication between the main UI thread (`MainWindow`) and the background threads (`ProcessingHandler`, `PredictionHandler`) relies heavily on Qt's signals and slots mechanism. This is a thread-safe way for objects in different threads to communicate.\r\n-\r\n-*   Background handlers emit signals to indicate events (e.g., progress updated, file status changed, task finished).\r\n-*   The `MainWindow` connects slots (methods) to these signals. When a signal is emitted, the connected slot is invoked on the thread that owns the receiving object (the main UI thread for `MainWindow`), ensuring UI updates happen safely.\r\n-\r\n-## Preset Editor\r\n-\r\n-The GUI includes an integrated preset editor panel. This allows users to interactively create, load, modify, and save preset `.json` files directly within the application. The editor typically uses standard UI widgets to display and edit the key fields of the preset structure.\r\n-\r\n-## Preview Table\r\n-\r\n-\r\n-The `PreviewTableModel` receives a flat list of file prediction dictionaries from the `PredictionHandler` via the `prediction_results_ready` signal. Each dictionary in this list represents a single file and includes details such as its original path, predicted status, and the source asset it belongs to.\r\n-\r\n-Instead of directly displaying this flat list, the `PreviewTableModel` processes and transforms it into a structured list of rows (`self._table_rows`). This transformation involves:\r\n-\r\n-1.  **Grouping:** Files are grouped based on their `source_asset`.\r\n-2.  **Separation:** Within each asset group, files are separated into `main_files` (Mapped, Model, Error) and `additional_files` (Ignored, Extra, Unrecognised, Unmatched Extra).\r\n-3.  **Structuring Rows:** Rows are created for `self._table_rows` to represent the grouped data. Each row can contain information about a main file and/or an additional file, allowing for the display of additional files in a separate column aligned with the main files of the same asset. Empty rows are created if there are more additional files than main files for an asset to maintain alignment.\r\n-\r\n-The `data()` method of the `PreviewTableModel` then accesses this structured `self._table_rows` list to provide data to the `QTableView` for display. It handles different columns and roles (Display, Tooltip, Foreground, and Background).\r\n-\r\n-*   `Qt.ItemDataRole.ForegroundRole`: Used to set the text color of individual cells based on the status of the file they represent. Coloring is applied to cells corresponding to a main file based on the main file's status, and to cells in the \"Additional Files\" column based on the additional file's status.\r\n-*   `Qt.ItemDataRole.BackgroundRole`: Used to provide alternating background colors based on the index of the asset group the row belongs to in a sorted list of unique assets, improving visual separation between different asset groups.\r\n-\r\n-The `PreviewSortFilterProxyModel` operates on this structured data, implementing a multi-level sort based on source asset, row type (main vs. additional-only), and file paths within those types.\r\n-\r\n-\r\n-### Preview Table Column Configuration\r\n-\r\n-The display and behavior of the columns in the `QTableView` are configured in `gui/main_window.py`. The current configuration is as follows:\r\n-\r\n-*   **Column Order (from left to right):**\r\n-    1.  Status\r\n-    2.  Predicted Asset\r\n-    3.  Details\r\n-    4.  Original Path\r\n-    5.  Additional Files\r\n-*   **Column Resizing:**\r\n-    *   Status: Resizes to content.\r\n-    *   Predicted Asset: Resizes to content.\r\n-    *   Details: Resizes to content.\r\n-    *   Original Path: Resizes to content (fixed width behavior).\r\n-    *   Additional Files: Stretches to fill available space.\r\n-\r\n-**Data Flow Diagram:**\r\n-\r\n-```mermaid\r\n-graph LR\r\n-    A[PredictionHandler] -- prediction_results_ready(flat_list) --> B(PreviewTableModel);\r\n-    subgraph PreviewTableModel\r\n-        C[set_data] -- Processes flat_list --> D{Internal Grouping & Transformation};\r\n-        D -- Creates --> E[_table_rows (Structured List)];\r\n-        F[data()] -- Reads from --> E;\r\n-    end\r\n-    B -- Provides data via data() --> G(QTableView via Proxy);\r\n-\r\n-    style B fill:#f9f,stroke:#333,stroke-width:2px\r\n-    style C fill:#ccf,stroke:#333,stroke-width:1px\r\n-    style D fill:#lightgrey,stroke:#333,stroke-width:1px\r\n-    style E fill:#ccf,stroke:#333,stroke-width:1px\r\n-    style F fill:#ccf,stroke:#333,stroke-width:1px\r\n-```\r\n-\r\n-### Application Styling\r\n-\r\n-The application style is explicitly set to 'Fusion' in `gui/main_window.py` to provide a more consistent look and feel across different operating systems, particularly to address styling inconsistencies observed on Windows 11. A custom `QPalette` is also applied to the application to adjust default colors within the 'Fusion' style, specifically to change the background color of list-like widgets and potentially other elements from a default dark blue to a more neutral grey.\r\n-\r\n-## Logging\r\n-\r\n-A custom `QtLogHandler` is used to redirect log messages from the standard Python `logging` module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.\r\n-\r\n-## Cancellation\r\n-\r\n The GUI provides a \"Cancel\" button to stop ongoing processing. The `ProcessingHandler` implements logic to handle cancellation requests. This typically involves setting an internal flag and attempting to shut down the `ProcessPoolExecutor`. However, it's important to note that this does not immediately terminate worker processes that are already executing; it primarily prevents new tasks from starting and stops processing results from completed futures once the cancellation flag is checked.\n\\ No newline at end of file\n"
                },
                {
                    "date": 1745934442662,
                    "content": "Index: \n===================================================================\n--- \n+++ \n@@ -99,5 +99,7 @@\n A custom `QtLogHandler` is used to redirect log messages from the standard Python `logging` module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.\r\n \r\n ## Cancellation\r\n \r\n-The GUI provides a \"Cancel\" button to stop ongoing processing. The `ProcessingHandler` implements logic to handle cancellation requests. This typically involves setting an internal flag and attempting to shut down the `ProcessPoolExecutor`. However, it's important to note that this does not immediately terminate worker processes that are already executing; it primarily prevents new tasks from starting and stops processing results from completed futures once the cancellation flag is checked.\n\\ No newline at end of file\n+The GUI provides a \"Cancel\" button to stop ongoing processing. The `ProcessingHandler` implements logic to handle cancellation requests. This typically involves setting an internal flag and attempting to shut down the `ProcessPoolExecutor`. However, it's important to note that this does not immediately terminate worker processes that are already executing; it primarily prevents new tasks from starting and stops processing results from completed futures once the cancellation flag is checked.\r\n+\r\n+**Note on Data Passing:** As mentioned in the Architecture documentation, major changes to the data passing mechanisms between the GUI, Main (CLI orchestration), and `AssetProcessor` modules are currently being planned. The descriptions of how data is handled and passed within the GUI and its interactions with background handlers reflect the current state and will require review and updates once the plan for these changes is finalized.\n\\ No newline at end of file\n"
                }
            ],
            "date": 1745494847187,
            "name": "Commit-0",
            "content": "# Developer Guide: GUI Internals\r\n\r\nThis document provides technical details about the implementation of the Graphical User Interface (GUI) for developers.\r\n\r\n## Framework\r\n\r\nThe GUI is built using `PySide6`, which provides Python bindings for the Qt framework.\r\n\r\n## Main Window (`gui/main_window.py`)\r\n\r\nThe `MainWindow` class is the central component of the GUI application. It is responsible for:\r\n\r\n*   Defining the main application window structure and layout using PySide6 widgets.\r\n*   Arranging the Preset Editor panel (left) and the Processing panel (right).\r\n*   Setting up the menu bar, including the \"View\" menu for toggling the Log Console and Detailed File Preview.\r\n*   Connecting user interactions (button clicks, drag-and-drop events, checkbox states, spinbox values) to corresponding methods (slots) within the `MainWindow` or other handler classes.\r\n*   Managing the display of application logs in the UI console using a custom `QtLogHandler`.\r\n*   Interacting with background handlers (`ProcessingHandler`, `PredictionHandler`) via Qt signals and slots to ensure thread-safe updates to the UI during long-running operations.\r\n\r\n## Threading and Background Tasks\r\n\r\nTo keep the UI responsive during intensive operations like asset processing and file preview generation, the GUI utilizes background threads managed by `QThread`.\r\n\r\n*   **`ProcessingHandler` (`gui/processing_handler.py`):** This class is designed to run in a separate `QThread`. It manages the execution of the main asset processing pipeline for multiple assets concurrently using `concurrent.futures.ProcessPoolExecutor`. It submits individual asset processing tasks to the pool and monitors their completion. It uses Qt signals to communicate progress updates, file status changes, and overall processing completion back to the `MainWindow` on the main UI thread. It also handles the execution of optional Blender scripts via subprocess calls after processing.\r\n*   **`PredictionHandler` (`gui/prediction_handler.py`):** This class also runs in a separate `QThread`. It is responsible for generating the detailed file classification previews displayed in the preview table. It calls methods on the `AssetProcessor` (`get_detailed_file_predictions`) to perform the analysis in the background. It uses a `ThreadPoolExecutor` for potentially concurrent prediction tasks. Results are sent back to the `MainWindow` via Qt signals to update the preview table data.\r\n\r\n## Communication (Signals and Slots)\r\n\r\nCommunication between the main UI thread (`MainWindow`) and the background threads (`ProcessingHandler`, `PredictionHandler`) relies heavily on Qt's signals and slots mechanism. This is a thread-safe way for objects in different threads to communicate.\r\n\r\n*   Background handlers emit signals to indicate events (e.g., progress updated, file status changed, task finished).\r\n*   The `MainWindow` connects slots (methods) to these signals. When a signal is emitted, the connected slot is invoked on the thread that owns the receiving object (the main UI thread for `MainWindow`), ensuring UI updates happen safely.\r\n\r\n## Preset Editor\r\n\r\nThe GUI includes an integrated preset editor panel. This allows users to interactively create, load, modify, and save preset `.json` files directly within the application. The editor typically uses standard UI widgets to display and edit the key fields of the preset structure.\r\n\r\n## Preview Table\r\n\r\nThe preview table displays information about the queued input assets and the predicted classification of their files.\r\n\r\n*   It uses a `QTableView` widget.\r\n*   Data is managed by a custom model (`PreviewTableModel`, inheriting `QAbstractTableModel`) which holds the structured prediction data.\r\n*   A `PreviewSortFilterProxyModel` is used to enable sorting and potentially filtering of the data displayed in the table.\r\n*   The table is updated asynchronously by the `PredictionHandler` via signals. Rows are color-coded based on predicted file status for easy visual identification.\r\n\r\n## Logging\r\n\r\nA custom `QtLogHandler` is used to redirect log messages from the standard Python `logging` module to a text area or console widget within the GUI, allowing users to see detailed application output and errors.\r\n\r\n## Cancellation\r\n\r\nThe GUI provides a \"Cancel\" button to stop ongoing processing. The `ProcessingHandler` implements logic to handle cancellation requests. This typically involves setting an internal flag and attempting to shut down the `ProcessPoolExecutor`. However, it's important to note that this does not immediately terminate worker processes that are already executing; it primarily prevents new tasks from starting and stops processing results from completed futures once the cancellation flag is checked."
        }
    ]
}