initial commit

.gitattributes

@@ -0,0 +1,37 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+/outputs/restored
+/outputs/upscaled
+/models
+/dist
+/.vs
+.vscode/
+.idea/
+/venv
+.venv/
+*.log
+Makefile
+.DS_Store
+.gradio

CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-11-10
+
+This marks the first major stable release after a significant architectural refactor, focusing on robustness, maintainability, and developer experience.
+
+### Added
+
+-   **Modular Architecture:**
+    -   Introduced a clean, multi-file architecture separating responsibilities:
+        -   `app.py`: The main application orchestrator.
+        -   `ui_layout.py`: Defines the complete UI structure and components.
+        -   `ui_events.py`: Contains all event handling logic and business rules.
+        -   `ui_state.py`: Provides a centralized `AppState` dataclass for managing shared application state.
+-   **State Management:**
+    -   Implemented a shared `AppState` container to manage application state (e.g., `uidata`, `cancel_event`, pipeline instances) cleanly, removing all global variables.
+    -   Event logic is now encapsulated within an `EventHandlers` class, which receives the shared state and UI components via dependency injection.
+-   **Developer Experience:**
+    -   Created a `UIComponents` dataclass to hold all Gradio component instances, providing full static type checking and editor Intellisense (auto-completion) for component access.
+    -   Refactored event bindings in `app.py` to use direct attribute access (e.g., `c.run_btn.click`) instead of error-prone string-based dictionary keys.
+
+### Changed
+
+-   **Event Handling Logic:**
+    -   Reverted the primary image generation event from using the `@livelog` decorator back to the original, more robust `threading` and `queue` pattern. This ensures the progress bar and logs update correctly even when the browser tab is not in focus.
+    -   The `generate` method now acts as a generator that spawns a `process_image` worker thread, yielding updates from a queue to the UI.
+-   **Event Binding:**
+    -   The main application class (`GradioApp`) is now solely responsible for orchestrating the app's lifecycle: initializing state, building the UI, and binding events. All implementation logic has been moved to `EventHandlers`.
+    -   Simplified event binding calls by removing unnecessary `lambda` and `partial` wrappers where methods could be called directly. `partial` is now only used for its intended purpose of pre-filling static arguments.
+-   **Code Quality & Style:**
+    -   Integrated `ruff` as the primary tool for linting and formatting, replacing `isort` and `black`.
+    -   Refactored code to resolve all major `ruff` warnings, including:
+        -   Replacing unnecessary list comprehensions with more efficient set comprehensions (e.g., `set([...])` -> `{...}`).
+        -   Replacing list comprehensions inside `any()` with memory-efficient generator expressions.
+        -   Eliminating all "bare `except`" blocks by specifying `except Exception` to prevent hiding critical system errors.
+
+### Fixed
+
+-   **Component State Synchronization:**
+    -   Fixed a critical bug where event handlers were reading stale state from component instances instead of receiving the latest values from the UI. All event handler methods now correctly receive up-to-date component values as arguments from the `inputs` list of the event trigger.
+-   **Gradio Context Errors:**
+    -   Resolved `AttributeError: Cannot call .click outside of a gradio.Blocks context` by centralizing the `gr.Blocks` context management within the `GradioApp` constructor, ensuring both UI creation and event binding occur within the same active context.
+-   **`gr.EventData` Injection:**
+    -   Fixed a bug where `gr.EventData` was being passed as `None` to event handlers. Implemented a robust wrapper pattern for event callbacks that require `EventData`, ensuring Gradio's event data injection mechanism works correctly with the class-based architecture.
+-   **Preset Loading Logic:**
+    -   Corrected a bug in the `load_preset` function where it was mutating the global `RESTORER_CONFIG_MAPPING` dictionary with component instances instead of classes, which caused a `TypeError` on subsequent UI interactions. The function now correctly updates the application state without modifying the original class mapping.

LICENSE

@@ -0,0 +1,177 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+

NOTICE

@@ -0,0 +1,62 @@
+DEVAIEXP Scaling-UP ToolBox Application
+Copyright 2025, DEVAIEXP
+
+This product is licensed under the Apache License, Version 2.0.
+You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0
+
+This product includes or is built upon software developed by third parties.
+The following is a list of these components and their respective licenses.
+Full license texts for each component can be found within their respective module directories.
+
+===================================================
+Component: SUPIR
+---------------------------------------------------
+This product includes an adaptation of the SUPIR project.
+Copyright (c) 2024 by SupPixel Pty Ltd. All rights reserved.
+Original Project: https://github.com/Fanghua-Yu/SUPIR
+
+The use of this component is strictly governed by the SUPIR Software
+License Agreement. This license PROHIBITS ANY COMMERCIAL USE of the
+SUPIR pipeline or its outputs. For commercial licensing, please contact
+the original authors.
+
+===================================================
+Component: FaithDiff
+---------------------------------------------------
+This product includes a derivative work based on the FaithDiff project.
+The original work is Copyright (c) 2025, Junyang Chen, and is licensed
+under the MIT License.
+Original Project: https://github.com/JyChen9811/FaithDiff
+
+===================================================
+Component: IPAdapter
+---------------------------------------------------
+This product utilizes software from the IP-Adapter project.
+The original work is Copyright (c) 2023, TencentARC, and is licensed
+under the Apache License, Version 2.0.
+Original Project: https://github.com/tencent-ailab/IP-Adapter
+
+===================================================
+Component: ControlNet Tile Pipeline
+---------------------------------------------------
+The code for this pipeline is a derivative work based on the ControlNet
+pipeline implementations found in the HuggingFace Diffusers library.
+
+The original Diffusers library is Copyright 2024, The HuggingFace Team,
+and is licensed under the Apache License, Version 2.0.
+
+===================================================
+Component: Mixture of Diffusers Technique
+---------------------------------------------------
+This product includes an implementation of the "Mixture of Diffusers"
+technique. The original work is Copyright (c) 2022, Álvaro Barbero Jiménez,
+and is licensed under the MIT License.
+Original Project: https://github.com/albarji/mixture-of-diffusers
+
+===================================================
+Component: Diffusers Library
+---------------------------------------------------
+This product is built upon and includes software from the Diffusers library.
+The original work is Copyright 2024, The HuggingFace Team, and is licensed
+under the Apache License, Version 2.0.
+Original Project: https://github.com/huggingface/diffusers

README.md

@@ -0,0 +1,149 @@
+---
+title: Sup Toolbox App
+emoji: ⚡
+colorFrom: gray
+colorTo: yellow
+sdk: gradio
+sdk_version: 5.49.1
+app_file: app.py
+pinned: false
+license: apache-2.0
+short_description: SUP Toolbox Gradio Demo
+---
+
+<h1 align="center">SUP Toolbox App 🎨</h1>
+<p align="center">
+  A user-friendly Gradio web interface for the powerful <strong>SUP-Toolbox</strong> image restoration and upscaling library.
+</p>
+
+<p align="center">
+  <img src="https://huggingface.co/datasets/DEVAIEXP/assets/resolve/main/screen_sup_toolbox.PNG" alt="SUP Toolbox App Interface" width="800"/>
+</p>
+
+<p align="center">
+  <a href="https://github.com/DEVAIEXP/sup-toolbox-app/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>  
+  <a href="https://github.com/DEVAIEXP/sup-toolbox/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python Version"></a>
+  <a href="https://github.com/DEVAIEXP/sup-toolbox-app/stargazers"><img src="https://img.shields.io/github/stars/DEVAIEXP/sup-toolbox-app?style=social" alt="GitHub Stars"></a>
+  <a href="https://github.com/DEVAIEXP/sup-toolbox"><img src="https://img.shields.io/badge/Powered%20by-SUP--Toolbox-orange" alt="Powered by SUP-Toolbox"></a>
+  <a href="https://huggingface.co/spaces/YOUR_HF_USERNAME/sup-toolbox-app"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-yellow" alt="Hugging Face Spaces"></a>
+</p>
+
+## About
+
+The **SUP Toolbox App** provides an intuitive and interactive web interface for the [SUP-Toolbox library](https://github.com/DEVAIEXP/sup-toolbox). It allows you to harness the power of advanced image enhancement models like **SUPIR**, **FaithDiff**, and **ControlNetTile** through a user-friendly Gradio application, without needing to use the command line.
+
+This application is designed for artists, photographers, and enthusiasts who want to visually experiment with different settings, manage presets, and process images one by one with real-time feedback.
+
+## Features
+
+-   **Interactive UI:** A clean and organized Gradio interface for easy access to all features.
+-   **Full Engine Support:** Access and combine all restoration (`SUPIR`, `FaithDiff`) and upscaling (`SUPIR`, `FaithDiff`, `ControlNetTile`) engines from the core library.
+-   **Preset Management:** Create, save, and load your custom workflows as `.json` presets directly from the UI.
+-   **Live Previews & Comparison:** Instantly see the results of your settings with before-and-after image sliders.
+-   **Metadata Handling:** Automatically saves all generation parameters within the output image. Load settings from a previously generated image by simply dropping it into the app.
+-   **Real-time Logging:** A live log panel shows the progress of the image generation process.
+
+## Requirements
+
+This application depends on the `sup-toolbox` library. Therefore, it shares the same hardware and software requirements. For a detailed breakdown, please refer to the core library's documentation:
+
+➡️ **[View Full Requirements in the SUP-Toolbox README](https://github.com/DEVAIEXP/sup-toolbox#requirements)**
+
+In summary:
+-   **Python 3.10+**, Git
+-   **NVIDIA GPU** with 12GB+ VRAM recommended.
+-   **~83 GB** of disk space for models.
+
+## Installation
+
+The setup process is designed to be simple. It will create a virtual environment and install both the `sup-toolbox` library from its GitHub repository and all other necessary Python packages.
+
+### 1. Clone the Application Repository
+```bash
+git clone https://github.com/DEVAIEXP/sup-toolbox-app.git
+cd sup-toolbox-app
+```
+
+### 2. Run the Setup Script
+
+Choose the script that matches your operating system and terminal.
+
+*   **On Windows (using PowerShell):**
+    This is the recommended method for modern Windows systems.
+
+    1.  **Allow script execution (one-time setup):**
+        If you haven't run PowerShell scripts before, open PowerShell **as an Administrator** and run:
+        ```powershell
+        Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+        ```
+        Press `Y` and `Enter` to confirm.
+
+    2.  **Run the script:**
+        In a regular PowerShell terminal, run:
+        ```powershell
+        .\setup.ps1
+        ```
+
+*   **On Windows (using Command Prompt):**
+    ```batch
+    .\setup.bat
+    ```
+
+*   **On Linux or macOS:**
+    ```bash
+    chmod +x setup.sh
+    ./setup.sh
+    ```
+
+This will set up everything you need. The `requirements.txt` file in this repository is configured to automatically download and install the correct version of the `sup-toolbox` library.
+
+## Usage
+
+After a successful installation, you can easily start the application using the provided start scripts.
+
+*   **On Windows:** Double-click `start.bat` or `start.ps1`, or run them from your terminal:
+    ```powershell
+    # In PowerShell
+    .\start.ps1
+    ```
+    ```batch
+    :: In Command Prompt
+    .\start.bat
+    ```
+
+*   **On Linux or macOS:**
+    ```bash
+    ./start.sh
+    ```
+
+This will activate the virtual environment and launch the Gradio application. Open your web browser and navigate to the local URL provided in the terminal (usually `http://127.0.0.1:7860`).
+
+## Relationship with `sup-toolbox`
+
+This project is the official Gradio UI front-end for the `sup-toolbox` library.
+
+-   **[sup-toolbox (Library)](https://github.com/DEVAIEXP/sup-toolbox):** The core engine. It's a Python library and CLI tool that contains all the processing logic, model management, and configuration system. It's designed for programmatic use and automation.
+-   **sup-toolbox-app (This Project):** A user-friendly graphical interface that *uses* the `sup-toolbox` library as its backend. It provides no image processing logic itself but offers a convenient way to access the library's features.
+
+## Releases and Changelog
+
+For a detailed list of changes, new features, and bug fixes for each version of this application, please see the **[CHANGELOG.md](CHANGELOG.md)** file.
+
+## Licensing
+
+The **SUP Toolbox App** (this project) is licensed under the **Apache License, Version 2.0**. You can find the full license text in the `LICENSE` file in this repository.
+
+Please be aware that this application is a front-end for the `sup-toolbox` library, which integrates several third-party components, some of which are under **non-commercial licenses** (such as SUPIR).
+
+**By using this application, you acknowledge and agree to comply with all the licensing terms of the underlying `sup-toolbox` library and its components.** For a complete breakdown of these licenses, please refer to the library's documentation:
+
+➡️ **[View Full Licensing Details in the SUP-Toolbox README](https://github.com/DEVAIEXP/sup-toolbox#licensing)**
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=DEVAIEXP/sup-toolbox-app&type=Date)](https://star-history.com/#DEVAIEXP/sup-toolbox-app&Date)
+
+## Contact
+For questions or issues related to this Gradio application, please open an issue in this repository. For issues related to the core processing logic, please refer to the [`sup-toolbox`](https://github.com/DEVAIEXP/sup-toolbox/issues) library's repository.
+
+Project Contact: contact@devaiexp.com

app.py

@@ -0,0 +1,405 @@
+# Copyright 2025 The DEVAIEXP Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import spaces
+import gradio as gr
+import torch
+import argparse
+from functools import partial
+from typing import Any
+
+from gradio_folderexplorer.helpers import load_media_from_folder
+from gradio_livelog.utils import livelog
+
+from ui.ui_data import UIData
+from ui.ui_events import AppState, EventHandlers
+from ui.ui_layout import UIComponents, create_ui_components
+
+
+class GradioApp:
+    def __init__(self, args):
+        self.args = args
+        self.state = AppState(uidata=UIData(always_download_models=args.always_download_models))
+
+        self.app = gr.Blocks(theme=self.state.uidata.theme, title="Scaling-UP ToolBox")
+        with self.app:
+            components_dict = create_ui_components(self.state.uidata)
+            self.components = UIComponents(**components_dict)
+            self.event_handlers = EventHandlers(self.state, self.components)
+            self._bind_events()
+
+    def _bind_events(self):
+        c = self.components
+        ui_inputs, output_fields = c._get_ui_inputs_and_outputs()
+        js_update_flyout = "(jsonData) => { update_flyout_from_state(jsonData); }"
+        flyout_data_event = {"fn": None, "inputs": [c.js_data_bridge], "js": js_update_flyout}
+
+        generate_inputs = list(ui_inputs.values())[4:]
+
+        @spaces.GPU(duration=60)
+        # Here we don't use the @livelog decorator function to ensure the progress bar is synchronized when the browser is not in focus.
+        def on_generate_wrapper(*args):
+            """
+            This wrapper is decorated by @spaces.GPU and is passed to Gradio.
+            It calls the actual logic handler from the EventHandlers instance.
+            """
+            yield from self.event_handlers.on_generate(*args)
+
+        @spaces.GPU(duration=60)
+        def on_refresh_mask_gpu_wrapper(*args, **kwargs):
+            """Wrapper for the mask generation."""
+
+            livelog_decorated_func = livelog(
+                log_names=["suptoolbox_app", "suptoolbox"],
+                outputs_for_yield=[c.restoration_mask, c.livelog_viewer],
+                log_output_index=1,
+                result_output_index=0,
+                use_tracker=False,
+            )(self.event_handlers.on_refresh_restoration_mask)
+
+            yield from livelog_decorated_func(*args, **kwargs)
+
+        @spaces.GPU(duration=60)
+        def on_generate_caption_gpu_wrapper(*args, **kwargs):
+            """
+            This wrapper handles the @spaces.GPU decorator and then applies
+            the @livelog decorator to the actual event handler.
+            """
+
+            livelog_decorated_func = livelog(
+                log_names=["suptoolbox_app", "suptoolbox"],
+                outputs_for_yield=[kwargs.pop("output_component_1"), kwargs.pop("output_component_2")],
+                log_output_index=1,
+                result_output_index=0,
+                use_tracker=False,
+            )(self.event_handlers.on_generate_caption)
+
+            yield from livelog_decorated_func(*args, **kwargs)
+
+        def on_load_metadata_from_gallery_wrapper(folder_explorer_value: Any, image_data: gr.EventData):
+            return self.event_handlers.on_load_metadata_from_gallery(folder_explorer_value, image_data)
+
+        # Settings Tab Events
+        c.reset_settings_btn.click(fn=self.event_handlers.on_reset_settings).then(fn=self.event_handlers.restart, js="restart_ui")
+        c.save_settings_btn.click(fn=self.event_handlers.on_save_settings, inputs=c.settings_sheet).then(fn=self.event_handlers.restart, js="restart_ui")
+
+        # Flyout Events
+        c.flyout_sheet.change(fn=self.event_handlers.on_flyout_change, inputs=[c.flyout_sheet, c.active_anchor_id])
+        c.flyout_property_sheet_close_btn.click(
+            partial(self.event_handlers.on_close_the_flyout, "flyout_property_sheet_panel_target"),
+            outputs=[c.flyout_visible, c.active_anchor_id, c.js_data_bridge],
+        ).then(**flyout_data_event)
+        c.flyout_restoration_image_close_btn.click(
+            partial(self.event_handlers.on_close_the_flyout, "flyout_restoration_mask_panel_target"),
+            outputs=[c.flyout_visible, c.active_anchor_id, c.js_data_bridge],
+        ).then(**flyout_data_event)
+        c.restorer_sampler.change(
+            partial(self.event_handlers.on_update_ear_visibility, c.restorer_sampler.elem_id),
+            outputs=[c.restorer_sampler_ear_btn],
+        ).then(
+            partial(self.event_handlers.on_close_the_flyout, "flyout_property_sheet_panel_target"),
+            outputs=[c.flyout_visible, c.active_anchor_id, c.js_data_bridge],
+        ).then(**flyout_data_event)
+        c.restorer_sampler_ear_btn.click(
+            partial(
+                self.event_handlers.on_handle_flyout_toggle,
+                clicked_elem_id=c.restorer_sampler.elem_id,
+                target_elem_id="flyout_property_sheet_panel_target",
+            ),
+            inputs=[c.flyout_visible, c.active_anchor_id],
+            outputs=[c.flyout_visible, c.active_anchor_id, c.flyout_sheet, c.js_data_bridge],
+        ).then(**flyout_data_event)
+        c.upscaler_sampler.change(
+            partial(self.event_handlers.on_update_ear_visibility, c.upscaler_sampler.elem_id),
+            outputs=[c.upscaler_sampler_ear_btn],
+        ).then(
+            partial(self.event_handlers.on_close_the_flyout, "flyout_property_sheet_panel_target"),
+            outputs=[c.flyout_visible, c.active_anchor_id, c.js_data_bridge],
+        ).then(**flyout_data_event)
+        c.upscaler_sampler_ear_btn.click(
+            partial(
+                self.event_handlers.on_handle_flyout_toggle,
+                clicked_elem_id=c.upscaler_sampler.elem_id,
+                target_elem_id="flyout_property_sheet_panel_target",
+            ),
+            inputs=[c.flyout_visible, c.active_anchor_id],
+            outputs=[c.flyout_visible, c.active_anchor_id, c.flyout_sheet, c.js_data_bridge],
+        ).then(**flyout_data_event)
+        c.preview_restoration_mask_chk.select(
+            lambda is_checked: (gr.update(interactive=is_checked), gr.update(interactive=is_checked)),
+            inputs=[c.preview_restoration_mask_chk],
+            outputs=[c.restoration_mask_prompt, c.preview_restoration_mask_btn],
+        )
+
+        c.preview_restoration_mask_btn.click(
+            self.event_handlers.on_check_inputs,
+            inputs=[
+                c.restorer_engine,
+                c.upscaler_engine,
+                c.restorer_model,
+                c.upscaler_model,
+                gr.State("generation_mask"),
+            ],
+            outputs=[c.bottom_bar, c.livelog_viewer],
+            show_progress="hidden",
+        ).success(
+            fn=on_refresh_mask_gpu_wrapper,
+            inputs=[c.restoration_mask_prompt],
+            outputs=[c.restoration_mask, c.livelog_viewer],
+        ).success(
+            partial(
+                self.event_handlers.on_handle_flyout_toggle,
+                clicked_elem_id=c.preview_restoration_mask_btn.elem_id,
+                target_elem_id="flyout_restoration_mask_panel_target",
+            ),
+            inputs=[c.flyout_visible, c.active_anchor_id],
+            outputs=[c.flyout_visible, c.active_anchor_id, c.restoration_mask, c.js_data_bridge],
+        ).success(**flyout_data_event)
+
+        c.res_prompt_generate_btn.click(
+            self.event_handlers.on_check_inputs,
+            inputs=[
+                c.restorer_engine,
+                c.upscaler_engine,
+                c.restorer_model,
+                c.upscaler_model,
+                gr.State("caption_generation"),
+            ],
+            outputs=[c.bottom_bar, c.livelog_viewer],
+            show_progress="hidden",
+        ).success(
+            fn=partial(on_generate_caption_gpu_wrapper, output_component_1=c.res_prompt, output_component_2=c.livelog_viewer),
+            outputs=[c.res_prompt, c.livelog_viewer],
+        )
+
+        c.ups_prompt_generate_btn.click(
+            self.event_handlers.on_check_inputs,
+            inputs=[
+                c.restorer_engine,
+                c.upscaler_engine,
+                c.restorer_model,
+                c.upscaler_model,
+                gr.State("caption_generation"),
+            ],
+            outputs=[c.bottom_bar, c.livelog_viewer],
+            show_progress="hidden",
+        ).success(
+            fn=partial(on_generate_caption_gpu_wrapper, output_component_1=c.ups_prompt, output_component_2=c.livelog_viewer),
+            outputs=[c.ups_prompt, c.livelog_viewer],
+        )
+        c.restorer_engine.select(
+            self.event_handlers.on_restore_engine_change,
+            inputs=[c.restorer_engine, c.upscaler_engine],
+            outputs=[c.restorer_tab, c.restorer_sheet_supir_advanced, c.restorer_sheet, c.ec_accordion, c.config_tabs],
+        ).success(
+            self.event_handlers.on_set_default_prompts,
+            inputs=[
+                c.restorer_engine,
+                c.upscaler_engine,
+                c.res_prompt,
+                c.res_prompt_2,
+                c.res_negative_prompt,
+                c.ups_prompt,
+                c.ups_prompt_2,
+                c.ups_negative_prompt,
+            ],
+            outputs=[
+                c.res_prompt,
+                c.res_prompt_2,
+                c.res_negative_prompt,
+                c.ups_prompt,
+                c.ups_prompt_2,
+                c.ups_negative_prompt,
+            ],
+        )
+        c.restorer_engine.change(
+            self.event_handlers.on_restore_engine_change,
+            inputs=[c.restorer_engine, c.upscaler_engine],
+            outputs=[c.restorer_tab, c.restorer_sheet_supir_advanced, c.restorer_sheet, c.ec_accordion, c.config_tabs],
+        )
+        c.upscaler_engine.change(
+            self.event_handlers.on_upscaler_engine_change,
+            inputs=[c.restorer_engine, c.upscaler_engine],
+            outputs=[
+                c.upscaler_tab,
+                c.upscaler_sheet_supir_advanced,
+                c.upscaler_sheet,
+                c.ec_accordion,
+                c.config_tabs,
+                c.ups_prompt_method,
+            ],
+        )
+        c.upscaler_engine.select(
+            self.event_handlers.on_upscaler_engine_change,
+            inputs=[c.restorer_engine, c.upscaler_engine],
+            outputs=[
+                c.upscaler_tab,
+                c.upscaler_sheet_supir_advanced,
+                c.upscaler_sheet,
+                c.ec_accordion,
+                c.config_tabs,
+                c.ups_prompt_method,
+            ],
+        ).success(
+            self.event_handlers.on_set_default_prompts,
+            inputs=[
+                c.restorer_engine,
+                c.upscaler_engine,
+                c.res_prompt,
+                c.res_prompt_2,
+                c.res_negative_prompt,
+                c.ups_prompt,
+                c.ups_prompt_2,
+                c.ups_negative_prompt,
+            ],
+            outputs=[
+                c.res_prompt,
+                c.res_prompt_2,
+                c.res_negative_prompt,
+                c.ups_prompt,
+                c.ups_prompt_2,
+                c.ups_negative_prompt,
+            ],
+        )
+        c.restorer_sheet.change(self.event_handlers.on_restorer_sheet_change, inputs=[c.restorer_sheet], outputs=[c.restorer_sheet])
+        c.upscaler_sheet.change(self.event_handlers.on_upscaler_sheet_change, inputs=[c.upscaler_sheet], outputs=[c.upscaler_sheet])
+        c.settings_sheet.change(self.event_handlers.on_settings_sheet_change, inputs=[c.settings_sheet], outputs=[c.settings_sheet])
+        c.restorer_sheet_supir_advanced.change(
+            self.event_handlers.on_restorer_supir_advanced_sheet_change, inputs=[c.restorer_sheet_supir_advanced], outputs=[c.restorer_sheet_supir_advanced]
+        )
+        c.upscaler_sheet_supir_advanced.change(
+            self.event_handlers.on_upscaler_supir_advanced_sheet_change, inputs=[c.upscaler_sheet_supir_advanced], outputs=[c.upscaler_sheet_supir_advanced]
+        )
+        c.settings_tab.select(self.event_handlers.on_settings_tab_select, outputs=[c.settings_sheet])
+        update_prompt_helper_from_tab_event = {
+            "fn": self.event_handlers.update_prompt_helper_from_tab,
+            "outputs": [c.tag_helper_pos, c.tag_helper_neg],
+        }
+        c.restorer_tab.select(**update_prompt_helper_from_tab_event)
+        c.upscaler_tab.select(**update_prompt_helper_from_tab_event)
+        c.res_prompt.change(
+            self.event_handlers.update_positive_tokenizer,
+            inputs=[c.res_prompt, c.res_prompt_2],
+            outputs=c.res_tokenizer_pos,
+        )
+        c.res_prompt_2.change(
+            self.event_handlers.update_positive_tokenizer,
+            inputs=[c.res_prompt, c.res_prompt_2],
+            outputs=c.res_tokenizer_pos,
+        )
+        c.ups_prompt.change(
+            self.event_handlers.update_positive_tokenizer,
+            inputs=[c.ups_prompt, c.ups_prompt_2],
+            outputs=c.ups_tokenizer_pos,
+        )
+        c.ups_prompt_2.change(
+            self.event_handlers.update_positive_tokenizer,
+            inputs=[c.ups_prompt, c.ups_prompt_2],
+            outputs=c.ups_tokenizer_pos,
+        )
+        c.res_negative_prompt.change(lambda p: gr.update(value=p), inputs=c.res_negative_prompt, outputs=c.res_tokenizer_neg)
+        c.ups_negative_prompt.change(lambda p: gr.update(value=p), inputs=c.ups_negative_prompt, outputs=c.ups_tokenizer_neg)
+        c.res_prompt.focus(self.event_handlers.update_positive_prompt_helper, outputs=c.tag_helper_pos)
+        c.res_prompt_2.focus(self.event_handlers.update_positive_prompt_helper, outputs=c.tag_helper_pos)
+        c.ups_prompt.focus(self.event_handlers.update_positive_prompt_helper, outputs=c.tag_helper_pos)
+        c.ups_prompt_2.focus(self.event_handlers.update_positive_prompt_helper, outputs=c.tag_helper_pos)
+
+        c.run_btn.click(
+            self.event_handlers.on_check_inputs,
+            inputs=[c.restorer_engine, c.upscaler_engine, c.restorer_model, c.upscaler_model],
+            outputs=[c.bottom_bar, c.livelog_viewer],
+            show_progress="hidden",
+        ).success(
+            self.event_handlers.calculate_total_steps,
+            inputs=[c.restorer_sheet, c.upscaler_sheet, c.restorer_engine, c.upscaler_engine],
+            outputs=c.total_inference_steps,
+        ).success(
+            fn=on_generate_wrapper,
+            inputs=[c.total_inference_steps, *generate_inputs],
+            outputs=[c.result_slider, c.livelog_viewer, c.run_btn, c.cancel_btn, c.bottom_bar],
+            show_progress="hidden",
+        )
+        c.cancel_btn.click(self.event_handlers.on_cancel_click)
+        c.save_preset_btn.click(
+            fn=self.event_handlers.save_preset,
+            inputs=[c.preset_name, *c.ALL_UI_COMPONENTS.values()],
+        ).then(self.event_handlers.update_preset_list, inputs=c.preset_name, outputs=[c.presets])
+        c.load_preset_btn.click(
+            fn=self.event_handlers.load_preset,
+            inputs=[c.presets],
+            outputs=list(c.ALL_UI_COMPONENTS.values()),
+        )
+        c.input_image.load_metadata(self.event_handlers.on_load_metadata_from_single_image, inputs=c.input_image, outputs=output_fields)
+        c.input_image.change(self.event_handlers.on_input_image_change, inputs=c.input_image)
+        c.folder_explorer.change(load_media_from_folder, inputs=c.folder_explorer, outputs=c.generated_image_viewer)
+        c.generated_image_viewer.load_metadata(fn=on_load_metadata_from_gallery_wrapper, inputs=[c.folder_explorer], outputs=output_fields).then(
+            lambda: gr.update(selected="process-tab"), outputs=c.main_tabs
+        )
+        c.livelog_viewer.clear(fn=self.event_handlers.on_clear_log_output, outputs=c.livelog_viewer)
+        flyout_setup = self.event_handlers.initial_flyout_setup()
+        self.app.load(fn=self.state.uidata.inject_assets, inputs=None, outputs=[c.html_injector]).then(
+            self.event_handlers.on_restore_engine_change,
+            inputs=[c.restorer_engine, c.upscaler_engine],
+            outputs=[c.restorer_tab, c.restorer_sheet_supir_advanced, c.restorer_sheet, c.ec_accordion, c.config_tabs],
+        ).then(
+            self.event_handlers.on_upscaler_engine_change,
+            inputs=[c.restorer_engine, c.upscaler_engine],
+            outputs=[
+                c.upscaler_tab,
+                c.upscaler_sheet_supir_advanced,
+                c.upscaler_sheet,
+                c.ec_accordion,
+                c.config_tabs,
+                c.ups_prompt_method,
+            ],
+        ).then(self.event_handlers.on_restorer_sheet_change, inputs=[c.restorer_sheet], outputs=[c.restorer_sheet]).then(
+            self.event_handlers.update_positive_tokenizer,
+            inputs=[c.res_prompt, c.res_prompt_2],
+            outputs=c.res_tokenizer_pos,
+        ).then(
+            self.event_handlers.update_positive_tokenizer,
+            inputs=[c.ups_prompt, c.ups_prompt_2],
+            outputs=c.ups_tokenizer_pos,
+        ).then(lambda p: gr.update(value=p), inputs=c.res_negative_prompt, outputs=c.res_tokenizer_neg).then(
+            lambda p: gr.update(value=p), inputs=c.ups_negative_prompt, outputs=c.ups_tokenizer_neg
+        ).then(
+            lambda: [flyout_setup["restorer_sampler_ear_btn"], flyout_setup["upscaler_sampler_ear_btn"]],
+            outputs=[c.restorer_sampler_ear_btn, c.upscaler_sampler_ear_btn],
+        ).then(
+            fn=None,
+            inputs=None,
+            outputs=None,
+            js="() => { setTimeout(reparent_flyout(['flyout_property_sheet_panel', 'flyout_restoration_mask_panel']), 200); }",
+        )
+
+    def launch(self):
+        self.app.queue().launch(debug=True, inbrowser=True, share=self.args.share, server_port=self.args.port, server_name=self.args.listen)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="SUP-Toolbox initialization args")
+    parser.add_argument(
+        "--always-download-models",
+        action="store_true",
+        default=False,
+        help="If specified, forces a full scan and download of the models if necessary.",
+    )
+    parser.add_argument("-s", "--share", action="store_true", help="Create a public link")
+    parser.add_argument("--port", default=7860, type=int, help="Port to run the server on")
+    parser.add_argument("--listen", default="0.0.0.0", help="IP address to listen on")
+
+    args = parser.parse_args()
+
+    app_instance = GradioApp(args)
+    app_instance.launch()

configs/settings.json

@@ -0,0 +1,29 @@
+{
+  "save_image_format": ".jpg",
+  "latest_preset": "Default",
+  "cache_dir": "models",
+  "checkpoints_dir": "F:\\models\\Stable-diffusion",
+  "vae_dir": "models/VAE",
+  "output_dir": "./outputs",
+  "save_image_on_upscaling_passes": true,
+  "weight_dtype": "Float16",
+  "vae_weight_dtype": "Float16",
+  "device": "cuda",
+  "generator_device": "cpu",
+  "enable_cpu_offload": false,
+  "enable_vae_tiling": true,
+  "enable_vae_slicing": false,
+  "memory_attention": "sdp",
+  "quantization_method": "Layerwise & Bnb",
+  "quantization_mode": "FP8",
+  "allow_cuda_tf32": false,
+  "allow_cudnn_tf32": false,
+  "disable_mmap": true,
+  "always_offload_models": true,
+  "run_vae_on_cpu": false,
+  "enable_llava_quantization": true,
+  "llava_quantization_mode": "INT4",
+  "llava_offload_model": false,
+  "llava_weight_dtype": "Float16",
+  "llava_question_prompt": "Describe what you see in this image and put it in prompt format limited to 77 tokens:"
+}

requirements.txt

@@ -0,0 +1,25 @@
+gradio==5.44.1
+gradio_tokenizertextbox
+gradio_taggrouphelper
+gradio_propertysheet
+gradio_htmlinjector
+gradio_imagemeta
+gradio_livelog
+gradio_bottombar
+gradio_topbar
+gradio_textboxplus
+gradio_dropdownplus
+gradio_buttonplus
+gradio_folderexplorer
+gradio_mediagallery
+gradio_creditspanel
+spaces
+optimum-quanto==0.2.7
+torch==2.8.0
+torchvision==0.23.0
+torchaudio==2.8.0
+transformers==4.56.0
+bitsandbytes==0.48.1
+xformers==0.0.32.post2
+hf_xet
+git+https://github.com/DEVAIEXP/sup-toolbox.git@main#egg=sup-toolbox

ui/globals.py

@@ -0,0 +1,8 @@
+import threading
+
+
+# These variables live at the module level.
+# When multiple workers import this module, they will all reference
+# the same objects in the parent process's memory (due to how Python forks processes on Linux).
+sup_toolbox_pipe = None
+pipeline_lock = threading.Lock()

ui/script.js

@@ -0,0 +1,194 @@
+function isJsonString(str) {
+    if (typeof str !== 'string' || str.trim() === '') {
+        return false;
+    }
+    try {
+        const result = JSON.parse(str);
+        return typeof result === 'object' && result !== null;
+    } catch (e) {
+        return false;
+    }
+}
+
+// Copied and adapted from https://github.com/AUTOMATIC1111/stable-diffusion-webui/blob/82a973c04367123ae98bd9abdf80d9eda9b910e2/javascript/extraNetworks.js#L582
+function requestGet(url, data, handler, errorHandler) {
+    if (typeof url !== 'string' || url.trim() === '') {
+        console.error("requestGet: Invalid or empty URL provided.");
+        if (typeof errorHandler === 'function') errorHandler(new Error("Invalid URL"));
+        return;
+    }
+
+    const requestData = (data && typeof data === 'object') ? data : {};
+    const successHandler = typeof handler === 'function' ? handler : () => { };
+    const failureHandler = typeof errorHandler === 'function' ? errorHandler : (err) => { console.error("requestGet failed:", err); };
+
+    let args = '';
+    try {
+        args = Object.keys(requestData).map(function (k) {
+            const key = encodeURIComponent(k);
+            const value = encodeURIComponent(requestData[k]);
+            return `${key}=${value}`;
+        }).join('&');
+    } catch (e) {
+        console.error("requestGet: Failed to serialize data object.", e);
+        failureHandler(e);
+        return;
+    }
+
+    const fullUrl = args ? `${url}?${args}` : url;
+
+    const xhr = new XMLHttpRequest();
+    xhr.open("GET", fullUrl, true);
+
+    xhr.onreadystatechange = function () {
+        if (xhr.readyState === 4) {
+            if (xhr.status === 200) {
+                try {
+                    const responseJson = isJsonString(xhr.responseText) ? JSON.parse(xhr.responseText) : {};
+                    successHandler(responseJson);
+                } catch (error) {
+                    console.error("requestGet: Error parsing JSON response.", error);
+                    failureHandler(error);
+                }
+            } else {
+                failureHandler(new Error(`Request failed with status ${xhr.status}: ${xhr.statusText}`));
+            }
+        }
+    };
+
+    xhr.onerror = function () {
+        failureHandler(new Error("Network error occurred."));
+    };
+
+    xhr.send();
+}
+
+// copied and adapted from https://github.com/AUTOMATIC1111/stable-diffusion-webui/blob/82a973c04367123ae98bd9abdf80d9eda9b910e2/javascript/ui.js#L348
+function restart_ui() {
+    const overlay = document.createElement('div');
+    overlay.innerHTML = '<h1 style="font-family:monospace; margin-top:20%; color:lightgray; text-align:center;">Reloading...</h1>';
+    overlay.style.position = 'fixed';
+    overlay.style.top = '0';
+    overlay.style.left = '0';
+    overlay.style.width = '100%';
+    overlay.style.height = '100%';
+    overlay.style.backgroundColor = 'rgba(20, 20, 20, 0.9)';
+    overlay.style.zIndex = '10000';
+    document.body.appendChild(overlay);
+
+    const requestPing = function () {
+        requestGet(
+            window.location.href,
+            {},
+            function (data) {
+                window.location.reload();
+            },
+            function (error) {
+                console.log("Ping failed, retrying...");
+                setTimeout(requestPing, 500);
+            }
+        );
+    };
+
+    setTimeout(requestPing, 2000);
+}
+
+/**
+ * Moves all child elements from one or more source containers to their corresponding target containers.
+ * By convention, the target ID for a source 'my-source-id' is expected to be 'my-source-id_target'.
+ * After moving, the source containers are removed from the DOM by default.
+ *
+ * @param {string | string[]} source_ids - A single source element ID or an array of IDs.
+ * @param {object} [options] - Optional settings.
+ * @param {boolean} [options.remove_sources=true] - If true, removes the source elements after their content is moved.
+ */
+function reparent_flyout(source_ids, options = { remove_sources: true }) {
+    // Ensure the input is always an array to simplify the logic.
+    const sourceArray = Array.isArray(source_ids) ? source_ids : [source_ids];
+
+    // Iterate over each provided source ID.
+    sourceArray.forEach(source_id => {
+        // Find the source element.
+        const source = document.getElementById(source_id);
+        
+        // If the source element doesn't exist, we can't do anything for this ID.
+        if (!source) {
+            console.warn(`WARNING: Source element with ID '${source_id}' not found. Skipping.`);
+            return; // 'return' inside a forEach acts like 'continue' in a for loop.
+        }
+
+        // Derive the target ID from the source ID
+        const target_id = `${source_id}_target`;
+        const target = document.getElementById(target_id);
+
+        // If the corresponding target element doesn't exist, log an error.
+        if (!target) {
+            console.error(`ERROR: Reparenting for '#${source_id}' failed. Corresponding target '#${target_id}' not found.`);
+            return;
+        }
+
+        // Move each child node from the source to the target.
+        // The `while (source.firstChild)` loop is efficient because `appendChild`
+        // automatically removes the child from its original parent.
+        while (source.firstChild) {
+            target.appendChild(source.firstChild);
+        }
+
+        // Remove the now-empty source container if the option is enabled.
+        if (options.remove_sources) {
+            source.remove();
+        }
+        
+        console.log(`SUCCESS: Content from '#${source_id}' has been reparented to '#${target_id}'.`);
+    });
+}
+
+function position_flyout(anchorId, target_id) {
+    if (!anchorId) { return; }
+    
+    const anchorElem = document.getElementById(anchorId);
+    const flyoutElem = document.getElementById(target_id);
+    
+    if (anchorElem && flyoutElem) {
+        //console.log("JS: Positioning flyout relative to:", anchorId);
+        const anchorRect = anchorElem.getBoundingClientRect();
+        const flyoutWidth = flyoutElem.offsetWidth;
+        const flyoutHeight = flyoutElem.offsetHeight;
+
+        let topPosition = anchorRect.top + (anchorRect.height / 2) - (flyoutHeight / 2);
+        let leftPosition = anchorRect.left + (anchorRect.width / 2) - (flyoutWidth / 2);
+        
+        const windowWidth = window.innerWidth;
+        const windowHeight = window.innerHeight;
+        if (leftPosition < 8) leftPosition = 8;
+        if (topPosition < 8) topPosition = 8;
+        if (leftPosition + flyoutWidth > windowWidth) leftPosition = windowWidth - flyoutWidth - 8;
+        if (topPosition + flyoutHeight > windowHeight) topPosition = windowHeight - flyoutHeight - 8;
+
+        flyoutElem.style.top = `${topPosition}px`;
+        flyoutElem.style.left = `${leftPosition}px`;
+    }
+}
+
+// This is the new main function called by Gradio's .then() event
+function update_flyout_from_state(jsonData) {
+    //console.log("JS: update_flyout_from_state() called with data:", jsonData);
+    
+    if (!jsonData) return;
+ 
+    const state = JSON.parse(jsonData);
+    const { isVisible, anchorId, targetId } = state;
+    const flyout = document.getElementById(targetId);
+
+    if (!flyout) {
+        console.error("ERROR: Cannot update UI. Flyout container not found.");
+        return;
+    }
+    //console.log("JS: Parsed state:", { isVisible, anchorId });
+    if (isVisible) {
+        flyout.style.display = 'flex';
+        position_flyout(anchorId, targetId);
+    } else {
+        flyout.style.display = 'none';
+    }
+}

ui/style.css

@@ -0,0 +1,301 @@
+/* ==========================================================================
+   1. GLOBAL & LAYOUT STYLES
+   ========================================================================== */
+
+body {
+    font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
+    margin: 0;
+    padding: 0;
+}
+
+/* Main application container styling */
+.gradio-container {
+    border-radius: 15px;
+    padding: 10px 10px; 
+    box-shadow: 0 8px 30px rgba(0, 0, 0, 0.3); 
+    margin: 40px 350px;
+}
+
+/* Text shadow for main headings for better readability */
+.gradio-container h1 {
+    text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.2);
+}
+
+/* Utility class to make elements fill their container's width */
+.fillable {
+    width: 100% !important;
+    max-width: unset !important; 
+}
+.fillable .sidebar-parent {
+    padding-left: 10px !important;
+    padding-right: 10px !important;
+}
+
+.credit-panel .outer-credits-wrapper .credits-panel-wrapper {
+    min-height: 80vh !important;
+    max-height: 700px;
+}
+.media-gallery-row {
+    min-height: 80vh !important;
+    max-height: 700px;
+}
+/* ==========================================================================
+   2. CUSTOM SCROLLBAR STYLES (GLOBAL & SIDEBAR)
+   ========================================================================== */
+
+/* --- For WebKit browsers (Chrome, Safari, Edge, etc.) --- */
+.sidebar-content::-webkit-scrollbar,
+body::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+  background-color: transparent;
+}
+
+.sidebar-content::-webkit-scrollbar-track,
+body::-webkit-scrollbar-track {
+  background: transparent;
+  border-radius: 10px;
+}
+
+.sidebar-content::-webkit-scrollbar-thumb,
+body::-webkit-scrollbar-thumb {
+  background-color: rgba(136, 136, 136, 0.4);
+  border-radius: 10px;
+  border: 2px solid transparent;
+  background-clip: content-box;
+}
+
+.sidebar-content::-webkit-scrollbar-thumb:hover,
+body::-webkit-scrollbar-thumb:hover {
+  background-color: rgba(136, 136, 136, 0.7);
+}
+
+/* --- For Firefox --- */
+.sidebar-content,
+html {
+  scrollbar-width: thin;
+  scrollbar-color: rgba(136, 136, 136, 0.7) transparent;
+}
+
+
+/* ==========================================================================
+   3. SIDEBAR STYLES
+   ========================================================================== */
+
+.sidebar {
+    border-radius: 10px;
+    padding: 10px;
+    box-shadow: 0 4px 15px rgba(0, 0, 0, 0.2);
+}
+/* .top-bar, .bottom-bar {
+    border-radius: 10px;    
+    box-shadow: 0 4px 15px rgba(0, 0, 0, 0.2);
+} */
+/* Overrides for the content padding inside the sidebar */
+.sidebar .sidebar-content {
+    padding-left: 10px !important;
+    padding-right: 10px !important;
+}
+
+/* Centers text within Markdown blocks inside the sidebar */
+.sidebar .sidebar-content .column .block div .prose {
+    text-align: center;
+}
+
+/* Stylish override for the sidebar toggle button */
+.sidebar .toggle-button {    
+    background: linear-gradient(90deg, #34d399, #10b981) !important;
+    border: none;
+    padding: 12px 18px;
+    text-transform: uppercase;
+    font-weight: bold;
+    letter-spacing: 1px;
+    border-radius: 5px;
+    position: absolute;
+    top: 50%;        
+    right: -28px !important;
+    left: auto !important;
+    transform: unset !important;   
+}
+
+.sidebar.right .toggle-button {
+    left: -28px !important;
+    right: auto !important; 
+    transform: rotate(180deg) !important;
+}
+
+.sidebar.open .chevron-left {
+    transform: rotate(-135deg);
+}
+
+.top-bar .toggle-top-button, .bottom-bar .toggle-bottom-button {
+    background: linear-gradient(90deg, #34d399, #10b981) !important;
+    border: none;
+    padding: 12px 18px;
+    text-transform: uppercase;
+    font-weight: bold;
+    letter-spacing: 1px;
+    border-radius: 5px;
+    cursor: pointer;
+    transition: transform 0.2s ease-in-out;
+    /* right: -20px !important; */
+} 
+.toggle-button:hover {
+    transform: scale(1.05);
+} 
+
+
+/* ==========================================================================
+   4. FLYOUT POPOVER STYLES
+   ========================================================================== */
+
+/* The context area from which the flyout is positioned */
+.flyout-context-area {
+    position: relative !important;
+    overflow: visible !important; /* Allows flyout to render outside its parent */
+}
+
+/* The main flyout container (the popover itself) */
+.flyout-container {
+    position: fixed !important;
+    z-index: 1000;
+    width: 350px !important;
+    background: var(--panel-background-fill, white);
+    border-radius: var(--radius-lg);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+    padding: var(--spacing-lg) !important;
+    /* Reset flex properties that might be inherited */
+    flex-grow: 0 !important;
+    min-width: unset !important;
+    align-self: center !important;
+}
+
+/* Allows tooltips inside a PropertySheet within a flyout to be visible */
+.flyout-container .propertysheet-wrapper .content-wrapper .container {
+    overflow: visible !important;
+}
+
+/* The hidden container for the flyout's initial content */
+.flyout-source-hidden {
+    display: none !important;
+}
+
+/* The close (X) button for the flyout */
+.flyout-close-btn {
+    position: absolute;
+    top: 5px;
+    right: 8px;
+    z-index: 1001; /* Should be on top of flyout content */
+    background: transparent !important;
+    border: none !important;
+    box-shadow: none !important;
+    color: #ef0000 !important;
+    min-width: 24px !important;
+    width: 24px !important;
+    height: 24px !important;
+    padding: 0 !important;
+    font-size: 1.2em !important;
+    line-height: 1;
+}
+
+/* .flyout-close-btn button:hover {
+    color: var(--body-text-color) !important;
+} */
+.flyout-container .block .image-container .icon-button-wrapper {
+	right: 20px !important
+}
+.flyout-container .block .image-container > button {
+	border: none !important;
+    border-radius: 0 !important;
+}
+#flyout_sheet > div.content-wrapper > div > div > div > div {
+    color: var(--button-secondary-text-color);
+}
+/* ==========================================================================
+   5. COMPONENT-SPECIFIC STYLES & OVERRIDES
+   ========================================================================== */
+
+/* Custom styling for the cancel button */
+#cancel-button { /* Corrected the typo from 'cancell' to 'cancel' */
+    background: linear-gradient(120deg, var(--neutral-500) 0%, var(--neutral-600) 60%, var(--neutral-700) 100%) !important;
+}
+.custom-dropdown .wrap-inner input {
+    padding-right: 22px;
+}
+/* --- Styles for creating dropdowns with integrated "ear" buttons --- */
+
+/* Container that looks like a single input field */
+.fake-input-container {
+    border: var(--input-border-width) solid var(--border-color-primary);
+    border-radius: var(--input-radius);
+    background: var(--block-background-fill) !important;
+    box-shadow: var(--input-shadow);
+    transition: box-shadow 0.2s, border-color 0.2s;
+    padding: 0 !important;
+    align-items: stretch !important;
+    gap: 0 !important;
+}
+
+.fake-input-container:focus-within {
+    box-shadow: var(--input-shadow-focus);
+    border-color: var(--input-border-color-focus);
+}
+
+/* Removes the default border from a Gradio dropdown when it's inside our fake container */
+.no-border-dropdown .form {
+    border: none !important;
+    box-shadow: none !important;
+    background: transparent !important;
+}
+
+/* The settings (gear) button next to the dropdown */
+.integrated-ear-btn {
+    align-self: center;
+    background: none !important;
+    border: none !important;
+    box-shadow: none !important;
+    color: var(--body-text-color-subdued) !important;
+    font-size: 1.1em;
+    min-width: 28px !important;
+    width: 28px !important;
+    height: 100% !important;
+    padding: 20px var(--spacing-sm) 0 0 !important;
+    transition: color 0.2s ease-in-out;
+    flex-grow: 0 !important;
+}
+
+.integrated-ear-btn:hover {
+    color: var(--body-text-color) !important;
+}
+
+.row-form-size .form {
+    flex-grow: 0 !important;
+    min-width: 50% !important;
+}
+
+.row-form-size-2 .form {
+    flex-grow: 0 !important;
+    min-width: 97% !important;
+}
+
+/* --- Misc Component Tweaks --- */
+
+/* Removes the gap from a specific group of settings */
+.group {
+    gap: unset !important;
+}
+
+/* Targets a styler inside the sampler group to reset form gap */
+.group .styler {
+    --form-gap-width: 0px !important;
+}
+
+/* Example of how to center content in Gradio's example components */
+#examples_container {
+    margin: auto;
+    width: 90%;
+}
+
+#examples_row {
+    justify-content: center;
+}

ui/ui_config.py

@@ -0,0 +1,1360 @@
+# Copyright 2025 The DEVAIEXP Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass, field
+from typing import List, Literal
+
+import sup_toolbox.modules.FaithDiff
+import sup_toolbox.modules.IPAdapter
+import sup_toolbox.modules.MoDControlTile
+import sup_toolbox.modules.SUPIR
+from sup_toolbox.config import PAG_LAYERS
+from sup_toolbox.enums import ImageSizeFixMode, SUPIRModel
+from sup_toolbox.utils.system import find_dist_info_files, get_module_file
+
+
+LICENSE_PATHS = {
+    "NOTICE": "./NOTICE",
+    "SUP-ToolBox License": "./LICENSE",
+    "SUPIR Component": get_module_file(sup_toolbox.modules.SUPIR, "LICENSE_SUPIR.md"),
+    "FaithDiff Component": get_module_file(sup_toolbox.modules.FaithDiff, "LICENSE_FAITHDIFF.md"),
+    "MoDControlTile Component": get_module_file(sup_toolbox.modules.MoDControlTile, "LICENSE_MIXTURE_OF_DIFFUSERS.md"),
+    "IPAdapter Component": get_module_file(sup_toolbox.modules.IPAdapter, "LICENSE_IPADAPTER.md"),
+    "Diffusers": find_dist_info_files("diffusers", "LICENSE"),
+    "SUP-ToolBox App Changelog": "./CHANGELOG.md",
+    "SUP-ToolBox CLI Changelog": get_module_file(sup_toolbox, "CHANGELOG.md"),
+}
+
+CREDIT_LIST = [
+    # Publisher/Developer Credit
+    {"title": "Developed By", "name": "DEVAIEXP"},
+    # Core Development Section
+    {"section_title": "Core Development"},
+    {"title": "Principal Developer & Solution Architect", "name": "Eliseu Silva"},
+    # SUPIR
+    {"section_title": "SUPIR Restoration Pipeline"},
+    {"title": "Original work by", "name": "SupPixel Pty Ltd"},
+    {"title": "Adapted for Diffusers by", "name": "DEVAIEXP"},
+    {"section_title": "SUPIR - Original Authors"},
+    {"title": "Lead Researcher", "name": "Dr. Jinjin Gu"},
+    {"title": "Contributing Author", "name": "Fanghua Yu"},
+    {"title": "Contributing Author", "name": "Zheyuan Li"},
+    {"title": "Contributing Author", "name": "Jinfan Hu"},
+    {"title": "Contributing Author", "name": "Xiangtao Kong"},
+    {"title": "Contributing Author", "name": "Xintao Wang"},
+    {"title": "Contributing Author", "name": "Jingwen He"},
+    {"title": "Contributing Author", "name": "Yu Qiao"},
+    {"title": "Contributing Author", "name": "Chao Dong"},
+    # FaithDiff
+    {"section_title": "FaithDiff Super-Resolution Pipeline"},
+    {"title": "Original work by", "name": "Junyang Chen"},
+    {"title": "Adapted and improved by", "name": "DEVAIEXP"},
+    {"section_title": "FaithDiff - Original Authors"},
+    {"title": "Contributing Author", "name": "Junyang Chen"},
+    {"title": "Contributing Author", "name": "Jinshan Pan"},
+    {"title": "Contributing Author", "name": "Jiangxin Dong"},
+    # MoD ControlNet Tile
+    {"section_title": "Mixture of Diffusers for ControlNet Tile Pipeline"},
+    {"title": "Original Pipeline Concept by", "name": "Álvaro Barbero Jiménez"},
+    {"title": "Adapted and improved for ControlNet Union by", "name": "DEVAIEXP"},
+    {"title": "ControlNet Union Model", "name": "Trained by xinsir"},
+    # Key Models & Components Section
+    {"section_title": "Key Models & Components"},
+    {"title": "IP-Adapter Model", "name": "TencentARC"},
+    # Foundational Frameworks Section
+    # Gradio
+    {"section_title": "Gradio Framework"},
+    {"section_title": "Gradio - Original Development Team"},
+    {"title": "Core Contributor", "name": "Abubakar Abid"},
+    {"title": "Core Contributor", "name": "Ali Abdalla"},
+    {"title": "Core Contributor", "name": "Ali Abid"},
+    {"title": "Core Contributor", "name": "Dawood Khan"},
+    {"title": "Core Contributor", "name": "Abdulrahman Alfozan"},
+    {"title": "Core Contributor", "name": "James Zou"},
+    # Diffusers
+    {"section_title": "Diffusers Framework"},
+    {"section_title": "Diffusers - Original Development Team"},
+    {"title": "Core Contributor", "name": "Patrick von Platen"},
+    {"title": "Core Contributor", "name": "Suraj Patil"},
+    {"title": "Core Contributor", "name": "Anton Lozhkov"},
+    {"title": "Core Contributor", "name": "Pedro Cuenca"},
+    {"title": "Core Contributor", "name": "Nathan Lambert"},
+    {"title": "Core Contributor", "name": "Kashif Rasul"},
+    {"title": "Core Contributor", "name": "Mishig Davaadorj"},
+    {"title": "Core Contributor", "name": "Dhruv Nair"},
+    {"title": "Core Contributor", "name": "Sayak Paul"},
+    {"title": "Core Contributor", "name": "William Berman"},
+    {"title": "Core Contributor", "name": "Yiyi Xu"},
+    {"title": "Core Contributor", "name": "Steven Liu"},
+    {"title": "Core Contributor", "name": "Thomas Wolf"},
+]
+
+
+# Dataclass for Application Settings
+@dataclass
+class AppSettings:
+    """Dataclass to hold all general application settings, replacing the old dictionary."""
+
+    # General
+    # civitai_token: str = field(default="", metadata={"component": "password", "label": "CivitAI API Token", "help": "CivitAI API token for downloading models."})
+    save_image_format: Literal[".png", ".jpg", ".webp"] = field(
+        default=".png",
+        metadata={
+            "component": "dropdown",
+            "label": "Save Image Format",
+            "help": "Default format for saving generated images.",
+        },
+    )
+    latest_preset: str = field(
+        default="Default",
+        metadata={"label": "Latest Preset", "help": "The most recently used preset."},
+    )
+
+    # Paths
+    cache_dir: str = field(
+        default="models",
+        metadata={
+            "label": "Cache Path",
+            "help": "Path to a directory to download and cache pre-trained model weights.",
+        },
+    )
+    checkpoints_dir: str = field(
+        default="models/Checkpoints",
+        metadata={
+            "label": "Checkpoints Path",
+            "help": "Directory path for local '.safetensors' model weights.",
+        },
+    )
+    vae_dir: str = field(
+        default="models/VAE",
+        metadata={
+            "label": "VAE Models Path",
+            "help": "Directory path for local VAE '.safetensors' model weights.",
+        },
+    )
+    output_dir: str = field(
+        default="./outputs",
+        metadata={
+            "label": "Output Path",
+            "help": "Directory where generated images will be saved.",
+        },
+    )
+    save_image_on_upscaling_passes: bool = field(
+        default=False,
+        metadata={
+            "label": "Save image in upscaling passes",
+            "help": "Saves intermediate images between image upscaling passes",
+        },
+    )
+
+    # Hardware & Optimizations
+    weight_dtype: Literal["Float16", "Bfloat16", "Float32"] = field(
+        default="Float16",
+        metadata={
+            "component": "dropdown",
+            "label": "Weight Precision",
+            "help": "Precision for loading model weights (e.g., UNet, ControlNet).",
+        },
+    )
+    vae_weight_dtype: Literal["Float16", "Float32"] = field(
+        default="Float16",
+        metadata={
+            "component": "dropdown",
+            "label": "VAE Precision",
+            "help": "Precision for loading the VAE weights. FP16 is often faster.",
+        },
+    )
+    device: Literal["cpu", "cuda", "mps"] = field(
+        default="cuda",
+        metadata={
+            "component": "dropdown",
+            "label": "Computation Device",
+            "help": "The primary device (GPU/CPU) for running the pipelines.",
+        },
+    )
+    generator_device: Literal["cpu", "cuda", "mps"] = field(
+        default="cpu",
+        metadata={
+            "component": "dropdown",
+            "label": "Generator Device",
+            "help": "The primary device (GPU/CPU) for generator seeds.",
+        },
+    )
+    enable_cpu_offload: bool = field(
+        default=True,
+        metadata={
+            "interactive_if": {"field": "device", "neq": "cpu"},
+            "label": "Enable CPU Offload",
+            "help": "Saves VRAM by keeping models on the CPU and moving them to the GPU only when needed during inference.",
+        },
+    )
+    enable_vae_tiling: bool = field(
+        default=True,
+        metadata={
+            "label": "Enable VAE Tiling",
+            "help": "Processes the VAE in tiles to decode large images with less VRAM.",
+        },
+    )
+    enable_vae_slicing: bool = field(
+        default=False,
+        metadata={
+            "label": "Enable VAE Slicing",
+            "help": "Processes image batches one slice at a time through the VAE to save VRAM.",
+        },
+    )
+    memory_attention: Literal["xformers", "sdp"] = field(
+        default="xformers",
+        metadata={
+            "component": "dropdown",
+            "label": "Memory Attention",
+            "help": "Optimized attention mechanism to save VRAM and increase speed (xformers recommended).",
+        },
+    )
+    quantization_method: Literal["None", "Quanto Library", "Layerwise & Bnb"] = field(
+        default="Layerwise & Bnb",
+        metadata={
+            "component": "radio",
+            "label": "Quantization Method",
+            "help": "Quantization mechanism to save VRAM and increase speed.",
+        },
+    )
+    quantization_mode: Literal["FP8", "NF4"] = field(
+        default="FP8",
+        metadata={
+            "interactive_if": {"field": "quantization_method", "neq": "None"},
+            "component": "radio",
+            "label": "Quantization Mode",
+            "help": "Quantization mechanism to save VRAM and increase speed.",
+        },
+    )
+    allow_cuda_tf32: bool = field(
+        default=False,
+        metadata={
+            "label": "Enable cuda TF32",
+            "help": "Enable TensorFloat-32 tensor cores to be used in matrix multiplications on Ampere or newer GPUs. Enable it only if your card is Ampere+ and weight precision type is Float32",
+        },
+    )
+    allow_cudnn_tf32: bool = field(
+        default=False,
+        metadata={
+            "label": "Enable cudnn TF32",
+            "help": "Enable TensorFloat-32 tensor cores to be used in cuDNN convolutions on Ampere or newer GPU. Enable it only if your card is Ampere+ and weight precision type is Float32",
+        },
+    )
+    disable_mmap: bool = field(
+        default=False,
+        metadata={
+            "label": "Disable mmap",
+            "help": "Disable memmapping for loading model files. Enable this if you encounter issues loading models on shared drives or network locations.",
+        },
+    )
+    always_offload_models: bool = field(
+        default=False,
+        metadata={
+            "label": "Always Offload Models",
+            "help": "Offload models to CPU immediately after finishing inference to free up GPU memory. May slow down performance switching between pipelines.",
+        },
+    )
+    run_vae_on_cpu: bool = field(
+        default=False,
+        metadata={
+            "label": "Run VAE on CPU",
+            "help": "Run the VAE on CPU to save GPU memory. This may slow down performance.",
+        },
+    )
+    enable_llava_quantization: bool = field(
+        default=True,
+        metadata={
+            "label": "Enable LLaVA Quantization",
+            "help": "Enable quantization for LLaVA models to save VRAM.",
+        },
+    )
+    llava_quantization_mode: Literal["INT4", "INT8"] = field(
+        default="INT4",
+        metadata={
+            "interactive_if": {"field": "enable_llava_quantization", "value": True},
+            "component": "radio",
+            "label": "LLaVA Quantization Mode",
+            "help": "Quantization mode used for LLaVA model.",
+        },
+    )
+    llava_offload_model: bool = field(
+        default=False,
+        metadata={
+            "label": "LLaVA Offload Model",
+            "help": "Offload the LLaVA model to CPU to save GPU memory. It may slow down performance.",
+        },
+    )
+    llava_weight_dtype: Literal["Float16", "Bfloat16", "Float32"] = field(
+        default="Float16",
+        metadata={
+            "component": "dropdown",
+            "label": "LLaVA Weight Precision",
+            "help": "Precision for loading LLaVA model weights.",
+        },
+    )
+    llava_question_prompt: str = field(
+        default="Describe what you see in this image and put it in prompt format limited to 77 tokens:",
+        metadata={
+            "label": "LLaVA Question Prompt",
+            "help": "Prompt used to query LLaVA for image descriptions.",
+        },
+    )
+
+
+# UI-Specific Dataclass for SUPIR Injection
+@dataclass
+class InjectionScaleConfig:
+    """Configuration for a single dynamic injection scale."""
+
+    scale_end: float = field(
+        default=1.0,
+        metadata={
+            "interactive_if": {"field": "enable_custom_scale", "value": True},
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 2.0,
+            "step": 0.1,
+            "label": "ControlNet Scale",
+            "help": "The weight of the ControlNet guidance.",
+        },
+    )
+    linear: bool = field(
+        default=False,
+        metadata={
+            "interactive_if": {"field": "enable_custom_scale", "value": True},
+            "label": "Use Linear Control",
+            "help": "Linearly increase Control scale during sampling.",
+        },
+    )
+    scale_start: float = field(
+        default=1.0,
+        metadata={
+            "interactive_if": {"field": "linear", "value": True},
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 20.0,
+            "step": 0.1,
+            "label": "ControlNet Scale Start",
+            "help": "The starting value for linear ControlNet guidance.",
+        },
+    )
+    reverse: bool = field(
+        default=False,
+        metadata={
+            "interactive_if": {"field": "linear", "value": True},
+            "label": "Reverse Linear Control",
+            "help": "Linearly decrease ControlNet scale during sampling.",
+        },
+    )
+
+
+@dataclass
+class SUPIRInjectionConfig(InjectionScaleConfig):
+    sft_active: bool = field(
+        default=True,
+        metadata={
+            "label": "Enable injection",
+            "help": "Enable or disable SFT Injection on this stage.",
+        },
+    )
+    enable_custom_scale: bool = field(
+        default=False,
+        metadata={
+            "interactive_if": {"field": "sft_active", "value": True},
+            "label": "Enable custom scale",
+            "help": "Use customizable controlnet scale at this stage.",
+        },
+    )
+
+
+# Reusable Building Blocks for PropertySheet
+@dataclass
+class GenerationSettings:
+    """Defines the core generation parameters, reused in each pipeline config."""
+
+    seed: int = field(
+        default=-1,
+        metadata={
+            "component": "number_integer",
+            "label": "Seed",
+            "help": "The random seed for generation. -1 means a random seed.",
+        },
+    )
+    randomize_seed: bool = field(default=True, metadata={"label": "Randomize Seed"})
+    num_steps: int = field(
+        default=30,
+        metadata={
+            "component": "slider",
+            "minimum": 1,
+            "maximum": 150,
+            "step": 1,
+            "label": "Inference Steps",
+            "help": "Number of denoising steps. More steps can improve quality but take longer.",
+        },
+    )
+    guidance_scale: float = field(
+        default=7.0,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 20.0,
+            "step": 0.1,
+            "label": "Guidance Scale (CFG)",
+            "help": "How strongly the prompt is adhered to.",
+        },
+    )
+    guidance_rescale: float = field(
+        default=0.5,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "step": 0.01,
+            "label": "Guidance Rescale",
+            "help": "Guidance rescale factor (phi).",
+        },
+    )
+    num_images: int = field(
+        default=1,
+        metadata={
+            "component": "slider",
+            "minimum": 1,
+            "maximum": 16,
+            "step": 1,
+            "label": "Number of Images",
+            "help": "Number of output images.",
+        },
+    )
+    image_size_fix_mode: Literal[tuple(member.value for member in ImageSizeFixMode)] = field(
+        default=ImageSizeFixMode.ProgressiveResize.value,
+        metadata={
+            "component": "dropdown",
+            "label": "Image Size Fix Mode",
+            "help": "Method to handle aspect ratio mismatches during processing.",
+        },
+    )
+    tile_size: Literal[1024, 1280] = field(
+        default=1280,
+        metadata={
+            "component": "dropdown",
+            "label": "Tile Size",
+            "help": "The size (in pixels) of the square tiles to use when latent tiling is enabled.",
+        },
+    )
+    upscaling_mode: Literal["Progressive", "Direct"] = field(
+        default="Direct",
+        metadata={
+            "component": "radio",
+            "label": "Upscaling Mode",
+            "help": "Choose 'Progressive' for maximum final quality, especially at high scaling factors. Choose 'Direct' for faster processing and previews.",
+        },
+    )
+    upscale_factor: Literal[
+        "2x",
+        "3x",
+        "4x",
+        "5x",
+        "6x",
+        "7x",
+        "8x",
+        "9x",
+        "10x",
+        "11x",
+        "12x",
+        "13x",
+        "14x",
+        "15x",
+        "16x",
+    ] = field(
+        default="2x",
+        metadata={
+            "component": "radio",
+            "label": "Upscale Factor",
+            "help": "Resolution upscale x1 to x10",
+        },
+    )
+    cfg_decay_rate: float = field(
+        default=0.5,
+        metadata={
+            "interactive_if": {"field": "upscaling_mode", "value": "Progressive"},
+            "component": "slider",
+            "label": "CFG Decay Rate",
+            "minimum": 0.0,
+            "maximum": 0.9,
+            "step": 0.05,
+            "help": (
+                "The percentage to reduce the Guidance Scale (CFG) at each progressive "
+                "upscaling pass. A value of 0.5 means the CFG is halved at each step. "
+                "Set to 0.0 to keep the CFG constant."
+            ),
+        },
+    )
+    strength_decay_rate: float = field(
+        default=0.5,
+        metadata={
+            "interactive_if": {"field": "upscaling_mode", "value": "Progressive"},
+            "component": "slider",
+            "label": "Strength Decay Rate",
+            "minimum": 0.0,
+            "maximum": 0.9,
+            "step": 0.05,
+            "help": (
+                "The percentage to reduce the Denoising Strength at each progressive "
+                "upscaling pass. A value of 0.5 means the strength is halved at each step. "
+                "Set to 0.0 to keep the strength constant."
+            ),
+        },
+    )
+
+
+@dataclass
+class CFGSettings:
+    """Defines advanced settings for Classifier-Free Guidance."""
+
+    use_linear_CFG: bool = field(
+        default=False,
+        metadata={
+            "label": "Use Linear CFG",
+            "help": "Linearly increase CFG scale during sampling.",
+        },
+    )
+    reverse_linear_CFG: bool = field(
+        default=False,
+        metadata={
+            "interactive_if": {"field": "use_linear_CFG", "value": True},
+            "label": "Reverse Linear CFG",
+            "help": "Linearly decrease CFG scale during sampling.",
+        },
+    )
+    guidance_scale_start: float = field(
+        default=1.0,
+        metadata={
+            "interactive_if": {"field": "use_linear_CFG", "value": True},
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 20.0,
+            "step": 0.1,
+            "label": "Guidance Scale Start",
+            "help": "The starting value for linear CFG scaling.",
+        },
+    )
+
+
+@dataclass
+class ControlNetScaleSettings:
+    """Defines settings for ControlNet conditioning scale."""
+
+    controlnet_conditioning_scale: float = field(
+        default=1.0,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 2.0,
+            "step": 0.05,
+            "label": "ControlNet Scale",
+            "help": "The weight of the ControlNet guidance.",
+        },
+    )
+    use_linear_control_scale: bool = field(
+        default=False,
+        metadata={
+            "label": "Use Linear Control Scale",
+            "help": "Linearly increase ControlNet scale during sampling.",
+        },
+    )
+    reverse_linear_control_scale: bool = field(
+        default=False,
+        metadata={
+            "interactive_if": {"field": "use_linear_control_scale", "value": True},
+            "label": "Reverse Linear Control Scale",
+            "help": "Linearly decrease ControlNet scale during sampling.",
+        },
+    )
+    control_scale_start: float = field(
+        default=0.7,
+        metadata={
+            "interactive_if": {"field": "use_linear_control_scale", "value": True},
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "step": 0.05,
+            "label": "Control Scale Start",
+            "help": "The starting value for linear ControlNet scaling.",
+        },
+    )
+
+
+@dataclass
+class PAGSettings:
+    """Defines settings for Perturbed Attention Guidance."""
+
+    enable_PAG: bool = field(default=False, metadata={"label": "Enable PAG"})
+    pag_scale: float = field(
+        default=3.0,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 10.0,
+            "step": 0.1,
+            "label": "PAG Scale",
+            "interactive_if": {"field": "enable_PAG", "value": True},
+            "help": "The scale factor for the perturbed attention guidance.",
+        },
+    )
+    use_linear_PAG: bool = field(
+        default=False,
+        metadata={
+            "label": "Use Linear PAG",
+            "interactive_if": {"field": "enable_PAG", "value": True},
+            "help": "Linearly increase PAG scale during sampling.",
+        },
+    )
+    reverse_linear_PAG: bool = field(
+        default=False,
+        metadata={
+            "label": "Reverse Linear PAG",
+            "interactive_if": {"field": "enable_PAG", "value": True},
+            "help": "Linearly decrease PAG scale during sampling.",
+        },
+    )
+    pag_scale_start: float = field(
+        default=1.0,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 10.0,
+            "step": 0.1,
+            "label": "PAG Scale Start",
+            "interactive_if": {"field": "enable_PAG", "value": True},
+            "help": "The starting value for linear PAG scaling.",
+        },
+    )
+    pag_layers: List[str] = field(
+        default_factory=lambda: ["mid"],
+        metadata={
+            "component": "multiselect_checkbox",
+            "choices": list(PAG_LAYERS.keys()),
+            "label": "PAG Layers",
+            "interactive_if": {"field": "enable_PAG", "value": True},
+            "help": "Select the UNet layers where Perturbed Attention Guidance should be applied.",
+        },
+    )
+
+
+@dataclass
+class PostprocessingSettings:
+    color_fix_mode: Literal["None", "Adain", "Wavelet"] = field(
+        default="None",
+        metadata={
+            "component": "radio",
+            "label": "Color Fix Mode",
+            "help": "Applies the color profile of the input image to the generated image using one of the chosen algorithms.",
+        },
+    )
+
+
+# Main Configuration Dataclasses for Each Pipeline
+@dataclass
+class SUPIR_Config:
+    """Complete configuration for a SUPIR pipeline run."""
+
+    apply_prompt_2: bool = field(
+        default=True,
+        metadata={
+            "label": "Apply Prompt 2",
+            "help": "If enabled, concatenates prompt 2 with prompt 1.",
+        },
+    )
+    supir_model: Literal[tuple(member.value for member in SUPIRModel)] = field(
+        default=SUPIRModel.Quality.value,
+        metadata={
+            "component": "radio",
+            "label": "Model Type",
+            "help": "Weights of the SUPIR model used. Quality or Fidelity.",
+        },
+    )
+    restoration_scale: float = field(
+        default=4.0,
+        metadata={
+            "component": "slider",
+            "label": "Restoration Scale",
+            "minimum": 0.0,
+            "maximum": 4.0,
+            "step": 0.1,
+            "help": "Strength of the SUPIR restoration guidance.",
+        },
+    )
+    s_churn: float = field(
+        default=0.0,
+        metadata={
+            "component": "slider",
+            "label": "S Churn",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "step": 0.01,
+            "help": "Stochasticity churn factor.",
+        },
+    )
+    s_noise: float = field(
+        default=1.003,
+        metadata={
+            "component": "slider",
+            "label": "S Noise",
+            "minimum": 1.0,
+            "maximum": 1.01,
+            "step": 0.001,
+            "help": "Stochasticity noise factor.",
+        },
+    )
+    start_point: Literal["lr", "noise"] = field(
+        default="lr",
+        metadata={
+            "component": "dropdown",
+            "label": "Start Point",
+            "help": "Start from low-res latents ('lr') or pure noise ('noise').",
+        },
+    )
+    strength: float = field(
+        default=1.0,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "step": 0.01,
+            "label": "Denoising Strength",
+            "help": "How much to denoise the original image. 1.0 is full denoising.",
+        },
+    )
+    general: GenerationSettings = field(default_factory=GenerationSettings, metadata={"label": "Image Generation"})
+    cfg_settings: CFGSettings = field(default_factory=CFGSettings, metadata={"label": "Guidance Scale (CFG) - Advanced"})
+    controlnet_settings: ControlNetScaleSettings = field(default_factory=ControlNetScaleSettings, metadata={"label": "ControlNet - Advanced"})
+    pag_settings: PAGSettings = field(default_factory=PAGSettings, metadata={"label": "PAG - Perturbed Attention Guidance"})
+    post_processsing_settings: PostprocessingSettings = field(default_factory=PostprocessingSettings, metadata={"label": "Image Post-Processing"})
+
+
+@dataclass
+class SUPIRAdvanced_Config:
+    """SFT Injection advanced configuration settings."""
+
+    sft_post_mid: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Post Mid"})
+    sft_up_block_0_stage0: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 0 Stage 0"})
+    sft_up_block_0_stage1: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 0 Stage 1"})
+    sft_up_block_0_stage2: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 0 Stage 2"})
+    sft_up_block_1_stage0: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 1 Stage 0"})
+    sft_up_block_1_stage1: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 1 Stage 1"})
+    sft_up_block_1_stage2: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 1 Stage 2"})
+    sft_up_block_2_stage0: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 2 Stage 0"})
+    sft_up_block_2_stage1: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 2 Stage 1"})
+    sft_up_block_2_stage2: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "SFT Up Block 2 Stage 2"})
+    cross_up_block_0_stage1: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "Cross Up Block 0 Stage 1"})
+    cross_up_block_0_stage2: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "Cross Up Block 0 Stage 2"})
+    cross_up_block_1_stage1: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "Cross Up Block 1 Stage 1"})
+    cross_up_block_1_stage2: SUPIRInjectionConfig = field(default_factory=SUPIRInjectionConfig, metadata={"label": "Cross Up Block 1 Stage 2"})
+
+
+@dataclass
+class FaithDiff_Config:
+    """Complete configuration for a FaithDiff pipeline run."""
+
+    apply_prompt_2: bool = field(
+        default=True,
+        metadata={
+            "label": "Apply Prompt 2",
+            "help": "If enabled, concatenates prompt 2 with prompt 1.",
+        },
+    )
+    invert_prompts: bool = field(
+        default=True,
+        metadata={
+            "label": "Invert Prompts",
+            "help": "Starts the send prompt with prompt 2 and ends with prompt 1.",
+        },
+    )
+    apply_ipa_embeds: bool = field(
+        default=True,
+        metadata={
+            "label": "Apply IPA Embeds",
+            "help": "Apply IP-Adapter embeddings during diffusion.",
+        },
+    )
+    s_churn: float = field(
+        default=0.0,
+        metadata={
+            "component": "slider",
+            "label": "S Churn",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "step": 0.01,
+            "help": "Stochasticity churn factor.",
+        },
+    )
+    s_noise: float = field(
+        default=1.003,
+        metadata={
+            "component": "slider",
+            "label": "S Noise",
+            "minimum": 1.0,
+            "maximum": 1.01,
+            "step": 0.001,
+            "help": "Stochasticity noise factor.",
+        },
+    )
+    start_point: Literal["lr", "noise"] = field(
+        default="lr",
+        metadata={
+            "component": "dropdown",
+            "label": "Start Point",
+            "help": "Start from low-res latents ('lr') or pure noise ('noise').",
+        },
+    )
+    strength: float = field(
+        default=1.0,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "step": 0.01,
+            "label": "Denoising Strength",
+            "help": "How much to denoise the original image. 1.0 is full denoising.",
+        },
+    )
+    general: GenerationSettings = field(default_factory=GenerationSettings, metadata={"label": "Image Generation"})
+    controlnet_settings: ControlNetScaleSettings = field(default_factory=ControlNetScaleSettings, metadata={"label": "ControlNet - Advanced"})
+    pag_settings: PAGSettings = field(default_factory=PAGSettings, metadata={"label": "PAG - Perturbed Attention Guidance"})
+    post_processsing_settings: PostprocessingSettings = field(default_factory=PostprocessingSettings, metadata={"label": "Image Post-Processing"})
+
+
+@dataclass
+class ControlNetTile_Config:
+    """Complete configuration for a ControlNetTile pipeline run."""
+
+    apply_prompt_2: bool = field(
+        default=True,
+        metadata={
+            "label": "Apply Prompt 2",
+            "help": "If enabled, concatenates prompt 2 with prompt 1.",
+        },
+    )
+    controlnet_conditioning_scale: float = field(
+        default=1.0,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 2.0,
+            "step": 0.05,
+            "label": "ControlNet Scale",
+            "help": "The weight of the ControlNet Tile guidance.",
+        },
+    )
+    tile_overlap: int = field(
+        default=128,
+        metadata={
+            "component": "slider",
+            "label": "Tile Overlap",
+            "minimum": 64,
+            "maximum": 512,
+            "step": 16,
+            "help": "Overlap in pixels between tiles to reduce seams.",
+        },
+    )
+    tile_weighting_method: Literal["Cosine", "Gaussian"] = field(
+        default="Cosine",
+        metadata={
+            "component": "radio",
+            "label": "Tile Weighting Method",
+            "help": "Method for blending tile edges.",
+        },
+    )
+    tile_gaussian_sigma: float = field(
+        default=0.3,
+        metadata={
+            "interactive_if": {"field": "tile_weighting_method", "value": "Gaussian"},
+            "component": "slider",
+            "label": "Tile Guassian Sigma",
+            "minimum": 0.05,
+            "maximum": 2.0,
+            "step": 0.01,
+            "help": "Sigma parameter for Gaussian weighting of tiles.",
+        },
+    )
+    strength: float = field(
+        default=0.65,
+        metadata={
+            "component": "slider",
+            "minimum": 0.0,
+            "maximum": 1.0,
+            "step": 0.01,
+            "label": "Denoising Strength",
+            "help": "How much to denoise the original image. 1.0 is full denoising.",
+        },
+    )
+    general: GenerationSettings = field(default_factory=GenerationSettings, metadata={"label": "Image Generation"})
+    post_processsing_settings: PostprocessingSettings = field(default_factory=PostprocessingSettings, metadata={"label": "Image Post-Processing"})
+
+
+# Data for Flyout popups
+@dataclass
+class SchedulerSettings:
+    """Settings to the sampler."""
+
+    scale_linear_exponent: float = field(
+        default=1.93,
+        metadata={
+            "component": "slider",
+            "label": "Scale Linear Exponent",
+            "minimum": 0.0,
+            "maximum": 2.0,
+            "step": 0.01,
+            "help": "Exponent for the scale linear beta schedule.",
+        },
+    )
+
+
+# PropertySheet value Mappings
+RESTORER_CONFIG_MAPPING = {
+    "SUPIR": SUPIR_Config(),
+    "SUPIRAdvanced": SUPIRAdvanced_Config(),
+    "FaithDiff": FaithDiff_Config(),
+}
+
+UPSCALER_CONFIG_MAPPING = {
+    "SUPIR": SUPIR_Config(),
+    "SUPIRAdvanced": SUPIRAdvanced_Config(),
+    "FaithDiff": FaithDiff_Config(),
+    "ControlNetTile": ControlNetTile_Config(),
+}
+SAMPLER_MAPPING = {
+    "restorer_sampler": SchedulerSettings(scale_linear_exponent=1.93),
+    "upscaler_sampler": SchedulerSettings(scale_linear_exponent=2.0),
+}
+
+# PropertySheet change rules mapping
+APPSETTINGS_SHEET_DEPENDENCY_RULES = {
+    "dynamic_dependencies": {
+        "quantization_method": {
+            "actions": [
+                {
+                    "type": "update_options",
+                    "target_field_path": "quantization_mode",
+                    "mapping": {
+                        "None": {"options": ["FP8", "NF4"], "new_default": "FP8"},
+                        "Layerwise & Bnb": {"options": ["FP8", "NF4"], "new_default": "FP8"},
+                        "Quanto Library": {"options": ["INT8", "INT4"], "new_default": "INT8"},
+                    },
+                },
+            ]
+        },
+        "device": {
+            "actions": [
+                {
+                    "type": "update_options",
+                    "target_field_path": "weight_dtype",
+                    "mapping": {
+                        "balanced": {
+                            "options": ["Float16", "Bfloat16", "Float32"],
+                            "new_default": None,
+                        },
+                        "cpu": {"options": ["Float32"], "new_default": "Float32"},
+                        "cuda": {
+                            "options": ["Float16", "Bfloat16", "Float32"],
+                            "new_default": None,
+                        },
+                        "mps": {"options": ["Float16", "Bfloat16", "Float32"], "new_default": None},
+                    },
+                },
+                {
+                    "type": "update_options",
+                    "target_field_path": "vae_weight_dtype",
+                    "mapping": {
+                        "balanced": {"options": ["Float16", "Float32"], "new_default": None},
+                        "cpu": {"options": ["Float32"], "new_default": "Float32"},
+                        "cuda": {"options": ["Float16", "Float32"], "new_default": None},
+                        "mps": {"options": ["Float16", "Float32"], "new_default": None},
+                    },
+                },
+                {
+                    "type": "set_value",
+                    "target_field_path": "enable_cpu_offload",
+                    "mapping": {"cpu": False},
+                },
+            ]
+        },
+    },
+    "on_load_actions": [],
+}
+
+UPSCALER_SHEET_DEPENDENCY_RULES = {
+    "dynamic_dependencies": {
+        "general.upscaling_mode": {
+            "actions": [
+                {
+                    "type": "update_options",
+                    "target_field_path": "general.upscale_factor",
+                    "mapping": {
+                        "Progressive": {
+                            "options": ["2x", "4x", "6x", "8x", "16x"],
+                            "new_default": None,
+                        },
+                        "Direct": {
+                            "options": [
+                                "2x",
+                                "3x",
+                                "4x",
+                                "5x",
+                                "6x",
+                                "7x",
+                                "8x",
+                                "9x",
+                                "10x",
+                                "11x",
+                                "12x",
+                                "13x",
+                                "14x",
+                                "15x",
+                                "16x",
+                            ],
+                            "new_default": None,
+                        },
+                    },
+                },
+            ]
+        }
+    },
+    "on_load_actions": [],
+}
+RESTORER_SHEET_DEPENDENCY_RULES = {
+    "dynamic_dependencies": {
+        "general.upscaling_mode": {
+            "actions": [
+                {
+                    "type": "update_options",
+                    "target_field_path": "general.upscale_factor",
+                    "mapping": {
+                        "Progressive": {
+                            "options": ["2x", "4x", "6x", "8x", "16x"],
+                            "new_default": None,
+                        },
+                        "Direct": {"options": ["1x", "2x", "3x", "4x"], "new_default": "1x"},
+                    },
+                },
+            ]
+        }
+    },
+    "on_load_actions": [
+        # Each item in the list is an action to perform.
+        {
+            "type": "update_visibility",
+            "target_field_path": "general.upscaling_mode",
+            "visible": False,
+        },
+        {
+            "type": "update_visibility",
+            "target_field_path": "general.cfg_decay_rate",
+            "visible": False,
+        },
+        {
+            "type": "update_visibility",
+            "target_field_path": "general.strength_decay_rate",
+            "visible": False,
+        },
+        {
+            "type": "update_visibility",
+            "target_field_path": "general.upscale_factor",
+            "visible": False,
+        },
+        # You could add more direct actions here..
+    ],
+}
+SUPIR_ADVANCED_RULES = {"dynamic_dependencies": {}, "on_load_actions": []}
+
+# Default prompt dictionary for each engine type
+DEFAULT_PROMPTS = {
+    "Restorer": {
+        "SUPIR": {
+            "prompt": "Direct flash photography. [subject].",
+            "prompt_2": "Extremely detailed faces, flawless natural skin texture, skin pore detailing, 4k, 8k, clean image, no noise, shot on Fujifilm Superia 400, sharp focus, faithful colors.",
+            "negative_prompt": "low-res, disfigured, analog artifacts, smudged, animate, (out of focus:1.2), catchlights, over-smooth, extra eyes, worst quality, unreal engine, art, aberrations, surreal, pastel drawing, harsh lighting, dead eyes, deformed fingers, undistinct fingers outlines",
+        },
+        "FaithDiff": {
+            "prompt": "[subject].",
+            "prompt_2": "Ultra-quality photography, flawless natural skin texture, shot on Fujifilm Superia 400, clean image, sharp focus.",
+            "negative_prompt": "low res, worst quality, blurry, out of focus, analog artifacts, oil painting, illustration, art, anime, cartoon, CG Style, unreal engine, render, artwork, (wrinkles:1.4), fine lines, smile lines, age spots, (blemishes:1.2), acne, scars, freckles, blotchy skin, deformed mouth, catchlights",
+        },
+    },
+    "Upscaler": {
+        "SUPIR": {
+            "prompt": "Extremely detailed faces, flawless natural skin texture, skin pore detailing, 4k, 8k, clean image, no noise, shot on Fujifilm Superia 400, sharp focus, faithful colors.",
+            "prompt_2": "",
+            "negative_prompt": "blurry, pixelated, noisy, low resolution, artifacts, poor details, (oversaturated:2.5), (overexposed:2.5)",
+        },
+        "FaithDiff": {
+            "prompt": "Ultra-quality photography, flawless natural skin texture, shot on Fujifilm Superia 400, clean image, sharp focus.",
+            "prompt_2": "",
+            "negative_prompt": "low res, worst quality, blurry, out of focus, analog artifacts, oil painting, illustration, art, anime, cartoon, CG Style, unreal engine, render, artwork, (wrinkles:1.4), fine lines, smile lines, age spots, (blemishes:1.2), acne, scars, freckles, blotchy skin, deformed mouth, catchlights",
+        },
+        "ControlNetTile": {
+            "prompt": "high-quality, noise-free edges, high quality, 4k, hd, 8k",
+            "prompt_2": "",
+            "negative_prompt": "blurry, pixelated, noisy, low resolution, artifacts, poor details",
+        },
+    },
+}
+
+
+TAG_DATA_POSITIVE = {
+    # POSITIVE PROMPTS
+    "Quality": [
+        "best quality",
+        "high quality",
+        "masterpiece",
+        "ultra high resolution",
+        "high resolution",
+        "4k",
+        "8k",
+        "extremely detailed",
+        "ultra-detailed",
+        "hyper detailed",
+        "intricate details",
+        "sharp focus",
+        "crisp details",
+        "sharp",
+        "hyper sharpness",
+    ],
+    "Style": [
+        "photorealistic",
+        "realistic photo",
+        "photograph",
+        "digital photograph",
+        "professional photography",
+        "direct flash photography",
+        "soft studio lighting",
+        "natural lighting",
+        "softbox lighting",
+        "cinematic",
+        "filmic",
+        "shot on [Camera Name]",
+        "Fujifilm Superia 400",
+        "Kodak Portra 400",
+        "early 2000s aesthetic",
+        "modern look",
+        "editorial fashion photo",
+        "beauty portrait",
+    ],
+    "Subject & Details": [
+        "natural skin texture",
+        "realistic skin",
+        "subtle skin variations",
+        "visible micro-details",
+        "matte skin finish",
+        "poreless skin",
+        "flawless skin",
+        "realistic eyes",
+        "detailed eyes",
+        "natural catchlights",
+        "crisp whiskers",
+        "dense fur",
+        "realistic fur texture",
+        "individual hair strands",
+        "multi-layered fur texture",
+        "detailed clothing",
+        "realistic fabric texture",
+        "clothing folds",
+    ],
+}
+
+TAG_DATA_NEGATIVE = {
+    # NEGATIVE PROMPTS
+    "Negative - General Quality & Artifacts": [
+        "worst quality",
+        "low quality",
+        "normal quality",
+        "bad quality",
+        "low-res",
+        "low resolution",
+        "jpeg artifacts",
+        "compression artifacts",
+        "grain",
+        "grainy",
+        "noisy",
+        "blurry",
+        "unsharp",
+        "blur",
+        "out of focus",
+        "unfocused",
+        "smudged",
+        "hazy",
+        "watermark",
+        "signature",
+        "username",
+        "artist name",
+        "text",
+        "logo",
+        "symbol",
+        "hieroglyph",
+        "script",
+        "printed words",
+        "written language",
+    ],
+    "Negative - Unrealistic Styles": [
+        "cartoon",
+        "3d",
+        "3d render",
+        "cgi",
+        "2d",
+        "sketch",
+        "drawing",
+        "illustration",
+        "bad art",
+        "bad illustration",
+        "painting",
+        "oil painting",
+        "pastel drawing",
+        "art",
+        "unreal engine",
+        "cinema 4d",
+        "artstation",
+        "octane render",
+        "photoshop",
+        "video game",
+        "surreal",
+        "kitsch",
+        "abstract",
+        "creative",
+    ],
+    "Negative - Anatomy & Deformities (General)": [
+        "ugly",
+        "disfigured",
+        "deformed",
+        "mutation",
+        "mutated",
+        "mutilated",
+        "mangled",
+        "bad anatomy",
+        "incorrect physiology",
+        "bad proportions",
+        "gross proportions",
+        "disproportioned",
+        "morbid",
+        "disgusting",
+        "repellent",
+        "revolting dimensions",
+        "corpse",
+        "2 heads",
+        "2 faces",
+        "conjoined",
+        "long neck",
+        "long body",
+        "childish",
+        "old",
+    ],
+    "Negative - Limbs, Hands & Fingers": [
+        "extra limbs",
+        "missing limb",
+        "extra legs",
+        "extra arms",
+        "missing arms",
+        "missing legs",
+        "malformed limbs",
+        "floating limbs",
+        "disconnected limbs",
+        "disembodied limb",
+        "linked limb",
+        "connected limb",
+        "interconnected limb",
+        "split limbs",
+        "split arms",
+        "split hands",
+        "severed",
+        "dismembered",
+        "amputee",
+        "extra knee",
+        "extra elbow",
+        "three crus",
+        "extra crus",
+        "fused crus",
+        "three feet",
+        "fused feet",
+        "worst feet",
+        "poorly drawn feet",
+        "fused thigh",
+        "three thigh",
+        "extra thigh",
+        "worst thigh",
+        "bad hands",
+        "poorly drawn hands",
+        "poorly rendered hands",
+        "mutated hands",
+        "malformed hands",
+        "disfigured hand",
+        "fused hands",
+        "three hands",
+        "missing hand",
+        "no thumb",
+        "broken hand",
+        "broken wrist",
+        "broken leg",
+        "extra fingers",
+        "missing fingers",
+        "fused fingers",
+        "too many fingers",
+        "extra digit",
+        "fewer digits",
+        "ugly fingers",
+        "long fingers",
+        "twisted fingers",
+        "bad digit",
+        "missing digit",
+        "broken finger",
+        "six fingers per hand",
+        "four fingers per hand",
+    ],
+    "Negative - Face & Eyes": [
+        "poorly drawn face",
+        "bad face",
+        "fused face",
+        "cloned face",
+        "worst face",
+        "deformed face",
+        "ugly face",
+        "irregular face",
+        "asymmetrical",
+        "squint",
+        "extra eyes",
+        "huge eyes",
+        "ugly eyes",
+        "deformed pupils",
+        "deformed iris",
+        "cross-eye",
+    ],
+    "Negative - Composition & Color": [
+        "out of frame",
+        "body out of frame",
+        "poorly framed",
+        "cut off",
+        "trimmed",
+        "cropped",
+        "canvas frame",
+        "picture frame",
+        "storyboard",
+        "split image",
+        "tiling",
+        "b&w",
+        "black and white",
+        "monochrome",
+        "weird colors",
+        "oversaturated",
+        "low saturation",
+    ],
+}

ui/ui_data.py

@@ -0,0 +1,525 @@
+# Copyright 2025 The DEVAIEXP Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import os
+import traceback
+from dataclasses import fields
+from enum import Enum
+from importlib import resources
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Dict, List, Optional, get_type_hints
+
+import gradio as gr
+import numpy as np
+
+# Project Imports
+from sup_toolbox.config import (
+    SAMPLERS_OTHERS,
+    SAMPLERS_SUPIR,
+    Config,
+    SchedulerConfig,
+)
+from sup_toolbox.enums import ModelType, PromptMethod
+from sup_toolbox.modules.model_manager import ModelManager
+from sup_toolbox.modules.SUPIR.pipeline_supir_stable_diffusion_xl import (
+    InjectionConfigs,
+    InjectionFlags,
+    InjectionScaleConfig,
+)
+from sup_toolbox.utils.logging import logger
+from ui.ui_config import AppSettings, SchedulerSettings, SUPIRAdvanced_Config, SUPIRInjectionConfig
+
+
+class UIData:
+    """
+    This class acts as a service provider for the Gradio UI.
+    It loads dynamic data like model lists, manages application settings and presets,
+    and contains helper functions for UI data conversion.
+    """
+
+    # Symbols and Constants
+    folder_symbol = "\U0001f4c2"
+    refresh_symbol = "\U0001f504"
+    save_symbol = "\U0001f4be"
+    add_symbol = "\U00002795"
+    remove_symbol = "\U0000274c"
+    clean_symbol = "\U0001f9f9"
+    download_symbol = "\U0001f4e5"
+    engine_symbol = "\U00002699"
+    tools_symbol = "\U0001f6e0"
+    settings_symbol = "⚙️"
+    process_symbol = "\U00002728"
+    stop_symbol = "\U0001f6d1"
+    preview_symbol = "\U0001f441"
+    about_symbol = "ℹ️"
+    caption_symbol = "🤖"
+
+    APPLICATION_TITLE = "SUP Toolbox UI"
+    MAX_SEED = np.iinfo(np.int32).max
+
+    # Static UI Option Lists
+    PROMPT_METHODS = [e.value for e in PromptMethod]
+    SAMPLER_SUPIR_LIST = sorted(SAMPLERS_SUPIR.keys())
+    SAMPLER_OTHERS_LIST = sorted(SAMPLERS_OTHERS.keys())
+
+    # Dynamically Populated Lists
+    MODEL_CHOICES: list[str] = []
+    VAE_CHOICES: list[str] = []
+    RESTORER_ENGINE_CHOICES: list[str] = []
+    UPSCALER_ENGINE_CHOICES: list[str] = []
+    PRESETS_LIST: list[str] = []
+    PRETRAINED_MODELS_LIST: list[str] = []
+    PRETRAINED_VAE_MODELS_LIST: list[str] = []
+
+    APP_ROOT_DIR = Path(__file__).resolve().parent.parent
+
+    def __init__(self, **kwargs):
+        self.USER_PRESETS_DIR = Path("./presets")
+        self.USER_PRESETS_DIR.mkdir(exist_ok=True)
+        self.PRESETS_LIST = []
+        self.config = Config(models_root_path=self.APP_ROOT_DIR)
+        Path(self.config.output_dir).mkdir(exist_ok=True)
+        self.settings = AppSettings()
+        self.model_manager = ModelManager(self.config)
+        self.loaded_preset = {}
+        always_download_models = kwargs.pop("always_download_models", None)
+
+        # Main initialization sequence
+        self.load_settings()
+
+        # Prepare models
+        self.model_manager.prepare_models(always_download_models)
+
+        # Populate dynamic lists based on loaded settings
+        self.get_model_list()
+        self.get_vae_model_list()
+        self.get_preset_list()
+
+        # Populate engine choices from the config mappings
+        from ui.ui_config import RESTORER_CONFIG_MAPPING, UPSCALER_CONFIG_MAPPING
+
+        self.RESTORER_ENGINE_CHOICES = ["None"] + [k for k in RESTORER_CONFIG_MAPPING.keys() if k != "SUPIRAdvanced"]
+        self.UPSCALER_ENGINE_CHOICES = ["None"] + [k for k in UPSCALER_CONFIG_MAPPING.keys() if k != "SUPIRAdvanced"]
+
+        # Theme
+        self.theme = gr.themes.Ocean()
+
+    def load_settings(self):
+        """Loads settings from a JSON file into the AppSettings dataclass and the main Config object."""
+        print("Loading settings...")
+
+        settings_file_path = "configs/settings.json"
+        if os.path.exists(settings_file_path):
+            with open(settings_file_path, "r") as f:
+                data = json.load(f)
+                # Populate the dataclass with only the keys that exist in it
+                valid_keys = {f.name for f in fields(AppSettings)}
+                filtered_data = {k: v for k, v in data.items() if k in valid_keys}
+                self.settings = AppSettings(**filtered_data)
+                config_class = type(self.config)
+                type_hints = get_type_hints(config_class)
+
+                # Populate the backend config
+                for key, value in data.items():
+                    if hasattr(self.config, key):
+                        expected_type = type_hints.get(key)
+                        final_value = value
+                        if expected_type and isinstance(expected_type, type) and issubclass(expected_type, Enum):
+                            try:
+                                if hasattr(expected_type, "from_str") and callable(getattr(expected_type, "from_str")):
+                                    final_value = expected_type.from_str(value)
+                                else:
+                                    final_value = expected_type(value)
+                            except ValueError:
+                                print(f"Warning: '{value}' is not a valid member of {expected_type.__name__} for field '{key}'. Skipping update.")
+                                continue
+                    setattr(self.config, key, final_value)
+
+        # This part is crucial for making the dynamic lists work
+        self.config.checkpoints_dir = self.settings.checkpoints_dir
+        self.config.vae_dir = self.settings.vae_dir
+        pass
+
+    def load_defaults(self):
+        default_settings_path = files("sup_toolbox.configs").joinpath("settings.json")
+        if not os.path.exists(default_settings_path):
+            print(f"Settings configuration file {default_settings_path} does not exist. Loading will be aborted!")
+            return
+
+        with open(default_settings_path, "r") as f:
+            config_dict = json.load(f)
+
+        self.save_settings(config_dict)
+
+    def save_settings(self, values_dict: dict):
+        status = "Settings was updated!"
+        try:
+            if not os.path.exists("configs"):
+                os.makedirs("configs")
+            settings_path = "configs/settings.json"
+            with open(settings_path, "w") as f:
+                json.dump(values_dict, f, indent=2)
+
+        except Exception as e:
+            logger.error(f"Error in save_settings: {str(e)}")
+            print(traceback.format_exc())
+            status = "There was an error saving the settings!"
+            pass
+        return status
+
+    def get_preset_list(self):
+        """
+        Scans for both default library presets and local user presets, then updates the instance's PRESETS_LIST.
+
+        This method performs a comprehensive scan to build a unified list of available presets for the UI.
+        It follows these steps:
+        1.  Scans the user-defined presets directory (`self.USER_PRESETS_DIR`) for any custom `.json` files.
+            This directory is created if it does not exist.
+        2.  Uses the modern `importlib.resources` library to safely locate and scan the `presets`
+            directory bundled within the installed `sup_toolbox` package. This approach works
+            reliably across all installation types (standard, editable, etc.).
+        3.  Prefixes the names of default presets with "Default: " to distinguish them in the UI.
+        4.  Merges the two lists (user and default), sorts them alphabetically, and stores the
+            final list in `self.PRESETS_LIST`.
+
+        Raises:
+            - Logs an error via the `logging` module if scanning the user presets directory fails.
+            - Logs a warning if the `sup_toolbox` package or its presets directory cannot be found.
+            - Logs an error for any other unexpected exceptions during the process.
+        """
+
+        print("Scanning for user and default presets...")
+
+        user_presets = set()
+        default_presets = set()
+
+        # 1. Load User-Defined Presets
+        try:
+            # Ensure the user presets directory exists before scanning.
+            self.USER_PRESETS_DIR.mkdir(parents=True, exist_ok=True)
+            for f in self.USER_PRESETS_DIR.glob("*.json"):
+                user_presets.add(f.stem)
+        except Exception as e:
+            logger.error(f"Could not scan user presets directory at '{self.USER_PRESETS_DIR}': {e}")
+
+        # 2. Load Bundled Default Presets
+        try:
+            # Use `importlib.resources.files` to get a traversable path object
+            # to the 'presets' directory inside the installed 'sup_toolbox' package.
+            # This is the modern, standard way to access package data.
+            preset_path = resources.files("sup_toolbox").joinpath("presets")
+
+            # Iterate through the contents of the bundled presets directory.
+            for item in preset_path.iterdir():
+                if item.is_file() and item.name.endswith(".json"):
+                    # Add with "Default: " prefix for UI clarity.
+                    default_presets.add(f"Default: {item.stem}")
+
+        except ModuleNotFoundError:
+            # This occurs if the `sup_toolbox` package is not installed in the environment.
+            logger.warning("Could not find default presets because the 'sup-toolbox' library is not installed.")
+        except FileNotFoundError:
+            # This might occur if the package is installed but the 'presets' folder is missing.
+            logger.warning("Located 'sup-toolbox' library, but its 'presets' directory could not be found.")
+        except Exception as e:
+            # Catch any other unexpected errors during resource loading.
+            logger.error(f"An unexpected error occurred while loading default presets: {e}")
+
+        # 3. Merge, Sort, and Finalize the List
+        # Convert sets to lists, sort each one, and then combine.
+        # User presets are listed first.
+        sorted_user_presets = sorted(user_presets)
+        sorted_default_presets = sorted(default_presets)
+
+        self.PRESETS_LIST = sorted_user_presets + sorted_default_presets
+        print(f"Finished loading presets. Found {len(user_presets)} user preset(s) and {len(default_presets)} default preset(s).")
+
+    def load_preset(self, preset_name: str) -> dict:
+        """
+        Loads a specific preset from a JSON file, returning its content as a dictionary.
+
+        This method intelligently searches for the preset in two locations:
+        1.  If the `preset_name` starts with "Default: ", it uses `importlib.resources`
+            to securely read the corresponding bundled preset file from within the
+            installed `sup_toolbox` package.
+        2.  Otherwise, it assumes the preset is a user-defined file located in the
+            `self.USER_PRESETS_DIR` directory.
+
+        In case of any errors (e.g., file not found, invalid JSON), it logs the
+        error and returns an empty dictionary to ensure the application can
+        continue gracefully.
+
+        Args:
+            preset_name (str): The name of the preset to load. Default presets
+                should be prefixed with "Default: ".
+
+        Returns:
+            dict: A dictionary containing the loaded preset data, or an empty
+                dictionary if the preset could not be loaded.
+        """
+
+        if not preset_name or not preset_name.strip():
+            logger.warning("`load_preset` called with an empty name.")
+            return {}
+
+        if preset_name.startswith("Default: "):
+            # Handle Bundled Default Presets
+            base_name = preset_name.replace("Default: ", "")
+            logger.info(f"Loading default preset: '{base_name}'")
+            try:
+                # Use `importlib.resources` to safely access the package data file.
+                # `files()` returns a traversable object representing the package.
+                preset_file_path = resources.files("sup_toolbox").joinpath("presets").joinpath(f"{base_name}.json")
+
+                # `read_text()` is a convenient and safe way to read the file content.
+                json_content = preset_file_path.read_text(encoding="utf-8")
+                return json.loads(json_content)
+
+            except ModuleNotFoundError:
+                logger.error("Cannot load default preset because the 'sup-toolbox' library is not installed.")
+                return {}
+            except FileNotFoundError:
+                logger.error(f"Default preset file '{base_name}.json' not found within the 'sup_toolbox' package.")
+                return {}
+            except json.JSONDecodeError as e:
+                logger.error(f"Failed to parse default preset '{base_name}.json'. Invalid JSON: {e}")
+                return {}
+            except Exception as e:
+                logger.error(f"An unexpected error occurred while loading default preset '{base_name}': {e}")
+                return {}
+        else:
+            # Handle User-Defined Presets
+            logger.info(f"Loading user preset: '{preset_name}'")
+            preset_path = self.USER_PRESETS_DIR / f"{preset_name}.json"
+
+            if not preset_path.is_file():
+                logger.warning(f"User preset '{preset_name}' not found at path: {preset_path}")
+                return {}
+
+            try:
+                with open(preset_path, "r", encoding="utf-8") as file:
+                    return json.load(file)
+            except json.JSONDecodeError as e:
+                logger.error(f"Failed to parse user preset '{preset_name}.json'. Invalid JSON: {e}")
+                return {}
+            except Exception as e:
+                logger.error(f"An unexpected error occurred while loading user preset '{preset_name}': {e}")
+                return {}
+
+    def save_preset(self, preset_name: str, values_dict: dict) -> str:
+        """Saves a preset dictionary to the local user presets directory."""
+
+        if not preset_name or not preset_name.strip():
+            raise gr.Error("Preset name cannot be empty.")
+
+        if preset_name.startswith("Default: "):
+            raise gr.Error("Cannot overwrite default presets. Please choose a name without the 'Default:' prefix.")
+
+        status = f"Preset '{preset_name}' was saved!"
+        preset_path = self.USER_PRESETS_DIR / f"{preset_name}.json"
+        try:
+            with open(preset_path, "w", encoding="utf-8") as f:
+                json.dump(values_dict, f, indent=4)
+            self.get_preset_list()
+        except Exception as e:
+            logger.error(f"Error in save_preset: {e}")
+            traceback.print_exc()
+            status = f"Error saving preset {preset_name}"
+        return status
+
+    def get_model_list(self):
+        """Populates MODEL_CHOICES from pretrained list and local checkpoint directory."""
+        print("Loading model list...")
+        try:
+            self.PRETRAINED_MODELS_LIST = self.model_manager.filter_models_by_model_type(ModelType.Diffusers.value)
+            pretrained_names = [m["model_name"] for m in self.PRETRAINED_MODELS_LIST]
+            local_files = []
+            if self.settings.checkpoints_dir and os.path.isdir(self.settings.checkpoints_dir):
+                local_files = sorted([f for f in os.listdir(self.settings.checkpoints_dir) if f.endswith((".safetensors", ".ckpt"))])
+            self.MODEL_CHOICES = ["None"] + pretrained_names + local_files
+        except Exception as e:
+            logger.error(f"Error in get_model_list: {e}")
+            self.MODEL_CHOICES = ["Error: Check checkpoints_dir path in settings."]
+
+    def get_vae_model_list(self):
+        """Populates VAE_CHOICES from pretrained list and local VAE directory."""
+        print("Loading VAE list...")
+        try:
+            self.PRETRAINED_VAE_MODELS_LIST = self.model_manager.filter_models_by_model_type(ModelType.VAE.value)
+            pretrained_names = [m["model_name"] for m in self.PRETRAINED_VAE_MODELS_LIST]
+            local_files = []
+            if self.settings.vae_dir and os.path.isdir(self.settings.vae_dir):
+                local_files = sorted([f for f in os.listdir(self.settings.vae_dir) if f.endswith((".safetensors", ".pt"))])
+            self.VAE_CHOICES = ["Default"] + pretrained_names + local_files
+        except Exception as e:
+            logger.error(f"Error in get_vae_model_list: {e}")
+            self.VAE_CHOICES = ["Error: Check vae_dir path in settings."]
+
+    def inject_assets(self):
+        """
+        This function prepares the payload of CSS and JS code. It's called by the
+        app.load() event listener when the Gradio app starts.
+        """
+        # Inline code
+        css_code = ""
+        js_code = ""
+        popup_html = """
+            <div id="flyout_property_sheet_panel_target" class="flyout-container" style="display: none;">
+            </div>
+            <div id="flyout_restoration_mask_panel_target" class="flyout-container" style="display: none;">
+            </div>
+        """
+        # Read from files
+        try:
+            with open("ui/style.css", "r", encoding="utf-8") as f:
+                css_code += f.read() + "\n"
+            with open("ui/script.js", "r", encoding="utf-8") as f:
+                js_code += f.read() + "\n"
+        except FileNotFoundError as e:
+            print(f"Warning: Could not read asset file: {e}")
+
+        return {"js": js_code, "css": css_code, "body_html": popup_html}
+
+    def map_ui_supir_injection_to_pipeline_params(self, ui_config: SUPIRAdvanced_Config) -> tuple[Optional[InjectionConfigs], Optional[InjectionFlags]]:
+        """
+        Maps the configuration from the PropertySheet UI to the pipeline's
+        InjectionConfigs and InjectionFlags dataclasses by modifying their fields in place.
+
+        Args:
+            ui_config: An instance of SUPIRAdvanced_Config, as returned by the PropertySheet.
+
+        Returns:
+            A tuple containing populated instances of (InjectionConfigs, InjectionFlags),
+            or (None, None) if SFT settings are not applied.
+        """
+
+        # 1. Initialize the target dataclasses. Their nested fields are also initialized.
+        injection_configs = InjectionConfigs()
+        injection_flags = InjectionFlags()
+
+        # 2. Iterate through the fields of the source UI config (SUPIRAdvanced_Config).
+        for ui_field in fields(ui_config):
+            # Skip fields that are not part of the mapping logic
+            if not isinstance(getattr(ui_config, ui_field.name), SUPIRInjectionConfig):
+                continue
+
+            target_field_name = ui_field.name  # e.g., "sft_post_mid"
+            source_injection_config: SUPIRInjectionConfig = getattr(ui_config, target_field_name)
+
+            # 3. Map the activation flag.
+            flag_name = f"{target_field_name}_active"
+            if hasattr(injection_flags, flag_name):
+                setattr(injection_flags, flag_name, source_injection_config.sft_active)
+
+            # 4. Map the scale configuration by modifying the existing nested object.
+            if hasattr(injection_configs, target_field_name):
+                # Get a direct reference to the nested dataclass instance
+                target_scale_config: InjectionScaleConfig = getattr(injection_configs, target_field_name)
+
+                # If custom scale is enabled, update the fields of the existing instance.
+                # Otherwise, it will keep its default values from initialization.
+                if source_injection_config.enable_custom_scale:
+                    target_scale_config.scale_end = float(source_injection_config.scale_end)
+                    target_scale_config.linear = source_injection_config.linear
+                    target_scale_config.scale_start = float(source_injection_config.scale_start)
+                    target_scale_config.reverse = source_injection_config.reverse
+                # No 'else' is needed, as the defaults are already set.
+
+        return injection_configs, injection_flags
+
+    def map_scheduler_settings_to_config(self, ui_settings: SchedulerSettings) -> SchedulerConfig:
+        """
+        Maps the UI-facing SchedulerSettings to the internal SchedulerConfig.
+
+        This function iterates through the fields of the source `ui_settings`
+        and transfers the values to a new `SchedulerConfig` instance if a field
+        with the same name exists in the destination. Fields present in
+        `SchedulerConfig` but not in `SchedulerSettings` will retain their
+        default values.
+
+        Args:
+            ui_settings: An instance of SchedulerSettings, as configured by the user.
+
+        Returns:
+            A populated instance of SchedulerConfig ready for use in the pipeline.
+        """
+        # 1. Initialize the target dataclass. This populates it with default values.
+        pipeline_config = SchedulerConfig()
+
+        # 2. Iterate through all fields defined in the source UI settings dataclass.
+        for source_field in fields(ui_settings):
+            field_name = source_field.name
+
+            # 3. Check if the destination dataclass has a field with the same name.
+            if hasattr(pipeline_config, field_name):
+                # 4. If it exists, get the value from the source and set it on the destination.
+                source_value = getattr(ui_settings, field_name)
+                setattr(pipeline_config, field_name, source_value)
+
+        return pipeline_config
+
+    def add_visibility_rules(self, rules_dict: Dict[str, Any], new_visibility_rules: List[Dict[str, bool]]) -> Dict[str, Any]:
+        """
+        Adds or updates unconditional visibility rules in the "on_load_actions" list.
+
+        This function takes a main UI rules dictionary and a list of new
+        visibility settings. It then iterates through the list and updates or adds
+        "update_visibility" actions to the `on_load_actions` section.
+
+        If an action for a specific field path already exists, its visibility
+        rule will be updated. If it doesn't exist, a new action will be appended.
+
+        Args:
+            rules_dict:
+                The main UI rules dictionary, expected to have keys like
+                `"dynamic_dependencies"` and `"on_load_actions"`.
+            new_visibility_rules:
+                A list of dictionaries, where each dictionary contains a single
+                key-value pair: the field path (e.g., "general.upscaling_mode")
+                and its desired visibility (True or False).
+
+        Returns:
+            The modified rules_dict with the new visibility rules applied.
+        """
+        # Safely get the 'on_load_actions' list.
+        # If it doesn't exist, create it as an empty list to avoid errors.
+        on_load_actions = rules_dict.setdefault("on_load_actions", [])
+
+        # Iterate through the list of new rules provided by the user.
+        for rule_item in new_visibility_rules:
+            # Each 'rule_item' is a dictionary like {"general.upscaling_mode": False}.
+            for field_path, is_visible in rule_item.items():
+                found_existing_rule = False
+                # Check if an action for this field_path already exists.
+                for action in on_load_actions:
+                    if action.get("target_field_path") == field_path and action.get("type") == "update_visibility":
+                        # If it exists, update its "visible" value.
+                        action["visible"] = is_visible
+                        found_existing_rule = True
+                        break  # Stop searching once found
+
+                # If no existing rule was found after checking the whole list...
+                if not found_existing_rule:
+                    # append a new action dictionary in the correct format.
+                    on_load_actions.append(
+                        {
+                            "type": "update_visibility",
+                            "target_field_path": field_path,
+                            "visible": is_visible,
+                        }
+                    )
+
+        return rules_dict

ui/ui_events.py

@@ -0,0 +1,1789 @@
+# Copyright 2025 The DEVAIEXP Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import dataclasses
+import json
+import logging
+import math
+import os
+import queue
+import random
+import sys
+import threading
+from dataclasses import asdict, fields, is_dataclass
+from pathlib import Path
+from typing import Any, Union, cast
+
+import gradio as gr
+from gradio_imagemeta.helpers import extract_metadata, transfer_metadata
+from gradio_livelog.utils import ProgressTracker, Tee, TqdmToQueueWriter, capture_logs
+from gradio_propertysheet import PropertySheet
+from gradio_propertysheet.helpers import flatten_dataclass_with_labels
+from PIL import Image
+
+from sup_toolbox.enums import (
+    ColorFix,
+    ImageSizeFixMode,
+    PromptMethod,
+    RestorerEngine,
+    Sampler,
+    StartPoint,
+    SUPIRModel,
+    UpscalerEngine,
+    UpscalingMode,
+    WeightingMethod,
+)
+from sup_toolbox.utils.system import infer_type
+from ui.globals import pipeline_lock, sup_toolbox_pipe
+from ui.ui_config import (
+    APPSETTINGS_SHEET_DEPENDENCY_RULES,
+    DEFAULT_PROMPTS,
+    RESTORER_CONFIG_MAPPING,
+    RESTORER_SHEET_DEPENDENCY_RULES,
+    SAMPLER_MAPPING,
+    SUPIR_ADVANCED_RULES,
+    UPSCALER_CONFIG_MAPPING,
+    UPSCALER_SHEET_DEPENDENCY_RULES,
+    ControlNetTile_Config,
+    FaithDiff_Config,
+    SUPIR_Config,
+    SUPIRAdvanced_Config,
+)
+from ui.ui_layout import UIComponents
+from ui.ui_state import AppState
+from ui.util.dataclass_helpers import (
+    apply_dynamic_changes,
+    dataclass_from_dict,
+    get_nested_attr,
+)
+
+
+class EventHandlers:
+    def __init__(self, state: AppState, components: UIComponents):
+        self.state = state
+        self.components = components
+
+    def update_pipeline(self, log_callback=None, progress_bar_handler=None):
+        """
+        Initializes or updates the shared SUPToolBoxPipeline instance in a thread-safe manner.
+
+        This method ensures that the module-level pipeline object (`sup_toolbox_pipe`)
+        is created and configured according to the current application state. It uses a
+        thread lock (`pipeline_lock`) to guarantee that the pipeline is initialized
+        only once, even if multiple threads or processes attempt to call this method
+        concurrently.
+
+        If a pipeline instance does not yet exist, it constructs a new `SUPToolBoxPipeline`
+        using the configuration from `self.state.uidata.config` and the provided callbacks.
+        If an instance already exists, it simply updates the instance's configuration and
+        callback attributes with the latest values from the application state.
+
+        Parameters
+        ----------
+        log_callback : callable, optional
+            A callback function used by the pipeline to emit log messages. Defaults to `None`.
+        progress_bar_handler : callable, optional
+            A handler for reporting progress, typically for UI progress bars. Defaults to `None`.
+
+        Accesses
+        --------
+        self.state.uidata.config : Config
+            The main configuration object used to initialize or update the pipeline.
+        self.state.cancel_event : threading.Event
+            The cancellation event object passed to the pipeline.
+
+        Side Effects
+        ------------
+        - Initializes the module-level `sup_toolbox_pipe` variable if it is `None`.
+        - Mutates the attributes (`config`, `log_callback`, etc.) of an existing
+          `sup_toolbox_pipe` instance.
+        - The import of `SUPToolBoxPipeline` is done locally within the function
+          to support the lazy-loading architecture.
+
+        Returns
+        -------
+        None
+        """
+        global sup_toolbox_pipe
+        from sup_toolbox.sup_toolbox_pipeline import (
+            SUPToolBoxPipeline,
+        )
+
+        with pipeline_lock:
+            if sup_toolbox_pipe is None:
+                sup_toolbox_pipe = SUPToolBoxPipeline(
+                    self.state.uidata.config,
+                    log_callback=log_callback,
+                    progress_bar_handler=progress_bar_handler,
+                    cancel_event=self.state.cancel_event,
+                )
+            else:
+                sup_toolbox_pipe.config = self.state.uidata.config
+                sup_toolbox_pipe.log_callback = log_callback
+                sup_toolbox_pipe.progress_bar_handler = progress_bar_handler
+                sup_toolbox_pipe.cancel_event = self.state.cancel_event
+
+    def get_supir_advanced_values(self):
+        """
+        Create and return a SUPIRAdvanced_Config instance with specific advanced flags disabled.
+
+        This function constructs a new SUPIRAdvanced_Config object initialized with its
+        default settings and then explicitly disables the "sft_active" flag for two
+        cross-up blocks used in stage 1:
+
+        - cross_up_block_0_stage1.sft_active is set to False
+        - cross_up_block_1_stage1.sft_active is set to False
+
+        Returns:
+            SUPIRAdvanced_Config: A configuration object reflecting the default advanced
+            settings with the two stage-1 cross-up block SFT flags disabled.
+
+        Notes:
+            - The function does not modify any global state; it returns a freshly
+            created configuration instance.
+            - It assumes SUPIRAdvanced_Config and its nested attributes
+            (cross_up_block_0_stage1, cross_up_block_1_stage1, and their sft_active
+            attributes) are defined and accessible.
+            - No parameters are required.
+
+        Example:
+            cfg = get_supir_advanced_values()
+            assert cfg.cross_up_block_0_stage1.sft_active is False
+            assert cfg.cross_up_block_1_stage1.sft_active is False
+        """
+        initial_supir_advanced_settings = SUPIRAdvanced_Config()
+        initial_supir_advanced_settings.cross_up_block_0_stage1.sft_active = False
+        initial_supir_advanced_settings.cross_up_block_1_stage1.sft_active = False
+        return initial_supir_advanced_settings
+
+    def calculate_effective_steps(
+        self,
+        config: Union[SUPIR_Config, FaithDiff_Config, ControlNetTile_Config],
+        is_upscaler: bool,
+    ) -> int:
+        """
+        Calculates the total effective number of inference steps for a given engine configuration.
+
+        For upscalers in 'Progressive' mode, it simulates the distributed decay of the 'strength'
+        parameter across multiple passes to provide an accurate total step count.
+
+        Args:
+            config: The configuration object for the engine.
+            is_upscaler: A boolean flag indicating if this config is for an upscaler.
+
+        Returns:
+            The total calculated effective number of steps for the configuration.
+        """
+        if not config or not hasattr(config, "general"):
+            return 0
+
+        num_images = getattr(config.general, "num_images", 1)
+        num_steps = getattr(config.general, "num_steps", 0)
+        initial_strength = getattr(config, "strength", 1.0)
+        total_steps_for_one_image = 0
+
+        # 1. Calculate steps for the first (or only) pass.
+        #    The strength used is the initial strength.
+        first_pass_steps = min(int(num_steps * initial_strength), num_steps)
+        total_steps_for_one_image += first_pass_steps
+
+        # 2. If it's an upscaler in progressive mode, simulate subsequent passes with distributed decay.
+        is_progressive_mode = is_upscaler and hasattr(config.general, "upscaling_mode") and config.general.upscaling_mode == UpscalingMode.Progressive.value
+
+        if is_progressive_mode:
+            scale_factor_str = getattr(config.general, "upscale_factor", "1x")
+            # Ensure the string is not empty before trying to slice
+            if scale_factor_str:
+                try:
+                    target_scale_factor = int(scale_factor_str[:-1])
+                except (ValueError, IndexError):
+                    target_scale_factor = 1
+            else:
+                target_scale_factor = 1
+
+            # Only calculate decay if there are multiple passes
+            if target_scale_factor > 1:  # Changed from > 2 to handle 2x upscale correctly
+                num_2x_passes = math.ceil(math.log2(target_scale_factor))
+
+                if num_2x_passes > 1:
+                    strength_decay_rate = getattr(config.general, "strength_decay_rate", 0.5)
+
+                    # Calculate the total amount of strength to be reduced over all passes
+                    total_strength_decay = initial_strength * strength_decay_rate
+
+                    # Distribute this total decay amount over the subsequent passes
+                    num_decay_steps = num_2x_passes - 1
+                    strength_decay_per_step = total_strength_decay / num_decay_steps if num_decay_steps > 0 else 0
+
+                    current_strength = initial_strength
+
+                    # Simulate the remaining passes (first pass is already counted)
+                    for _ in range(num_decay_steps):
+                        # Apply the linear decay step
+                        current_strength -= strength_decay_per_step
+
+                        # Apply the safety floor, same as in the pipeline
+                        final_strength_for_pass = round(max(current_strength, 0.1), 2)
+
+                        # Calculate steps for this pass and add to total
+                        pass_steps = min(int(num_steps * final_strength_for_pass), num_steps)
+                        total_steps_for_one_image += pass_steps
+
+        # 3. Multiply by the number of images to get the overall total
+        total_effective_steps = num_images * total_steps_for_one_image
+
+        return total_effective_steps
+
+    def prepare_engine_configs(
+        self,
+        restorer_engine: str,
+        restorer_config: dict,
+        upscaler_engine: str,
+        upscaler_config: dict,
+    ):
+        """
+        Prepares and casts the engine configuration objects based on the selected engine names.
+        This function is responsible only for creating the correct dataclass instances.
+
+        Args:
+            restorer_engine: The name of the selected restorer engine.
+            restorer_config: The raw configuration data for the restorer from the UI.
+            upscaler_engine: The name of the selected upscaler engine.
+            upscaler_config: The raw configuration data for the upscaler from the UI.
+
+        Returns:
+            A tuple containing the prepared restorer config and upscaler config objects,
+            which may be None if the corresponding engine is not selected.
+        """
+        res_config, ups_config = None, None
+        if restorer_engine in [
+            RestorerEngine.SUPIR.value,
+            RestorerEngine.FaithDiff.value,
+        ]:
+            res_config = cast(Union[SUPIR_Config, FaithDiff_Config], restorer_config)
+
+        if upscaler_engine in [
+            UpscalerEngine.SUPIR.value,
+            UpscalerEngine.FaithDiff.value,
+            UpscalerEngine.ControlNetTile.value,
+        ]:
+            if upscaler_engine == UpscalerEngine.ControlNetTile.value:
+                ups_config = cast(ControlNetTile_Config, upscaler_config)
+            else:
+                ups_config = cast(Union[SUPIR_Config, FaithDiff_Config], upscaler_config)
+
+        return res_config, ups_config
+
+    def calculate_total_steps(self, res_config, ups_config, res_engine_name, ups_engine_name):
+        """
+        Calculates the total effective inference steps based on the prepared engine configurations.
+
+        Args:
+            res_config: The prepared configuration object for the restorer.
+            ups_config: The prepared configuration object for the upscaler.
+            res_engine_name: The selected restorer engine name.
+            ups_engine_name: The selected upscaler engine name.
+
+        Returns:
+            The total number of effective inference steps.
+        """
+
+        total_inference_steps = 0
+        if res_config and res_engine_name != "None":
+            total_inference_steps += self.calculate_effective_steps(res_config, is_upscaler=False)
+
+        if ups_config and ups_engine_name != "None":
+            total_inference_steps += self.calculate_effective_steps(ups_config, is_upscaler=True)
+
+        return total_inference_steps
+
+    def generate_image_metadata(
+        self,
+        res_config_class,
+        ups_config_class,
+        res_supir_advanced_config_class,
+        ups_supir_advanced_config_class,
+        input_params,
+        res_sampler_config_class,
+        ups_sampler_config_class,
+    ):
+        """
+        Generates metadata by aggregating configuration values from various sources.
+        This function takes multiple configuration classes and input parameters, flattens them,
+        and combines them into a single dictionary with prefixed keys for metadata tracking.
+        Args:
+            res_config_class (dict): Configuration for the image restoration.
+            ups_config_class (dict): Configuration for the image upscaling.
+            res_supir_advanced_config_class (dict): Advanced SUPIR configuration for restoration.
+            ups_supir_advanced_config_class (dict): Advanced SUPIR configuration for upscaling.
+            input_params (dict): User input parameters including engine selections.
+            res_sampler_config_class (dict): Sampler configuration for restoration.
+            ups_sampler_config_class (dict): Sampler configuration for upscaling.
+        Returns:
+            Dict[str, Any]: A flattened dictionary containing all configuration values with
+                prefixed keys that identify their source and purpose. For example:
+                {
+                    "Restorer - Engine1 - param1": value1,
+                    "Upscaler - Engine2 - param2": value2,
+                    ...
+                }
+        Notes:
+            - Keys are prefixed based on their source (Restorer/Upscaler) and engine type
+            - Processing only occurs if the respective engine is selected and not "none"
+            - Input parameters are preserved in the output dictionary
+        """
+        res_engine, ups_engine = (
+            input_params["Image Restore Engine"],
+            input_params["Image Upscale Engine"],
+        )
+
+        all_values = input_params.copy()
+
+        def process_and_prefix(instance: Any, prefix: str):
+            """Helper to flatten a dataclass and add a final prefix to its keys."""
+            if instance:
+                for key, value in flatten_dataclass_with_labels(instance).items():
+                    all_values[f"{prefix} - {key}"] = value
+
+        if res_engine and res_engine.lower() != "none":
+            process_and_prefix(res_config_class, f"Restorer - {res_engine}")
+            process_and_prefix(res_supir_advanced_config_class, "Restorer")
+            process_and_prefix(res_sampler_config_class, "Restorer - Sampler")
+
+        if ups_engine and ups_engine.lower() != "none":
+            process_and_prefix(ups_config_class, f"Upscaler - {ups_engine}")
+            process_and_prefix(ups_supir_advanced_config_class, "Upscaler")
+            process_and_prefix(ups_sampler_config_class, "Upscaler - Sampler")
+
+        return all_values
+
+    def update_preset_list(self, preset):
+        """
+        Updates the preset list in the UI dropdown with the latest presets and sets a specific value.
+
+        Args:
+        preset (str): The preset value to be selected in the dropdown after updating the list
+
+        Returns:
+        gr.update: A Gradio update object containing the new preset choices and selected value
+        """
+        self.state.uidata.get_preset_list()
+        return gr.update(choices=self.state.uidata.PRESETS_LIST, value=preset)
+
+    def save_preset(self, preset_name: str, *all_component_values):
+        """
+        Parameters:
+                preset_name (str): The name of the preset to be saved. Must not be empty or a default preset name.
+                *all_component_values: A variable number of values representing the current state of UI components.
+            Raises:
+                gr.Error: If the preset name is empty or if an attempt is made to overwrite a default preset.
+            Notes:
+                - Maps the received values back to the components using the order of the input list passed to the .click() event.
+                - It is safer to map by elem_id.
+                - Removes 'restorer_supir_advanced_settings' if the 'restorer_engine' is not set to SUPIR.
+                - Removes 'upscaler_supir_advanced_settings' if the 'upscaler_engine' is not set to SUPIR.
+                - For PropertySheets, if the value is a dataclass, it is converted to a dictionary before saving.
+        """
+        if not preset_name or not preset_name.strip():
+            raise gr.Error("Please enter a preset name.")
+
+        if preset_name in self.state.uidata.PRESETS_LIST and "Default:" in preset_name:
+            raise gr.Error("A default preset cannot be overwritten; please set a different name.")
+
+        preset_data = {}
+        ALL_UI_COMPONENTS = self.components.ALL_UI_COMPONENTS
+        component_values = dict(zip(ALL_UI_COMPONENTS.keys(), all_component_values))
+        component_values["restorer_sampler_settings"] = SAMPLER_MAPPING["restorer_sampler"]
+        component_values["upscaler_sampler_settings"] = SAMPLER_MAPPING["upscaler_sampler"]
+
+        if component_values.get("restorer_engine") != RestorerEngine.SUPIR.value:
+            component_values.pop("restorer_supir_advanced_settings", None)
+
+        if component_values.get("upscaler_engine") != RestorerEngine.SUPIR.value:
+            component_values.pop("upscaler_supir_advanced_settings", None)
+
+        for elem_id, value in component_values.items():
+            if dataclasses.is_dataclass(value):
+                preset_data[elem_id] = asdict(value)
+            else:
+                preset_data[elem_id] = value
+
+        self.state.uidata.save_preset(preset_name.strip(), preset_data)
+        gr.Info(f"Preset '{preset_name}' saved successfully!")
+
+    def load_preset(self, preset_name: str):
+        """
+        Load Presets to UI components. It also updates the backend state, such as
+        SAMPLER_MAPPING, based on the loaded preset.
+        Parameters:
+            preset_name (str): The name of the preset to load. Must be a non-empty string.
+        Returns:
+            List[gr.Update]: A list of updates for the UI components, where each update
+            corresponds to the state of a component after loading the preset.
+        Raises:
+            gr.Error: If no preset is selected, if the preset is empty or cannot be found,
+            or if there is an error during the loading process.
+        The function handles different types of UI components, including PropertySheets,
+        and updates their values based on the data retrieved from the preset. It also
+        ensures that the backend state is synchronized with the loaded preset data.
+        """
+
+        ALL_UI_COMPONENTS = self.components.ALL_UI_COMPONENTS
+        # Prepare a default output list. `gr.skip()` means "do not change this component".
+        output_updates = [gr.skip()] * len(ALL_UI_COMPONENTS)
+        if not preset_name or not preset_name.strip():
+            raise gr.Error("No preset selected to load.")
+
+        try:
+            # Load the preset data from the JSON file
+            preset_data = self.state.uidata.load_preset(preset_name.strip())
+            if not preset_data:
+                raise gr.Error(f"Preset '{preset_name}' is empty or could not be found.")
+
+            # Create a mapping of components to their indices in the output list for easy access
+            component_to_index = {id(comp): i for i, comp in enumerate(ALL_UI_COMPONENTS.values())}
+
+            for elem_id, component in ALL_UI_COMPONENTS.items():
+                # Check if there is a value for this component in the preset
+                if elem_id in preset_data:
+                    value_from_preset = preset_data[elem_id]
+                    output_index = component_to_index.get(id(component))
+                    if output_index is None:
+                        continue
+
+                    # If the component is a PropertySheet, reconstruct the dataclass instance
+                    if isinstance(component, PropertySheet):
+                        dc_type = type(getattr(component, "_dataclass_value", None))
+
+                        # If the component is a PropertySheet, reconstruct the dataclass instance
+                        if dc_type and is_dataclass(dc_type) and isinstance(value_from_preset, dict):
+                            if component.elem_id == "restorer_settings" and output_updates[0]["value"] == RestorerEngine.SUPIR.value:
+                                dc_type = type(RESTORER_CONFIG_MAPPING[RestorerEngine.SUPIR.value])
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+                                instance = apply_dynamic_changes(instance, RESTORER_SHEET_DEPENDENCY_RULES)
+                                RESTORER_CONFIG_MAPPING[RestorerEngine.SUPIR.value] = instance
+                            elif component.elem_id == "restorer_supir_advanced_settings" and output_updates[0]["value"] == RestorerEngine.SUPIR.value:
+                                dc_type = type(RESTORER_CONFIG_MAPPING["SUPIRAdvanced"])
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+                                instance = apply_dynamic_changes(instance, SUPIR_ADVANCED_RULES)
+                                RESTORER_CONFIG_MAPPING["SUPIRAdvanced"] = instance
+                            elif component.elem_id == "restorer_settings" and output_updates[0]["value"] == RestorerEngine.FaithDiff.value:
+                                dc_type = type(RESTORER_CONFIG_MAPPING[RestorerEngine.FaithDiff.value])
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+                                instance = apply_dynamic_changes(instance, RESTORER_SHEET_DEPENDENCY_RULES)
+                                RESTORER_CONFIG_MAPPING[RestorerEngine.FaithDiff.value] = instance
+
+                            if component.elem_id == "upscaler_settings" and output_updates[1]["value"] == UpscalerEngine.SUPIR.value:
+                                dc_type = type(UPSCALER_CONFIG_MAPPING[UpscalerEngine.SUPIR.value])
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+                                UPSCALER_CONFIG_MAPPING[UpscalerEngine.SUPIR.value] = instance
+                            elif component.elem_id == "upscaler_supir_advanced_settings" and output_updates[1]["value"] == UpscalerEngine.SUPIR.value:
+                                dc_type = type(UPSCALER_CONFIG_MAPPING["SUPIRAdvanced"])
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+                                instance = apply_dynamic_changes(instance, SUPIR_ADVANCED_RULES)
+                                UPSCALER_CONFIG_MAPPING["SUPIRAdvanced"] = instance
+                            elif component.elem_id == "upscaler_settings" and output_updates[1]["value"] == UpscalerEngine.FaithDiff.value:
+                                dc_type = type(UPSCALER_CONFIG_MAPPING[UpscalerEngine.FaithDiff.value])
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+                                UPSCALER_CONFIG_MAPPING[UpscalerEngine.FaithDiff.value] = instance
+                            elif component.elem_id == "upscaler_settings" and output_updates[1]["value"] == UpscalerEngine.ControlNetTile.value:
+                                dc_type = type(UPSCALER_CONFIG_MAPPING[UpscalerEngine.ControlNetTile.value])
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+                                UPSCALER_CONFIG_MAPPING[UpscalerEngine.ControlNetTile.value] = instance
+
+                            if instance is None:
+                                instance = dataclass_from_dict(dc_type, value_from_preset)
+
+                            output_updates[output_index] = gr.update(value=instance)
+                    # For all other standard Gradio components
+                    else:
+                        output_updates[output_index] = gr.update(value=value_from_preset)
+
+            # Update the backend state (SAMPLER_MAPPING)
+            # Iterate over the special keys you saved for the samplers
+            for sampler_key in [
+                "restorer_sampler_settings",
+                "upscaler_sampler_settings",
+            ]:
+                if sampler_key in preset_data:
+                    sampler_data = preset_data[sampler_key]
+                    # The key in SAMPLER_MAPPING is the elem_id (e.g., "restorer_sampler_settings")
+                    target_instance = SAMPLER_MAPPING.get(sampler_key.rpartition("_")[0])
+
+                    if target_instance and is_dataclass(target_instance) and isinstance(sampler_data, dict):
+                        # Populate the existing instance in SAMPLER_MAPPING with the preset data
+                        # This is similar to how on_flyout_change works
+                        for field_name, value in sampler_data.items():
+                            if hasattr(target_instance, field_name):
+                                setattr(target_instance, field_name, value)
+
+            gr.Info(f"Preset '{preset_name}' loaded successfully.")
+            return output_updates
+        except Exception as e:
+            raise gr.Error(f"Failed to load or apply preset '{preset_name}': {e}")
+
+    def restart(self):
+        """Triggers a restart of the Python script."""
+        print("Please wait. The UI is being restarted...")
+        os.execv(sys.executable, [os.path.basename(sys.executable)] + sys.argv)
+
+    # region Flyout Event Function Logic
+    def on_handle_flyout_toggle(self, is_vis, current_anchor, *, clicked_elem_id, target_elem_id):
+        """
+        Manages the visibility and content of a flyout panel based on user interaction.
+
+        This function determines whether to show, hide, or update a flyout panel.
+        - If the clicked element is already the active anchor, it hides the flyout.
+        - Otherwise, it shows the flyout, positioning it relative to the clicked element,
+          and populates it with the correct settings from `SAMPLER_MAPPING`.
+
+        Args:
+            is_vis (bool): The current visibility state of the flyout.
+            current_anchor (str): The elem_id of the current element the flyout is anchored to.
+            clicked_elem_id (str): The elem_id of the element that was just clicked.
+            target_elem_id (str): The elem_id of the flyout panel to control.
+
+        Returns:
+            Tuple[bool, Optional[str], gr.update, gr.update]: A tuple of updates for:
+                - flyout_visible (gr.State)
+                - active_anchor_id (gr.State)
+                - flyout_sheet (PropertySheet content)
+                - js_data_bridge (JSON data for the frontend)
+        """
+        settings_obj = SAMPLER_MAPPING.get(clicked_elem_id)
+
+        if settings_obj is None:  # not a propertysheet
+            # Command JS to show and position
+            js_data = json.dumps(
+                {
+                    "isVisible": True,
+                    "anchorId": clicked_elem_id,
+                    "targetId": target_elem_id,
+                }
+            )
+            return True, clicked_elem_id, gr.skip(), gr.update(value=js_data)
+
+        if is_vis and current_anchor == clicked_elem_id:
+            # Command JS to hide
+            js_data = json.dumps({"isVisible": False, "anchorId": None, "targetId": target_elem_id})
+            return False, None, gr.update(), gr.update(value=js_data)
+        else:
+            # Command JS to show and position
+            js_data = json.dumps(
+                {
+                    "isVisible": True,
+                    "anchorId": clicked_elem_id,
+                    "targetId": target_elem_id,
+                }
+            )
+            return (
+                True,
+                clicked_elem_id,
+                gr.update(value=settings_obj),
+                gr.update(value=js_data),
+            )
+
+    def on_update_ear_visibility(self, elem_id: str):
+        """
+        Controls the visibility of an 'ear' button next to a sampler dropdown.
+
+        The button is made visible only if the selected sampler has advanced settings
+        defined in the global `SAMPLER_MAPPING`.
+
+        Args:
+            elem_id (str): The elem_id of the sampler dropdown component.
+
+        Returns:
+            gr.update: A Gradio update object to set the visibility of the ear button.
+        """
+        has_settings = elem_id in SAMPLER_MAPPING
+        return gr.update(visible=has_settings)
+
+    def on_flyout_change(self, updated_settings, active_id):
+        """
+        Callback for when the flyout PropertySheet's value changes.
+
+        It updates the corresponding sampler settings object in the global
+        `SAMPLER_MAPPING` dictionary with the new values from the flyout.
+
+        Args:
+            updated_settings (dataclass): The new settings object from the PropertySheet.
+            active_id (str): The elem_id of the component that triggered the flyout,
+                             used as a key in `SAMPLER_MAPPING`.
+        """
+        if updated_settings is None or active_id is None:
+            return
+
+        if active_id in SAMPLER_MAPPING:
+            original_settings_obj = SAMPLER_MAPPING[active_id]
+            for f in dataclasses.fields(original_settings_obj):
+                if hasattr(updated_settings, f.name):
+                    setattr(original_settings_obj, f.name, getattr(updated_settings, f.name))
+
+    def on_close_the_flyout(self, target_elem_id):
+        """
+        Closes the flyout panel.
+
+        This function prepares the necessary state and JS data to command the frontend
+        to hide the flyout panel.
+
+        Args:
+            target_elem_id (str): The elem_id of the flyout panel to close.
+
+        Returns:
+            Tuple[bool, None, gr.update]: Updates for flyout visibility state,
+                                          active anchor ID, and the JS data bridge.
+        """
+        js_data = json.dumps({"isVisible": False, "anchorId": None, "targetId": target_elem_id})
+        return False, None, gr.update(value=js_data)
+
+    def initial_flyout_setup(self):
+        """
+        Sets the initial visibility for all ear buttons on application load.
+
+        Returns:
+            Dict[gr.Button, gr.update]: A dictionary mapping each ear button
+                                        component to its visibility update.
+        """
+        return {
+            "restorer_sampler_ear_btn": self.on_update_ear_visibility("restorer_sampler"),
+            "upscaler_sampler_ear_btn": self.on_update_ear_visibility("upscaler_sampler"),
+        }
+
+    # endregion
+
+    # region Tokenizer Event Function Logic
+    def update_positive_tokenizer(self, p1, p2):
+        """
+        Combines two positive prompt textboxes into a single string for the tokenizer.
+
+        Args:
+            p1 (str): Content of the first prompt textbox.
+            p2 (str): Content of the second prompt textbox.
+
+        Returns:
+            gr.update: An update for the TokenizerTextBox with the combined prompt.
+        """
+        return gr.update(value=f"{p1}\n{p2}".strip())
+
+    def update_positive_prompt_helper(self, evt: gr.EventData):
+        """
+        Updates the target textbox for the positive TagGroupHelper.
+
+        This is triggered on focus for a prompt textbox, ensuring that when a tag
+        is clicked in the helper, it's inserted into the currently active prompt box.
+
+        Args:
+            evt (gr.EventData): Event data from Gradio, containing the target component.
+
+        Returns:
+            gr.update: An update for the TagGroupHelper to set its target textbox ID.
+        """
+        return gr.update(target_textbox_id=evt.target.elem_id)
+
+    def update_prompt_helper_from_tab(self, evt: gr.EventData):
+        """
+        Updates the target textboxes for both TagGroupHelpers when a tab is selected.
+
+        This ensures the helpers target the correct prompt and negative prompt
+        textboxes based on whether the 'Restoration' or 'Upscaling' tab is active.
+
+        Args:
+            evt (gr.EventData): Event data from Gradio, containing the selected tab.
+
+        Returns:
+            Dict[TagGroupHelper, gr.update]: A dictionary of updates for both the
+                                             positive and negative tag helpers.
+        """
+        if evt.target.elem_id == "res-tab":
+            return (
+                gr.update(target_textbox_id="restorer_prompt_1"),
+                gr.update(target_textbox_id="restorer_negative_prompt"),
+            )
+        else:
+            return (
+                gr.update(target_textbox_id="upscaler_prompt_1"),
+                gr.update(target_textbox_id="upscaler_negative_prompt"),
+            )
+
+    # endregion
+
+    # region Others UI Event Function Logic
+    def on_reset_settings(self):
+        """
+        Handles the 'reset settings' button click. Loads default
+        settings via `uidata` and displays an info message to the user before
+        the UI is restarted.
+        """
+        self.state.uidata.load_defaults()
+        gr.Info("Defaults loaded! UI will be restarted!")
+
+    def on_save_settings(self, settings_dict):
+        """
+        Handles the 'save settings' button click. Converts the settings
+        dataclass to a dictionary and saves it using `uidata`. Displays a
+        confirmation message before the UI is restarted.
+
+        Args:
+            settings_dict (AppSettings): The settings dataclass instance from the PropertySheet.
+        """
+        values_dict = asdict(settings_dict)
+        self.state.uidata.save_settings(values_dict)
+        gr.Info("Settings saved! UI will be restarted!")
+
+    def on_settings_sheet_change(self, updated_settings: Any):
+        """
+        Handles changes in the AppSettings PropertySheet.
+
+        It applies dynamic visibility rules to the settings sheet based on the
+        current values (e.g., hiding `quantization_mode` if `quantization_method`
+        is 'None').
+
+        Args:
+            updated_settings (Any): The updated AppSettings dataclass instance
+                                    from the PropertySheet.
+
+        Returns:
+            AppSettings: The modified AppSettings instance with dynamic rules applied.
+        """
+        if updated_settings is None:
+            return updated_settings
+
+        rules_to_apply = []
+
+        if updated_settings.quantization_method == "None":
+            rules_to_apply.append({"quantization_mode": False})
+        else:
+            rules_to_apply.append({"quantization_mode": True})
+
+        self.state.uidata.add_visibility_rules(APPSETTINGS_SHEET_DEPENDENCY_RULES, rules_to_apply)
+        return apply_dynamic_changes(updated_settings, APPSETTINGS_SHEET_DEPENDENCY_RULES)
+
+    def on_set_default_prompts(
+        self,
+        res_engine_name,
+        ups_engine_name,
+        res_prompt_value,
+        res_prompt_2_value,
+        res_negative_prompt_value,
+        ups_prompt_value,
+        ups_prompt_2_value,
+        ups_negative_prompt_value,
+    ):
+        """
+        Sets default prompts in the UI when an engine is selected or changed.
+
+        This function checks if the current prompt fields are empty or if the engine
+        has changed. If so, it populates the respective prompt fields with
+        pre-defined default values for the newly selected engine.
+
+        Args:
+            res_engine_name (str): The selected restorer engine name.
+            ups_engine_name (str): The selected upscaler engine name.
+            res_prompt_value (str): Current value of the restorer's prompt 1.
+            res_prompt_2_value (str): Current value of the restorer's prompt 2.
+            res_negative_prompt_value (str): Current value of the restorer's negative prompt.
+            ups_prompt_value (str): Current value of the upscaler's prompt 1.
+            ups_prompt_2_value (str): Current value of the upscaler's prompt 2.
+            ups_negative_prompt_value (str): Current value of the upscaler's negative prompt.
+
+        Returns:
+            Tuple[str, str, str, str, str, str]: A tuple containing the new values
+                                                 for all six prompt textboxes.
+        """
+
+        restorer_engine_selected = self.state.restorer_engine_selected
+        upscaler_engine_selected = self.state.upscaler_engine_selected
+
+        # Set defaults for restorer prompts only if input is empty/None
+        if res_engine_name == "None":
+            res_prompt = ""
+        elif not res_prompt_value or (restorer_engine_selected != res_engine_name):
+            res_prompt = DEFAULT_PROMPTS["Restorer"][res_engine_name]["prompt"]
+        else:
+            res_prompt = res_prompt_value
+
+        if res_engine_name == "None":
+            res_prompt_2 = ""
+        elif not res_prompt_2_value or (restorer_engine_selected != res_engine_name):
+            res_prompt_2 = DEFAULT_PROMPTS["Restorer"][res_engine_name]["prompt_2"]
+        else:
+            res_prompt_2 = res_prompt_2_value
+
+        if res_engine_name == "None":
+            res_negative = ""
+        elif not res_negative_prompt_value or (restorer_engine_selected != res_engine_name):
+            res_negative = DEFAULT_PROMPTS["Restorer"][res_engine_name]["negative_prompt"]
+        else:
+            res_negative = res_negative_prompt_value
+
+        # Set defaults for upscaler prompts only if input is empty/None
+        if ups_engine_name == "None":
+            ups_prompt = ""
+        elif not ups_prompt_value or (upscaler_engine_selected != ups_engine_name):
+            ups_prompt = DEFAULT_PROMPTS["Upscaler"][ups_engine_name]["prompt"]
+        else:
+            ups_prompt = ups_prompt_value
+
+        if ups_engine_name == "None":
+            ups_prompt_2 = ""
+        elif not ups_prompt_2_value or (upscaler_engine_selected != ups_engine_name):
+            ups_prompt_2 = DEFAULT_PROMPTS["Upscaler"][ups_engine_name]["prompt_2"]
+        else:
+            ups_prompt_2 = ups_prompt_2_value
+
+        if ups_engine_name == "None":
+            ups_negative = ""
+        elif not ups_negative_prompt_value or (upscaler_engine_selected != ups_engine_name):
+            ups_negative = DEFAULT_PROMPTS["Upscaler"][ups_engine_name]["negative_prompt"]
+        else:
+            ups_negative = ups_negative_prompt_value
+
+        self.state.restorer_engine_selected = res_engine_name
+        self.state.upscaler_engine_selected = ups_engine_name
+
+        return (
+            res_prompt,
+            res_prompt_2,
+            res_negative,
+            ups_prompt,
+            ups_prompt_2,
+            ups_negative,
+        )
+
+    def _update_sheet_changes(self, updated_config, mode="Restorer"):
+        """
+        Internal helper to apply dynamic changes to a PropertySheet's dataclass.
+
+        This function applies visibility rules and handles seed randomization logic
+        common to both the restorer and upscaler PropertySheets.
+
+        Args:
+            updated_config (dataclass): The configuration dataclass instance to update.
+            mode (str): Either "Restorer" or "Upscaler" to apply the correct rules.
+
+        Returns:
+            dataclass: The modified configuration dataclass.
+        """
+
+        if mode == "Restorer":
+            updated_config = apply_dynamic_changes(updated_config, RESTORER_SHEET_DEPENDENCY_RULES)
+            previous_randomize_state = get_nested_attr(self.state.restorer_config_class, "general.randomize_seed")
+        else:
+            rules_to_apply = []
+            if updated_config.general.upscaling_mode == "Direct":
+                rules_to_apply.extend(
+                    [
+                        {"general.cfg_decay_rate": False},
+                        {"general.strength_decay_rate": False},
+                    ]
+                )
+            else:
+                rules_to_apply.extend(
+                    [
+                        {"general.cfg_decay_rate": True},
+                        {"general.strength_decay_rate": True},
+                    ]
+                )
+            self.state.uidata.add_visibility_rules(UPSCALER_SHEET_DEPENDENCY_RULES, rules_to_apply)
+            updated_config = apply_dynamic_changes(updated_config, UPSCALER_SHEET_DEPENDENCY_RULES)
+            previous_randomize_state = get_nested_attr(self.state.upscaler_config_class, "general.randomize_seed")
+
+        should_generate_new_seed = (updated_config.general.randomize_seed and not previous_randomize_state) or (
+            updated_config.general.randomize_seed and updated_config.general.seed == -1
+        )
+        if should_generate_new_seed:
+            updated_config.general.seed = random.randint(0, self.state.uidata.MAX_SEED)
+
+        return updated_config
+
+    def on_restore_engine_change(self, restorer_engine_name: str, upscaler_engine_name: str):
+        """
+        Handles UI changes when the restorer engine dropdown is modified.
+
+        This updates the visibility of the restoration tab, loads the correct
+        configuration object into the `restorer_sheet` PropertySheet, and shows/hides
+        the advanced SUPIR settings sheet accordingly.
+
+        Args:
+            restorer_engine_name (str): The newly selected restorer engine.
+            upscaler_engine_name (str): The current upscaler engine.
+
+        Returns:
+            Tuple[gr.update, gr.update, gr.update, gr.update, gr.update]: A tuple of
+                updates for the restoration tab, advanced settings, main settings sheet,
+                engine configuration accordion, and the config tabs selector.
+        """
+        is_restorer_active = restorer_engine_name != "None" and restorer_engine_name in RESTORER_CONFIG_MAPPING
+        is_upscaler_active = upscaler_engine_name != "None" and upscaler_engine_name in UPSCALER_CONFIG_MAPPING
+        is_supir = restorer_engine_name == "SUPIR"
+
+        if is_restorer_active:
+            config_class = RESTORER_CONFIG_MAPPING.get(restorer_engine_name, SUPIR_Config)
+            if is_supir:
+                self.state.restorer_supir_advanced_config_class = self.get_supir_advanced_values()
+            self.state.restorer_config_class = self._update_sheet_changes(config_class, "Restorer")
+        else:
+            self.state.restorer_config_class = None
+            if is_supir:
+                self.state.restorer_supir_advanced_config_class = None
+
+        ec_visible = is_restorer_active or is_upscaler_active
+        selected_tab = 1 if is_upscaler_active and not is_restorer_active else 0
+        return (
+            gr.update(visible=is_restorer_active),
+            gr.update(value=self.state.restorer_supir_advanced_config_class, visible=is_supir),
+            gr.update(
+                value=self.state.restorer_config_class,
+                label=f"{restorer_engine_name} Settings",
+            ),
+            gr.update(visible=ec_visible),
+            gr.update(selected=selected_tab),
+        )
+
+    def on_upscaler_engine_change(self, restorer_engine_name: str, upscaler_engine_name: str):
+        """
+        Handles UI changes when the upscaler engine dropdown is modified.
+
+        This updates the visibility of the upscaling tab, loads the correct
+        configuration object into the `upscaler_sheet` PropertySheet, and manages
+        the visibility of related UI elements like advanced SUPIR settings.
+
+        Args:
+            restorer_engine_name (str): The current restorer engine.
+            upscaler_engine_name (str): The newly selected upscaler engine.
+
+        Returns:
+            Tuple[gr.update, ...]: A tuple of updates for the upscaling tab,
+                advanced settings, main settings sheet, engine accordion, config tabs,
+                and the prompt method dropdown.
+        """
+
+        is_restorer_active = restorer_engine_name != "None" and restorer_engine_name in RESTORER_CONFIG_MAPPING
+        is_upscaler_active = upscaler_engine_name != "None" and upscaler_engine_name in UPSCALER_CONFIG_MAPPING
+        is_supir = upscaler_engine_name == "SUPIR"
+        is_controlnettile = upscaler_engine_name == "ControlNetTile"
+
+        if is_upscaler_active:
+            config_class = UPSCALER_CONFIG_MAPPING.get(upscaler_engine_name, ControlNetTile_Config)
+            if is_supir:
+                self.state.upscaler_supir_advanced_config_class = self.get_supir_advanced_values()
+            self.state.upscaler_config_class = self._update_sheet_changes(config_class, "Upscaler")
+        else:
+            self.state.upscaler_config_class = None
+            if is_supir:
+                self.state.upscaler_supir_advanced_config_class = None
+
+        ec_visible = is_restorer_active or is_upscaler_active
+        selected_tab = 1 if is_upscaler_active and not is_restorer_active else 0
+        return (
+            gr.update(visible=is_upscaler_active),
+            gr.update(value=self.state.upscaler_supir_advanced_config_class, visible=is_supir),
+            gr.update(
+                value=self.state.upscaler_config_class,
+                label=f"{upscaler_engine_name} Settings",
+            ),
+            gr.update(visible=ec_visible),
+            gr.update(selected=selected_tab),
+            gr.update(visible=not is_controlnettile),
+        )
+
+    def on_restorer_sheet_change(self, updated_config: Union[SUPIR_Config, FaithDiff_Config, None]):
+        """
+        Handles changes from the restorer configuration PropertySheet.
+
+        It calls the internal `_update_sheet_changes` helper to apply dynamic rules
+        and manage seed randomization, then updates the global state.
+
+        Args:
+            updated_config (dataclass | None): The new configuration from the sheet.
+
+        Returns:
+            dataclass: The updated and processed configuration dataclass.
+        """
+        if updated_config is None:
+            return self.state.restorer_config_class
+
+        self.state.restorer_config_class = self._update_sheet_changes(updated_config, "Restorer")
+
+        return self.state.restorer_config_class
+
+    def on_restorer_supir_advanced_sheet_change(self, updated_config: SUPIRAdvanced_Config | None):
+        """
+        Handles changes from the restorer supir advanced configuration PropertySheet.
+
+        It calls the internal `apply_dynamic_changes` helper to apply dynamic rules
+        and manage seed randomization, then updates the global state.
+
+        Args:
+            updated_config (dataclass | None): The new configuration from the sheet.
+
+        Returns:
+            dataclass: The updated and processed configuration dataclass.
+        """
+        if updated_config is None:
+            return self.state.restorer_supir_advanced_config_class
+
+        self.state.restorer_supir_advanced_config_class = apply_dynamic_changes(updated_config, SUPIR_ADVANCED_RULES)
+
+        return self.state.restorer_supir_advanced_config_class
+
+    def on_upscaler_sheet_change(
+        self,
+        updated_config: Union[SUPIR_Config, ControlNetTile_Config, FaithDiff_Config, None],
+    ):
+        """
+        Handles changes from the upscaler configuration PropertySheet.
+
+        It calls the internal `_update_sheet_changes` helper to apply dynamic rules
+        (like for progressive upscaling) and manage seed randomization, then
+        updates the global state.
+
+        Args:
+            updated_config (dataclass | None): The new configuration from the sheet.
+
+        Returns:
+            dataclass: The updated and processed configuration dataclass.
+        """
+        if updated_config is None:
+            return self.state.upscaler_config_class
+
+        self.state.upscaler_config_class = self._update_sheet_changes(updated_config, "Upscaler")
+
+        return self.state.upscaler_config_class
+
+    def on_upscaler_supir_advanced_sheet_change(self, updated_config: SUPIRAdvanced_Config | None):
+        """
+        Handles changes from the upscaler supir advanced configuration PropertySheet.
+
+        It calls the internal `apply_dynamic_changes` helper to apply dynamic rules
+        and manage seed randomization, then updates the global state.
+
+        Args:
+            updated_config (dataclass | None): The new configuration from the sheet.
+
+        Returns:
+            dataclass: The updated and processed configuration dataclass.
+        """
+        if updated_config is None:
+            return self.state.upscaler_supir_advanced_config_class
+
+        self.state.upscaler_supir_advanced_config_class = apply_dynamic_changes(updated_config, SUPIR_ADVANCED_RULES)
+
+        return self.state.upscaler_supir_advanced_config_class
+
+    def on_settings_tab_select(self):
+        """
+        Callback triggered when the 'Settings' tab is selected.
+
+        Ensures the settings sheet is correctly rendered with any dynamic rules applied.
+
+        Returns:
+            AppSettings: The processed AppSettings dataclass to be rendered.
+        """
+        return self.on_settings_sheet_change(self.state.uidata.settings)
+
+    def on_cancel_click(self):
+        """
+        Handles the 'Cancel' button click by setting a global threading event.
+        The running pipeline periodically checks this event and will stop execution
+        if it is set.
+        """
+        self.state.cancel_event.set()
+
+    def load_metadata(self, metadata: dict):
+        """
+        Loads settings from an image's metadata dictionary into the UI components.
+
+        This function acts as a bridge between the raw metadata and the UI. It defines
+        mappings for complex components like PropertySheets and standard Gradio
+        components, then uses a helper (`transfer_metadata`) to apply the values.
+
+        Args:
+            metadata (dict): A dictionary of key-value pairs extracted from image metadata.
+
+        Returns:
+            List[Any]: A list of values in the correct order to update the UI
+                       output components.
+
+        Raises:
+            gr.Error: If metadata conversion for a sampler setting fails.
+        """
+        # Get UI components
+        ui_inputs, output_fields = self.components._get_ui_inputs_and_outputs()
+        ui_inputs_for_metadata = ui_inputs.copy()
+        restorer_sheet = self.components.restorer_sheet
+        upscaler_sheet = self.components.upscaler_sheet
+        restorer_sheet_supir_advanced = self.components.restorer_sheet_supir_advanced
+        upscaler_sheet_supir_advanced = self.components.upscaler_sheet_supir_advanced
+
+        # Define the map that tells the helper how to process each PropertySheet.
+        # This is the "glue" between your generic helper and your specific app.
+        source_restorer_engine = RestorerEngine.from_str(metadata["Image Restore Engine"])
+        source_upscaler_engine = UpscalerEngine.from_str(metadata["Image Upscale Engine"])
+        source_restorer_class = RESTORER_CONFIG_MAPPING.get(source_restorer_engine.value)
+        source_upscaler_class = UPSCALER_CONFIG_MAPPING.get(source_upscaler_engine.value)
+        sheet_map = {}
+        if source_restorer_class:
+            sheet_map[id(restorer_sheet)] = {
+                "type": source_restorer_class.__class__,
+                "prefixes": ["Restorer", "Image Restore Engine"],
+            }
+
+            if source_restorer_engine == RestorerEngine.SUPIR:
+                sheet_map[id(restorer_sheet_supir_advanced)] = {
+                    "type": restorer_sheet_supir_advanced._dataclass_type,
+                    "prefixes": ["Restorer"],
+                }
+
+        if source_upscaler_class:
+            sheet_map[id(upscaler_sheet)] = {
+                "type": source_upscaler_class.__class__,
+                "prefixes": ["Upscaler", "Image Upscale Engine"],
+            }
+            if source_upscaler_engine == UpscalerEngine.SUPIR:
+                sheet_map[id(upscaler_sheet_supir_advanced)] = {
+                    "type": upscaler_sheet_supir_advanced._dataclass_type,
+                    "prefixes": ["Upscaler"],
+                }
+
+        gradio_map = {id(component): label for label, component in ui_inputs_for_metadata.items()}
+
+        output_values = transfer_metadata(
+            output_fields=output_fields,
+            metadata=metadata,
+            propertysheet_map=sheet_map,
+            gradio_component_map=gradio_map,
+        )
+
+        sampler_map_data = {
+            "restorer_sampler_settings": {
+                "prefix": "Restorer - Sampler",
+                "instance": SAMPLER_MAPPING.get("restorer_sampler"),
+            },
+            "upscaler_sampler_settings": {
+                "prefix": "Upscaler - Sampler",
+                "instance": SAMPLER_MAPPING.get("upscaler_sampler"),
+            },
+        }
+
+        for _, data in sampler_map_data.items():
+            sampler_instance, prefix = data["instance"], data["prefix"]
+            if not (sampler_instance and is_dataclass(sampler_instance)):
+                continue
+
+            for field in fields(sampler_instance):
+                label = field.metadata.get("label", field.name.replace("_", " ").title())
+                metadata_key = f"{prefix} - {label}"
+
+                if metadata_key in metadata:
+                    try:
+                        setattr(
+                            sampler_instance,
+                            field.name,
+                            infer_type(metadata[metadata_key]),
+                        )
+                    except (ValueError, TypeError):
+                        print(f"Warning: Could not convert metadata value '{metadata[metadata_key]}' for sampler field '{field.name}'.")
+                        raise gr.Error("Error loading Image metadata, see console log.")
+
+        return output_values
+
+    def on_load_metadata_from_gallery(self, folder_explorer, image_data: gr.EventData):
+        """
+        Callback to load metadata from an image selected in the 'Generated' gallery.
+
+        It extracts metadata from the selected image, calls the `load_metadata`
+        helper to process it, and applies the final settings to the UI components.
+        It also handles path corrections for example images.
+
+        Args:
+            folder_explorer (Any): The current value of the folder explorer component.
+            image_data (gr.EventData): Event data for the selected image, containing metadata.
+
+        Returns:
+            List[Any]: A list of values to update the UI components with the loaded settings.
+        """
+        # Get output_fields
+        _, output_fields = self.components._get_ui_inputs_and_outputs()
+
+        gallery_path = Path(folder_explorer)
+        is_example = all(part in gallery_path.parts for part in ["outputs", "examples"])
+
+        # Initial checks for valid input
+        if not image_data or not hasattr(image_data, "_data"):
+            return [gr.skip()] * len(output_fields)
+
+        metadata = image_data._data
+        output_values = self.load_metadata(metadata)
+        if output_values[0]:
+            self.state.restorer_config_class = self._update_sheet_changes(output_values[0], "Restorer")
+            RESTORER_CONFIG_MAPPING[metadata["Image Restore Engine"]] = self.state.restorer_config_class
+        if output_values[2]:
+            self.state.upscaler_config_class = self._update_sheet_changes(output_values[2], "Upscaler")
+            UPSCALER_CONFIG_MAPPING[metadata["Image Upscale Engine"]] = self.state.upscaler_config_class
+
+        output_values[0], output_values[2] = (
+            self.state.restorer_config_class,
+            self.state.upscaler_config_class,
+        )
+        input_image_name = output_values[11]
+        output_values[11] = os.path.join("assets/samples", input_image_name) if is_example and input_image_name else None
+
+        gr.Info("Image metadata loaded.")
+        return output_values
+
+    def on_input_image_change(self, input_image):
+        self.state.input_image_path = getattr(input_image, "path", None)
+
+    def on_load_metadata_from_single_image(self, image_data):
+        """
+        Callback to load metadata from the main input image component.
+
+        Triggered when an image with embedded metadata is uploaded. It extracts the
+        metadata and calls the `load_metadata` helper to apply it to the UI.
+
+        Args:
+            image_data (Image.Image | None): The image object from the ImageMeta component.
+
+        Returns:
+            List[Any]: A list of values/updates for the UI components.
+        """
+        # Get output_fields
+        _, output_fields = self.components._get_ui_inputs_and_outputs()
+
+        # Initial checks for valid input
+        if not image_data or not hasattr(image_data, "path"):
+            return [gr.skip()] * len(output_fields)
+
+        # Extract the flat metadata dictionary from the image
+        metadata = extract_metadata(image_data, only_custom_metadata=True)
+        if not metadata:
+            return [gr.skip()] * len(output_fields)
+
+        output_values = self.load_metadata(metadata)
+        if output_values[0]:
+            self.state.restorer_config_class = self._update_sheet_changes(output_values[0], "Restorer")
+            RESTORER_CONFIG_MAPPING[metadata["Image Restore Engine"]] = self.state.restorer_config_class
+        if output_values[2]:
+            self.state.upscaler_config_class = self._update_sheet_changes(output_values[2], "Upscaler")
+            UPSCALER_CONFIG_MAPPING[metadata["Image Upscale Engine"]] = self.state.upscaler_config_class
+
+        output_values[0], output_values[2] = (
+            self.state.restorer_config_class,
+            self.state.upscaler_config_class,
+        )
+        output_values[11] = None
+
+        gr.Info("Image metadata loaded.")
+        return output_values
+
+    def on_clear_log_output(self):
+        """
+        Clears the content of the LiveLog viewer component.
+
+        Returns:
+            None: Sets the value of the LiveLog component to None, clearing it.
+        """
+        return None
+
+    def on_check_inputs(
+        self,
+        restorer_engine,
+        upscaler_engine,
+        restorer_model_name,
+        upscaler_model_name,
+        action="generation_process",
+    ):
+        """
+        Validates the core inputs before starting a process like generation or masking.
+
+        Raises a gr.Error with a user-friendly message if validation fails.
+        Also configures the bottom bar and logger for the upcoming process.
+
+        Args:
+            restorer_engine (str): The selected restorer engine.
+            upscaler_engine (str): The selected upscaler engine.
+            restorer_model_name (str): The selected restorer model.
+            upscaler_model_name (str): The selected upscaler model.
+            action (str): The type of action being initiated, used to tailor checks.
+
+        Returns:
+            Tuple[gr.update, gr.update]: Updates to open the bottom bar and configure
+                                         the LiveLog display mode.
+        """
+        if self.state.input_image_path is None:
+            raise gr.Error("Input image is required. Please upload an image to proceed.")
+
+        if action == "generation_process":
+            if restorer_engine == "None" and upscaler_engine == "None":
+                raise gr.Error("Please select at least a Restorer or an Upscaler engine.")
+            if restorer_engine != "None" and restorer_model_name == "None":
+                raise gr.Error("Please select a Restorer model when using the Restore engine.")
+            if upscaler_engine != "None" and upscaler_model_name == "None":
+                raise gr.Error("Please select an Upscaler model when using the Upscale engine.")
+
+        return gr.update(open=True), gr.update(display_mode="full" if action == "generation_process" else "log")
+
+    def on_refresh_restoration_mask(self, mask_prompt, **kwargs):
+        """
+        Generates a face restoration mask based on a text prompt.
+
+        This function is decorated with `@livelog` to stream log outputs to the UI.
+        It initializes the pipeline and calls the `generate_prompt_mask` method.
+
+        Args:
+            mask_prompt (str): The prompt used to identify the area to mask (e.g., "head").
+            lq_image_path (Any): The file object for the low-quality input image.
+            **kwargs: Injected by the `@livelog` decorator (e.g., `log_callback`).
+
+        Returns:
+            PIL.Image: The generated mask image.
+        """
+        log_callback = kwargs.get("log_callback")
+        logger = logging.getLogger(kwargs.get("log_name", "suptoolbox_app"))
+        log_callback(log_content="Starting masking generation...")
+
+        if self.state.input_image_path is None:
+            raise gr.Error("Input image must be provided!")
+
+        lq_image = Image.open(self.state.input_image_path).convert("RGB")
+        self.state.cancel_event.clear()
+        self.update_pipeline(log_callback=log_callback)
+
+        try:
+            mask, _ = sup_toolbox_pipe.generate_prompt_mask(lq_image, mask_prompt)
+            if mask is None:
+                gr.Warning("Mask couldn't be generated!")
+            return mask
+        except Exception as e:
+            logger.error(f"Error in generation object mask: {e}, process aborted!", exc_info=True)
+            raise e
+
+    def on_generate_caption(self, **kwargs):
+        """
+        Generates a descriptive caption for the input image.
+
+        Decorated with `@livelog` to stream logs. It initializes the pipeline
+        and uses the `generate_caption` method.
+
+        Args:
+            lq_image_path (Any): The file object for the low-quality input image.
+            **kwargs: Injected by the `@livelog` decorator.
+
+        Returns:
+            str: The generated image caption.
+        """
+        log_callback = kwargs.get("log_callback")
+        logger = logging.getLogger(kwargs.get("log_name", "suptoolbox_app"))
+        log_callback(log_content="Starting caption generation...")
+
+        if self.state.input_image_path is None:
+            raise gr.Error("Input image must be provided!")
+
+        lq_image = Image.open(self.state.input_image_path).convert("RGB")
+        self.state.cancel_event.clear()
+        self.update_pipeline(log_callback=log_callback)
+
+        try:
+            caption = sup_toolbox_pipe.generate_caption(lq_image)
+            if caption is None:
+                gr.Warning("Caption couldn't be generated!")
+            return caption
+        except Exception as e:
+            logger.error(f"Error in caption generation: {e}, process aborted!", exc_info=True)
+            raise e
+
+    def on_generate(self, *args):
+        """
+        Starts the image processing thread and yields updates from a queue.
+        This method is the entry point for the Gradio event chain.
+        """
+
+        # 1. Send initial UI state update (disable buttons, show progress).
+        yield None, None, gr.update(interactive=False), gr.update(visible=True), gr.update(open=True)
+        update_queue = queue.Queue()
+
+        # 2. Package arguments for the worker thread.
+        thread_args = (update_queue, *args)
+
+        # 3. Start the image processing worker thread.
+        diffusion_thread = threading.Thread(target=self._process_image, args=thread_args)
+        diffusion_thread.start()
+
+        # 4. Loop to read from the queue and yield updates to the UI.
+        final_images, log_update = None, None
+        while True:
+            update = update_queue.get()
+            if update is None:  # Sentinel value indicating the thread has finished.
+                break
+
+            images, log_update = update
+
+            if images:
+                final_images = images
+
+            # Yield the update to the Gradio outputs.
+            yield final_images, log_update, gr.skip(), gr.skip(), gr.skip()
+
+        # 5. Send final UI state update (re-enable buttons).
+        yield final_images, log_update, gr.update(interactive=True), gr.update(visible=False), gr.skip()
+
+    def _process_image(self, update_queue: queue.Queue, total_steps: int, *input_params: Any, **kwargs):
+        """
+        Executes the main image processing pipeline in a worker thread.
+
+        This method receives simple, serializable data types from the UI event.
+        It retrieves complex configuration objects (like PropertySheet values)
+        directly from the shared application state (`self.state`), which are kept
+        up-to-date by their respective `.change()` events.
+
+        Args:
+            update_queue (queue.Queue): The queue for sending status updates back to the UI.
+            total_steps (int): The pre-calculated total number of diffusion steps.
+            *input_params (Any): A tuple of the remaining simple UI input values
+                (e.g., engine selections, prompts), passed positionally.
+            **kwargs: Catches any extra keyword arguments.
+
+        Side Effects:
+            - Puts multiple update dictionaries and a final `None` sentinel onto the `update_queue`.
+            - Modifies and uses the shared `sup_toolbox_pipe` instance via `self.update_pipeline`.
+            - Catches all exceptions and reports them via the queue.
+        """
+        from sup_toolbox.sup_toolbox_pipeline import PipelineCancelationRequested
+
+        # 1. Prepare input params
+        restorer_config = self.state.restorer_config_class
+        upscaler_config = self.state.upscaler_config_class
+        restorer_supir_advanced_config = self.state.restorer_supir_advanced_config_class
+        upscaler_supir_advanced_config = self.state.upscaler_supir_advanced_config_class
+        ui_inputs, _ = self.components._get_ui_inputs_and_outputs()
+        ui_inputs_keys_sliced = list(ui_inputs.keys())[4:]
+        input_param_with_values = dict(zip(ui_inputs_keys_sliced, input_params))
+        input_image, res_engine, ups_engine = (
+            self.state.input_image_path,
+            input_param_with_values.get("Image Restore Engine"),
+            input_param_with_values.get("Image Upscale Engine"),
+        )
+
+        if hasattr(input_image, "orig_name"):
+            input_param_with_values["Input Image"] = input_image.orig_name
+        else:
+            input_param_with_values.pop("Input Image", None)
+
+        if input_image is None:
+            update_queue.put((None, {"logs": [{"type": "log", "level": "ERROR", "content": "Error: Input image is required."}]}))
+            update_queue.put(None)
+            return
+
+        # 2. Generate image metadata
+        image_metadata = self.generate_image_metadata(
+            restorer_config,
+            upscaler_config,
+            (restorer_supir_advanced_config if res_engine == RestorerEngine.SUPIR.value else None),
+            (upscaler_supir_advanced_config if ups_engine == UpscalerEngine.SUPIR.value else None),
+            input_param_with_values,
+            SAMPLER_MAPPING["restorer_sampler"],
+            SAMPLER_MAPPING["upscaler_sampler"],
+        )
+
+        tracker = None
+        self.state.cancel_event.clear()
+
+        with capture_logs(log_level=logging.INFO, log_name=["suptoolbox_app", "suptoolbox"]) as get_logs:
+            try:
+                rate_queue = queue.Queue()
+                tqdm_writer = TqdmToQueueWriter(rate_queue)
+                progress_bar_handler = Tee(sys.stderr, tqdm_writer)
+                all_logs, last_known_rate_data = [], None
+
+                # 2. Prepare selected engines
+                config = self.state.uidata.config
+
+                _restorer_config, _upscaler_config = self.prepare_engine_configs(res_engine, restorer_config, ups_engine, upscaler_config)
+
+                # 3. Define update callback
+                def process_and_send_updates(status="running", advance=0, final_image_payload=None):
+                    nonlocal all_logs, last_known_rate_data
+                    new_rate_data = None
+                    while not rate_queue.empty():
+                        try:
+                            new_rate_data = rate_queue.get_nowait()
+                        except queue.Empty:
+                            break
+
+                    if new_rate_data:
+                        last_known_rate_data = new_rate_data
+
+                    new_records = get_logs()
+                    if new_records:
+                        new_logs = [
+                            {"type": "log", "level": "SUCCESS" if r.levelno == logging.INFO + 5 else r.levelname, "content": r.getMessage()}
+                            for r in new_records
+                        ]
+                        all_logs.extend(new_logs)
+
+                    update_dict = (
+                        tracker.update(advance=advance, status=status, logs=all_logs, rate_data=last_known_rate_data)
+                        if tracker
+                        else {"type": "progress", "logs": all_logs, "current": 0, "total": total_steps, "desc": "Diffusion Steps"}
+                    )
+                    update_queue.put((final_image_payload, update_dict))
+
+                logger = logging.getLogger("suptoolbox_app")
+                logger.info("Starting diffusion process...")
+                process_and_send_updates()
+
+                # 4. Create tracker
+                tracker = ProgressTracker(total=total_steps, description="Diffusion Steps", rate_unit="s/it")
+
+                # 5. Define pipeline progress callback
+                def progress_callback(_, __, ___, callback_kwargs):
+                    process_and_send_updates(advance=callback_kwargs["advance"])
+                    return callback_kwargs
+
+                # 6. Map all pipeline configuration from UI to SUP-Toolbox Pipeline
+                config = self.state.uidata.config
+                config.restorer_engine, config.upscaler_engine = (
+                    RestorerEngine.from_str(res_engine),
+                    UpscalerEngine.from_str(ups_engine),
+                )
+                config.selected_vae_model = input_param_with_values["VAE Model"]
+                if res_engine == RestorerEngine.SUPIR.value:
+                    _restorer_config = cast(SUPIR_Config, _restorer_config)
+                    config.selected_restorer_checkpoint_model = input_param_with_values["Image Restore Model"]
+                    config.restorer_engine = RestorerEngine.SUPIR
+                    config.selected_restorer_sampler = Sampler.from_str(input_param_with_values["Image Restore Sampler"])
+                    config.restorer_pipeline_params.supir_model = SUPIRModel.from_str(_restorer_config.supir_model)
+                    config.restorer_pipeline_params.seed = _restorer_config.general.seed
+                    config.restorer_pipeline_params.upscale_factor = _restorer_config.general.upscale_factor
+                    config.restorer_pipeline_params.prompt = input_param_with_values["Image Restore - Prompt 1"]
+                    config.restorer_pipeline_params.prompt_2 = input_param_with_values["Image Restore - Prompt 2"]
+                    config.restorer_pipeline_params.negative_prompt = input_param_with_values["Image Restore - Negative prompt"]
+                    config.restore_face = input_param_with_values["Enable Face Restoration"]
+                    config.mask_prompt = input_param_with_values["Mask Prompt"]
+                    config.restorer_pipeline_params.num_images = _restorer_config.general.num_images
+                    config.restorer_pipeline_params.num_steps = _restorer_config.general.num_steps
+                    config.restorer_pipeline_params.use_lpw_prompt = (
+                        True if input_param_with_values["Image Restore - Prompt method"] == PromptMethod.Weighted.value else False
+                    )
+                    config.restorer_pipeline_params.tile_size = _restorer_config.general.tile_size
+                    config.restorer_pipeline_params.restoration_scale = float(_restorer_config.restoration_scale)
+                    config.restorer_pipeline_params.s_churn = float(_restorer_config.s_churn)
+                    config.restorer_pipeline_params.s_noise = float(_restorer_config.s_noise)
+                    config.restorer_pipeline_params.strength = float(_restorer_config.strength)
+                    config.restorer_pipeline_params.use_linear_CFG = _restorer_config.cfg_settings.use_linear_CFG
+                    config.restorer_pipeline_params.guidance_scale = float(_restorer_config.general.guidance_scale)
+                    config.restorer_pipeline_params.guidance_rescale = float(_restorer_config.general.guidance_rescale)
+                    config.restorer_pipeline_params.reverse_linear_CFG = float(_restorer_config.cfg_settings.reverse_linear_CFG)
+                    config.restorer_pipeline_params.guidance_scale_start = float(_restorer_config.cfg_settings.guidance_scale_start)
+                    config.restorer_pipeline_params.use_linear_control_scale = _restorer_config.controlnet_settings.use_linear_control_scale
+                    config.restorer_pipeline_params.reverse_linear_control_scale = _restorer_config.controlnet_settings.reverse_linear_control_scale
+                    config.restorer_pipeline_params.controlnet_conditioning_scale = float(_restorer_config.controlnet_settings.controlnet_conditioning_scale)
+                    config.restorer_pipeline_params.control_scale_start = float(_restorer_config.controlnet_settings.control_scale_start)
+                    config.restorer_pipeline_params.enable_PAG = _restorer_config.pag_settings.enable_PAG and len(_restorer_config.pag_settings.pag_layers) > 0
+                    config.restorer_pipeline_params.use_linear_PAG = _restorer_config.pag_settings.use_linear_PAG
+                    config.restorer_pipeline_params.reverse_linear_PAG = _restorer_config.pag_settings.reverse_linear_PAG
+                    config.restorer_pipeline_params.pag_scale = float(_restorer_config.pag_settings.pag_scale)
+                    config.restorer_pipeline_params.pag_scale_start = float(_restorer_config.pag_settings.pag_scale_start)
+                    config.restorer_pipeline_params.pag_layers = _restorer_config.pag_settings.pag_layers
+                    config.restorer_pipeline_params.start_point = StartPoint.from_str(_restorer_config.start_point)
+                    config.restorer_pipeline_params.image_size_fix_mode = ImageSizeFixMode.from_str(_restorer_config.general.image_size_fix_mode)
+                    config.restorer_pipeline_params.color_fix_mode = ColorFix.from_str(_restorer_config.post_processsing_settings.color_fix_mode)
+                    (
+                        config.restorer_pipeline_params.zero_sft_injection_configs,
+                        config.restorer_pipeline_params.zero_sft_injection_flags,
+                    ) = self.state.uidata.map_ui_supir_injection_to_pipeline_params(restorer_supir_advanced_config)
+                    config.restorer_pipeline_params.callback_on_step_end = progress_callback
+                    config.restorer_sampler_config = self.state.uidata.map_scheduler_settings_to_config(SAMPLER_MAPPING["restorer_sampler"])
+                elif res_engine == RestorerEngine.FaithDiff.value:
+                    _restorer_config = cast(FaithDiff_Config, _restorer_config)
+                    config.selected_restorer_checkpoint_model = input_param_with_values["Image Restore Model"]
+                    config.restorer_engine = RestorerEngine.FaithDiff
+                    config.selected_restorer_sampler = Sampler.from_str(input_param_with_values["Image Restore Sampler"])
+                    config.restorer_pipeline_params.seed = _restorer_config.general.seed
+                    config.restorer_pipeline_params.upscale_factor = _restorer_config.general.upscale_factor
+                    config.restorer_pipeline_params.prompt = input_param_with_values["Image Restore - Prompt 1"]
+                    config.restorer_pipeline_params.prompt_2 = input_param_with_values["Image Restore - Prompt 2"]
+                    config.restorer_pipeline_params.negative_prompt = input_param_with_values["Image Restore - Negative prompt"]
+                    config.restore_face = input_param_with_values["Enable Face Restoration"]
+                    config.mask_prompt = input_param_with_values["Mask Prompt"]
+                    config.restorer_pipeline_params.num_images = _restorer_config.general.num_images
+                    config.restorer_pipeline_params.num_steps = _restorer_config.general.num_steps
+                    config.restorer_pipeline_params.use_lpw_prompt = (
+                        True if input_param_with_values["Image Restore - Prompt method"] == PromptMethod.Weighted.value else False
+                    )
+                    config.restorer_pipeline_params.tile_size = _restorer_config.general.tile_size
+                    config.restorer_pipeline_params.s_churn = float(_restorer_config.s_churn)
+                    config.restorer_pipeline_params.s_noise = float(_restorer_config.s_noise)
+                    config.restorer_pipeline_params.strength = float(_restorer_config.strength)
+                    config.restorer_pipeline_params.guidance_scale = float(_restorer_config.general.guidance_scale)
+                    config.restorer_pipeline_params.guidance_rescale = float(_restorer_config.general.guidance_rescale)
+                    config.restorer_pipeline_params.use_linear_control_scale = _restorer_config.controlnet_settings.use_linear_control_scale
+                    config.restorer_pipeline_params.reverse_linear_control_scale = _restorer_config.controlnet_settings.reverse_linear_control_scale
+                    config.restorer_pipeline_params.controlnet_conditioning_scale = float(_restorer_config.controlnet_settings.controlnet_conditioning_scale)
+                    config.restorer_pipeline_params.control_scale_start = float(_restorer_config.controlnet_settings.control_scale_start)
+                    config.restorer_pipeline_params.enable_PAG = _restorer_config.pag_settings.enable_PAG and len(_restorer_config.pag_settings.pag_layers) > 0
+                    config.restorer_pipeline_params.use_linear_PAG = _restorer_config.pag_settings.use_linear_PAG
+                    config.restorer_pipeline_params.reverse_linear_PAG = _restorer_config.pag_settings.reverse_linear_PAG
+                    config.restorer_pipeline_params.pag_scale = float(_restorer_config.pag_settings.pag_scale)
+                    config.restorer_pipeline_params.pag_scale_start = float(_restorer_config.pag_settings.pag_scale_start)
+                    config.restorer_pipeline_params.pag_layers = _restorer_config.pag_settings.pag_layers
+                    config.restorer_pipeline_params.start_point = StartPoint.from_str(_restorer_config.start_point)
+                    config.restorer_pipeline_params.image_size_fix_mode = ImageSizeFixMode.from_str(_restorer_config.general.image_size_fix_mode)
+                    config.restorer_pipeline_params.color_fix_mode = ColorFix.from_str(_restorer_config.post_processsing_settings.color_fix_mode)
+                    config.restorer_pipeline_params.invert_prompts = _restorer_config.invert_prompts
+                    config.restorer_pipeline_params.apply_ipa_embeds = _restorer_config.apply_ipa_embeds
+                    config.restorer_pipeline_params.callback_on_step_end = progress_callback
+                    config.restorer_sampler_config = self.state.uidata.map_scheduler_settings_to_config(SAMPLER_MAPPING["restorer_sampler"])
+                if ups_engine == UpscalerEngine.SUPIR.value:
+                    _upscaler_config = cast(SUPIR_Config, _upscaler_config)
+                    config.selected_upscaler_checkpoint_model = input_param_with_values["Image Upscale Model"]
+                    config.upscaler_engine = UpscalerEngine.SUPIR
+                    config.selected_upscaler_sampler = Sampler.from_str(input_param_with_values["Image Upscale Sampler"])
+                    config.upscaler_pipeline_params.supir_model = SUPIRModel.from_str(_upscaler_config.supir_model)
+                    config.upscaler_pipeline_params.seed = _upscaler_config.general.seed
+                    config.upscaler_pipeline_params.upscale_factor = _upscaler_config.general.upscale_factor
+                    config.upscaler_pipeline_params.prompt = input_param_with_values["Image Upscale - Prompt 1"]
+                    config.upscaler_pipeline_params.prompt_2 = input_param_with_values["Image Upscale - Prompt 2"]
+                    config.upscaler_pipeline_params.negative_prompt = input_param_with_values["Image Upscale - Negative prompt"]
+                    config.upscaler_pipeline_params.num_images = _upscaler_config.general.num_images
+                    config.upscaler_pipeline_params.num_steps = _upscaler_config.general.num_steps
+                    config.upscaler_pipeline_params.use_lpw_prompt = (
+                        True if input_param_with_values["Image Upscale - Prompt method"] == PromptMethod.Weighted.value else False
+                    )
+                    config.upscaler_pipeline_params.tile_size = _upscaler_config.general.tile_size
+                    config.upscaler_pipeline_params.restoration_scale = float(_upscaler_config.restoration_scale)
+                    config.upscaler_pipeline_params.s_churn = float(_upscaler_config.s_churn)
+                    config.upscaler_pipeline_params.s_noise = float(_upscaler_config.s_noise)
+                    config.upscaler_pipeline_params.strength = float(_upscaler_config.strength)
+                    config.upscaler_pipeline_params.use_linear_CFG = _upscaler_config.cfg_settings.use_linear_CFG
+                    config.upscaler_pipeline_params.guidance_scale = float(_upscaler_config.general.guidance_scale)
+                    config.upscaler_pipeline_params.guidance_rescale = float(_upscaler_config.general.guidance_rescale)
+                    config.upscaler_pipeline_params.reverse_linear_CFG = float(_upscaler_config.cfg_settings.reverse_linear_CFG)
+                    config.upscaler_pipeline_params.guidance_scale_start = float(_upscaler_config.cfg_settings.guidance_scale_start)
+                    config.upscaler_pipeline_params.use_linear_control_scale = _upscaler_config.controlnet_settings.use_linear_control_scale
+                    config.upscaler_pipeline_params.reverse_linear_control_scale = _upscaler_config.controlnet_settings.reverse_linear_control_scale
+                    config.upscaler_pipeline_params.controlnet_conditioning_scale = float(_upscaler_config.controlnet_settings.controlnet_conditioning_scale)
+                    config.upscaler_pipeline_params.control_scale_start = float(_upscaler_config.controlnet_settings.control_scale_start)
+                    config.upscaler_pipeline_params.enable_PAG = _upscaler_config.pag_settings.enable_PAG
+                    config.upscaler_pipeline_params.use_linear_PAG = _upscaler_config.pag_settings.use_linear_PAG
+                    config.upscaler_pipeline_params.reverse_linear_PAG = (
+                        _upscaler_config.pag_settings.reverse_linear_PAG and len(_upscaler_config.pag_settings.pag_layers) > 0
+                    )
+                    config.upscaler_pipeline_params.pag_scale = float(_upscaler_config.pag_settings.pag_scale)
+                    config.upscaler_pipeline_params.pag_scale_start = float(_upscaler_config.pag_settings.pag_scale_start)
+                    config.upscaler_pipeline_params.pag_layers = _upscaler_config.pag_settings.pag_layers
+                    config.upscaler_pipeline_params.start_point = StartPoint.from_str(_upscaler_config.start_point)
+                    config.upscaler_pipeline_params.image_size_fix_mode = ImageSizeFixMode.from_str(_upscaler_config.general.image_size_fix_mode)
+                    config.upscaler_pipeline_params.upscaling_mode = UpscalingMode.from_str(_upscaler_config.general.upscaling_mode)
+                    (
+                        config.upscaler_pipeline_params.zero_sft_injection_configs,
+                        config.upscaler_pipeline_params.zero_sft_injection_flags,
+                    ) = self.state.uidata.map_ui_supir_injection_to_pipeline_params(upscaler_supir_advanced_config)
+                    config.upscaler_pipeline_params.cfg_decay_rate = _upscaler_config.general.cfg_decay_rate
+                    config.upscaler_pipeline_params.strength_decay_rate = _upscaler_config.general.strength_decay_rate
+                    config.upscaler_pipeline_params.color_fix_mode = ColorFix.from_str(_upscaler_config.post_processsing_settings.color_fix_mode)
+                    config.upscaler_pipeline_params.callback_on_step_end = progress_callback
+                    config.upscaler_sampler_config = self.state.uidata.map_scheduler_settings_to_config(SAMPLER_MAPPING["upscaler_sampler"])
+                elif ups_engine == UpscalerEngine.FaithDiff.value:
+                    _upscaler_config = cast(FaithDiff_Config, _upscaler_config)
+                    config.selected_upscaler_checkpoint_model = input_param_with_values["Image Upscale Model"]
+                    config.upscaler_engine = UpscalerEngine.FaithDiff
+                    config.selected_upscaler_sampler = Sampler.from_str(input_param_with_values["Image Upscale Sampler"])
+                    config.upscaler_pipeline_params.seed = _upscaler_config.general.seed
+                    config.upscaler_pipeline_params.upscale_factor = _upscaler_config.general.upscale_factor
+                    config.upscaler_pipeline_params.prompt = input_param_with_values["Image Upscale - Prompt 1"]
+                    config.upscaler_pipeline_params.prompt_2 = input_param_with_values["Image Upscale - Prompt 2"]
+                    config.upscaler_pipeline_params.negative_prompt = input_param_with_values["Image Upscale - Negative prompt"]
+                    config.upscaler_pipeline_params.num_images = _upscaler_config.general.num_images
+                    config.upscaler_pipeline_params.num_steps = _upscaler_config.general.num_steps
+                    config.upscaler_pipeline_params.use_lpw_prompt = (
+                        True if input_param_with_values["Image Upscale - Prompt method"] == PromptMethod.Weighted.value else False
+                    )
+                    config.upscaler_pipeline_params.tile_size = _upscaler_config.general.tile_size
+                    config.upscaler_pipeline_params.s_churn = float(_upscaler_config.s_churn)
+                    config.upscaler_pipeline_params.s_noise = float(_upscaler_config.s_noise)
+                    config.upscaler_pipeline_params.strength = float(_upscaler_config.strength)
+                    config.upscaler_pipeline_params.guidance_scale = float(_upscaler_config.general.guidance_scale)
+                    config.upscaler_pipeline_params.guidance_rescale = float(_upscaler_config.general.guidance_rescale)
+                    config.upscaler_pipeline_params.use_linear_control_scale = _upscaler_config.controlnet_settings.use_linear_control_scale
+                    config.upscaler_pipeline_params.reverse_linear_control_scale = _upscaler_config.controlnet_settings.reverse_linear_control_scale
+                    config.upscaler_pipeline_params.controlnet_conditioning_scale = float(_upscaler_config.controlnet_settings.controlnet_conditioning_scale)
+                    config.upscaler_pipeline_params.control_scale_start = float(_upscaler_config.controlnet_settings.control_scale_start)
+                    config.upscaler_pipeline_params.enable_PAG = _upscaler_config.pag_settings.enable_PAG and len(_upscaler_config.pag_settings.pag_layers) > 0
+                    config.upscaler_pipeline_params.use_linear_PAG = _upscaler_config.pag_settings.use_linear_PAG
+                    config.upscaler_pipeline_params.reverse_linear_PAG = _upscaler_config.pag_settings.reverse_linear_PAG
+                    config.upscaler_pipeline_params.pag_scale = float(_upscaler_config.pag_settings.pag_scale)
+                    config.upscaler_pipeline_params.pag_scale_start = float(_upscaler_config.pag_settings.pag_scale_start)
+                    config.upscaler_pipeline_params.pag_layers = _upscaler_config.pag_settings.pag_layers
+                    config.upscaler_pipeline_params.start_point = StartPoint.from_str(_upscaler_config.start_point)
+                    config.upscaler_pipeline_params.image_size_fix_mode = ImageSizeFixMode.from_str(_upscaler_config.general.image_size_fix_mode)
+                    config.upscaler_pipeline_params.upscaling_mode = UpscalingMode.from_str(_upscaler_config.general.upscaling_mode)
+                    config.upscaler_pipeline_params.invert_prompts = _upscaler_config.invert_prompts
+                    config.upscaler_pipeline_params.apply_ipa_embeds = _upscaler_config.apply_ipa_embeds
+                    config.upscaler_pipeline_params.cfg_decay_rate = _upscaler_config.general.cfg_decay_rate
+                    config.upscaler_pipeline_params.strength_decay_rate = _upscaler_config.general.strength_decay_rate
+                    config.upscaler_pipeline_params.color_fix_mode = ColorFix.from_str(_upscaler_config.post_processsing_settings.color_fix_mode)
+                    config.upscaler_pipeline_params.callback_on_step_end = progress_callback
+                    config.upscaler_sampler_config = self.state.uidata.map_scheduler_settings_to_config(SAMPLER_MAPPING["upscaler_sampler"])
+                elif ups_engine == UpscalerEngine.ControlNetTile.value:
+                    _upscaler_config = cast(ControlNetTile_Config, _upscaler_config)
+                    config.selected_upscaler_checkpoint_model = input_param_with_values["Image Upscale Model"]
+                    config.upscaler_engine = UpscalerEngine.ControlNetTile
+                    config.selected_upscaler_sampler = Sampler.from_str(input_param_with_values["Image Upscale Sampler"])
+                    config.upscaler_pipeline_params.seed = _upscaler_config.general.seed
+                    config.upscaler_pipeline_params.upscale_factor = _upscaler_config.general.upscale_factor
+                    config.upscaler_pipeline_params.prompt = input_param_with_values["Image Upscale - Prompt 1"]
+                    config.upscaler_pipeline_params.prompt_2 = input_param_with_values["Image Upscale - Prompt 2"]
+                    config.upscaler_pipeline_params.negative_prompt = input_param_with_values["Image Upscale - Negative prompt"]
+                    config.upscaler_pipeline_params.num_images = _upscaler_config.general.num_images
+                    config.upscaler_pipeline_params.num_steps = _upscaler_config.general.num_steps
+                    config.upscaler_pipeline_params.tile_size = _upscaler_config.general.tile_size
+                    config.upscaler_pipeline_params.tile_overlap = _upscaler_config.tile_overlap
+                    config.upscaler_pipeline_params.tile_weighting_method = WeightingMethod.from_str(_upscaler_config.tile_weighting_method)
+                    config.upscaler_pipeline_params.tile_gaussian_sigma = _upscaler_config.tile_gaussian_sigma
+                    config.upscaler_pipeline_params.strength = float(_upscaler_config.strength)
+                    config.upscaler_pipeline_params.guidance_scale = float(_upscaler_config.general.guidance_scale)
+                    config.upscaler_pipeline_params.guidance_rescale = float(_upscaler_config.general.guidance_rescale)
+                    config.upscaler_pipeline_params.image_size_fix_mode = ImageSizeFixMode.from_str(_upscaler_config.general.image_size_fix_mode)
+                    config.upscaler_pipeline_params.upscaling_mode = UpscalingMode.from_str(_upscaler_config.general.upscaling_mode)
+                    config.upscaler_pipeline_params.cfg_decay_rate = _upscaler_config.general.cfg_decay_rate
+                    config.upscaler_pipeline_params.strength_decay_rate = _upscaler_config.general.strength_decay_rate
+                    config.upscaler_pipeline_params.color_fix_mode = ColorFix.from_str(_upscaler_config.post_processsing_settings.color_fix_mode)
+                    config.upscaler_pipeline_params.callback_on_step_end = progress_callback
+                    config.upscaler_sampler_config = self.state.uidata.map_scheduler_settings_to_config(SAMPLER_MAPPING["upscaler_sampler"])
+
+                config.image_path = input_image
+                self.update_pipeline(log_callback=process_and_send_updates, progress_bar_handler=progress_bar_handler)
+
+                initialize_status = sup_toolbox_pipe.initialize()
+                if initialize_status:
+                    result, process_status = sup_toolbox_pipe.predict(metadata=image_metadata)
+                    if process_status:
+                        logger.log(logging.INFO + 5, "Image generated successfully!")
+                        process_and_send_updates(status="success", final_image_payload=(input_image, result))
+                    else:
+                        raise RuntimeError("Pipeline prediction returned a failure status.")
+                else:
+                    raise RuntimeError("Pipeline initialization failed.")
+
+            except PipelineCancelationRequested as ce:
+                logger.warning(str(ce))
+                process_and_send_updates(status="error")
+            except Exception as e:
+                logger.error(f"Error in diffusion thread: {e}, process aborted!", exc_info=True)
+                process_and_send_updates(status="error")
+            finally:
+                update_queue.put(None)

ui/ui_layout.py

@@ -0,0 +1,684 @@
+# Copyright 2025 The DEVAIEXP Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass, field
+from typing import Any, Dict
+
+import gradio as gr
+
+# Custom Component Imports
+from gradio_bottombar import BottomBar
+from gradio_buttonplus import ButtonPlus
+from gradio_creditspanel import CreditsPanel
+from gradio_dropdownplus import DropdownPlus
+from gradio_folderexplorer import FolderExplorer
+from gradio_htmlinjector import HTMLInjector
+from gradio_imagemeta import ImageMeta
+from gradio_livelog import LiveLog
+from gradio_mediagallery import MediaGallery
+from gradio_propertysheet import PropertySheet
+from gradio_taggrouphelper import TagGroupHelper
+from gradio_textboxplus import TextboxPlus
+from gradio_tokenizertextbox import TokenizerTextBox
+from gradio_topbar import TopBar
+
+from ui.ui_config import (
+    CREDIT_LIST,
+    LICENSE_PATHS,
+    TAG_DATA_NEGATIVE,
+    TAG_DATA_POSITIVE,
+    AppSettings,
+    ControlNetTile_Config,
+    SUPIR_Config,
+    SUPIRAdvanced_Config,
+)
+from ui.ui_data import UIData
+
+
+@dataclass
+class UIComponents:
+    """A dataclass to hold all interactive UI components for type safety and Intellisense."""
+
+    html_injector: HTMLInjector
+    flyout_visible: gr.State
+    active_anchor_id: gr.State
+    js_data_bridge: gr.Textbox
+    total_inference_steps: gr.State
+    run_btn: gr.Button
+    cancel_btn: gr.Button
+    preset_name: TextboxPlus
+    presets: DropdownPlus
+    save_preset_btn: gr.Button
+    load_preset_btn: gr.Button
+    restorer_engine: DropdownPlus
+    upscaler_engine: DropdownPlus
+    restorer_model: DropdownPlus
+    upscaler_model: DropdownPlus
+    vae_model: gr.Dropdown
+    restorer_sampler: DropdownPlus
+    restorer_sampler_ear_btn: ButtonPlus
+    upscaler_sampler: DropdownPlus
+    upscaler_sampler_ear_btn: ButtonPlus
+    flyout_property_sheet_close_btn: gr.Button
+    flyout_sheet: PropertySheet
+    main_tabs: gr.Tabs
+    input_image: ImageMeta
+    result_slider: gr.ImageSlider
+    ec_accordion: gr.Accordion
+    config_tabs: gr.Tabs
+    restorer_tab: gr.Tab
+    res_prompt_method: gr.Dropdown
+    res_prompt: gr.Textbox
+    res_prompt_generate_btn: ButtonPlus
+    res_prompt_2: gr.Textbox
+    res_tokenizer_pos: TokenizerTextBox
+    res_negative_prompt: gr.Textbox
+    res_tokenizer_neg: TokenizerTextBox
+    preview_restoration_mask_chk: gr.Checkbox
+    restoration_mask_prompt: gr.Textbox
+    preview_restoration_mask_btn: ButtonPlus
+    flyout_restoration_image_close_btn: gr.Button
+    restoration_mask: gr.Image
+    restorer_sheet: PropertySheet
+    restorer_sheet_supir_advanced: PropertySheet
+    upscaler_tab: gr.Tab
+    ups_prompt_method: gr.Dropdown
+    ups_prompt: gr.Textbox
+    ups_prompt_generate_btn: ButtonPlus
+    ups_prompt_2: gr.Textbox
+    ups_tokenizer_pos: TokenizerTextBox
+    ups_negative_prompt: gr.Textbox
+    ups_tokenizer_neg: TokenizerTextBox
+    upscaler_sheet: PropertySheet
+    upscaler_sheet_supir_advanced: PropertySheet
+    generated_tab: gr.Tab
+    folder_explorer: FolderExplorer
+    generated_image_viewer: MediaGallery
+    settings_tab: gr.Tab
+    settings_sheet: PropertySheet
+    reset_settings_btn: gr.Button
+    save_settings_btn: gr.Button
+    about_tab: gr.Tab
+    tag_helper_pos: TagGroupHelper
+    tag_helper_neg: TagGroupHelper
+    bottom_bar: BottomBar
+    livelog_viewer: LiveLog
+    ALL_UI_COMPONENTS: Dict[str, Any] = field(default_factory=dict)
+
+    def _get_ui_inputs_and_outputs(self):
+        """Internal helper to reconstruct UI input/output lists when needed."""
+
+        ui_inputs = {
+            "Restorer Sheet": self.restorer_sheet,
+            "Restorer Sheet SUPIR Advanced": self.restorer_sheet_supir_advanced,
+            "Upscaler Sheet": self.upscaler_sheet,
+            "Upscaler Sheet SUPIR Advanced": self.upscaler_sheet_supir_advanced,
+            "Image Restore Engine": self.restorer_engine,
+            "Image Upscale Engine": self.upscaler_engine,
+            "Image Restore Model": self.restorer_model,
+            "Image Upscale Model": self.upscaler_model,
+            "VAE Model": self.vae_model,
+            "Image Restore Sampler": self.restorer_sampler,
+            "Image Upscale Sampler": self.upscaler_sampler,
+            "Input Image": self.input_image,
+            "Image Restore - Prompt method": self.res_prompt_method,
+            "Image Restore - Prompt 1": self.res_prompt,
+            "Image Restore - Prompt 2": self.res_prompt_2,
+            "Image Restore - Negative prompt": self.res_negative_prompt,
+            "Enable Face Restoration": self.preview_restoration_mask_chk,
+            "Mask Prompt": self.restoration_mask_prompt,
+            "Image Upscale - Prompt method": self.ups_prompt_method,
+            "Image Upscale - Prompt 1": self.ups_prompt,
+            "Image Upscale - Prompt 2": self.ups_prompt_2,
+            "Image Upscale - Negative prompt": self.ups_negative_prompt,
+        }
+        output_fields = [*ui_inputs.copy().values()]
+        ui_inputs.pop("Input Image", None)
+        return ui_inputs, output_fields
+
+
+def get_initial_supir_advanced_values():
+    """Helper to provide initial default values to the UI component."""
+    initial_supir_advanced_settings = SUPIRAdvanced_Config()
+    initial_supir_advanced_settings.cross_up_block_0_stage1.sft_active = False
+    initial_supir_advanced_settings.cross_up_block_1_stage1.sft_active = False
+    return initial_supir_advanced_settings
+
+
+def create_ui_components(uidata: UIData) -> UIComponents:
+    """
+    Builds and returns a dictionary of UI components.
+    This function MUST be called from within a `gr.Blocks()` context.
+    """
+
+    html_injector = HTMLInjector()
+    flyout_visible = gr.State(False)
+    active_anchor_id = gr.State(None)
+    js_data_bridge = gr.Textbox(visible=False, elem_id="js_data_bridge")
+    total_inference_steps = gr.State(0)
+    gr.Markdown(
+        """
+        <div align="center">
+        
+        # SUP Toolbox App Demo
+        
+        > **Note:** This is a demonstration version with limited features.
+        > The **Face Restoration** and **Auto Caption Generation** features are disabled in this online demo
+        > to ensure stability and reduce resource usage. For access to all features, please run the
+        > [full application locally](https://github.com/DEVAIEXP/sup-toolbox-app).
+        
+        </div>
+        """
+    )
+    with gr.Row():
+        with TopBar(width="30%", height=80, bring_to_front=True, rounded_borders=True):
+            with gr.Row():
+                run_btn = gr.Button(f"{uidata.process_symbol} Run Process", variant="primary", elem_id="run-button")
+                cancel_btn = gr.Button(
+                    f"{uidata.stop_symbol} Cancel",
+                    variant="stop",
+                    elem_id="cancel-button",
+                    visible=False,
+                )
+
+        with gr.Sidebar(width=360):
+            with gr.Column(elem_classes=["flyout-context-area"], min_width=250):
+                gr.Markdown("### Preset Selection")
+                with gr.Row():
+                    preset_name = TextboxPlus(
+                        elem_id="preset_name",
+                        label="Preset name",
+                        help="Name of the preset to be saved or loaded",
+                    )
+                    presets = DropdownPlus(
+                        elem_id="presets",
+                        label="Presets",
+                        interactive=True,
+                        choices=uidata.PRESETS_LIST,
+                        value=uidata.config.latest_preset,
+                        help="Select a preset to load",
+                    )
+                with gr.Row():
+                    save_preset_btn = gr.Button(
+                        f"{uidata.save_symbol} Save preset",
+                        variant="primary",
+                        elem_id="save_preset",
+                    )
+                    load_preset_btn = gr.Button(f"{uidata.download_symbol} Load preset", elem_id="load_preset")
+                with gr.Row():
+                    gr.Markdown("### Engine Selection")
+                    restorer_engine = DropdownPlus(
+                        elem_id="restorer_engine",
+                        label="Image Restore Engine",
+                        choices=uidata.RESTORER_ENGINE_CHOICES,
+                        value="SUPIR",
+                        help="Select the image restoration engine to be used",
+                    )
+                    upscaler_engine = DropdownPlus(
+                        elem_id="upscaler_engine",
+                        label="Image Upscale Engine",
+                        choices=uidata.UPSCALER_ENGINE_CHOICES,
+                        value="None",
+                        help="Select the image upscaling engine to be used",
+                    )
+                    gr.Markdown("### Model Selection")
+                    restorer_model = DropdownPlus(
+                        elem_id="restorer_model",
+                        label="Image Restore Model",
+                        choices=uidata.MODEL_CHOICES,
+                        value=uidata.MODEL_CHOICES[0] if uidata.MODEL_CHOICES else None,
+                        elem_classes=["custom-dropdown"],
+                        help="Select the model to be used for the restoration engine",
+                    )
+                    upscaler_model = DropdownPlus(
+                        elem_id="upscaler_model",
+                        label="Image Upscale Model",
+                        choices=uidata.MODEL_CHOICES,
+                        value=uidata.MODEL_CHOICES[0] if uidata.MODEL_CHOICES else None,
+                        elem_classes=["custom-dropdown"],
+                        help="Select the model to be used for the upscaling engine",
+                    )
+                    vae_model = gr.Dropdown(
+                        elem_id="vae_model",
+                        label="VAE Model (Optional)",
+                        choices=uidata.VAE_CHOICES,
+                        value="Default",
+                    )
+                gr.Markdown("### Sampler Selection")
+                with gr.Accordion(open=False, label="Create/Choose Sampler", elem_id="sampler-accordion"):
+                    with gr.Group(elem_classes=["group"]):
+                        with gr.Row(elem_classes=["fake-input-container", "no-border-dropdown"]):
+                            restorer_sampler = DropdownPlus(
+                                elem_id="restorer_sampler",
+                                label="Image Restore Sampler",
+                                choices=uidata.SAMPLER_SUPIR_LIST,
+                                value="Euler",
+                                help="Select the sampler to be used for the restoration engine",
+                            )
+                            restorer_sampler_ear_btn = ButtonPlus(
+                                f"{uidata.engine_symbol}",
+                                elem_id="restorer_sampler_ear_btn",
+                                scale=1,
+                                elem_classes=["integrated-ear-btn"],
+                                help="Click to open advanced settings...",
+                            )
+                        with gr.Row(elem_classes=["fake-input-container", "no-border-dropdown"]):
+                            upscaler_sampler = DropdownPlus(
+                                elem_id="upscaler_sampler",
+                                label="Image Upscale Sampler",
+                                choices=uidata.SAMPLER_OTHERS_LIST,
+                                value="Euler",
+                                help="Select the sampler to be used for the upscaling engine",
+                            )
+                            upscaler_sampler_ear_btn = ButtonPlus(
+                                f"{uidata.engine_symbol}",
+                                elem_id="upscaler_sampler_ear_btn",
+                                scale=1,
+                                elem_classes=["integrated-ear-btn"],
+                                help="Click to open advanced settings...",
+                            )
+            with gr.Column(elem_id="flyout_property_sheet_panel", elem_classes=["flyout-source-hidden"]):
+                flyout_property_sheet_close_btn = gr.Button("×", elem_classes=["flyout-close-btn"])
+                flyout_sheet = PropertySheet(
+                    elem_id="flyout_sheet",
+                    visible=True,
+                    container=False,
+                    label="Settings",
+                    show_group_name_only_one=False,
+                    disable_accordion=True,
+                )
+
+        with gr.Tabs() as main_tabs:
+            with gr.TabItem(f"{uidata.process_symbol} Process", id="process-tab"):
+                with gr.Row():
+                    with gr.Column(scale=3):
+                        with gr.Row():
+                            input_image = ImageMeta(
+                                elem_id="input_image",
+                                type="filepath",
+                                label="Input Image",
+                                height=500,
+                                width=600,
+                                popup_metadata_width=600,
+                                popup_metadata_height=500,
+                                only_custom_metadata=False,
+                            )
+                            result_slider = gr.ImageSlider(
+                                elem_id="result_slider",
+                                label="Result Comparison",
+                                show_label=True,
+                                height=500,
+                            )
+
+                        with gr.Accordion("Engine Configurations", open=True) as ec_accordion:
+                            with gr.Tabs() as config_tabs:
+                                with gr.TabItem("Restoration", id=0, visible=False, elem_id="res-tab") as restorer_tab:
+                                    res_prompt_method = gr.Dropdown(
+                                        elem_id="restorer_prompt_method",
+                                        label="Prompt Method",
+                                        choices=uidata.PROMPT_METHODS,
+                                        value=uidata.PROMPT_METHODS[1],
+                                        info="Method used to generate prompt embedding",
+                                    )
+                                    with gr.Group(elem_classes=["group"]):
+                                        with gr.Row(
+                                            elem_classes=[
+                                                "fake-input-container",
+                                                "no-border-dropdown",
+                                                "row-form-size-2",
+                                            ]
+                                        ):
+                                            res_prompt = gr.Textbox(
+                                                elem_id="restorer_prompt_1",
+                                                label="Prompt",
+                                                lines=3,
+                                                info="Your positive prompt",
+                                                value="Direct flash photography. Three (30-year-old men:1.1), (all black hair:1.2). Left man: (black t-shirt:1.1) with white text 'Road Kill Cafe' and in his right forearm has distinct (dark tribal tattoo:1.2).Their hands has clearly defined fingers and distinct outlines. A (plaster interior wall: 1.1) on the left.",
+                                            )
+                                            res_prompt_generate_btn = ButtonPlus(
+                                                value=f"{uidata.caption_symbol}",
+                                                elem_id="res_prompt_generate_btn",
+                                                elem_classes=["integrated-ear-btn"],
+                                                help="Click to auto generate the initial caption...",
+                                                visible=False
+                                            )
+                                    res_prompt_2 = gr.Textbox(
+                                        elem_id="restorer_prompt_2",
+                                        label="Prompt 2",
+                                        lines=2,
+                                        info="Your positive prompt complement",
+                                        value="Extremely detailed faces, flawless natural skin texture, skin pore detailing, 4k, 8k, clean image, no noise, shot on Fujifilm Superia 400, sharp focus, faithful colors.",
+                                    )
+                                    res_tokenizer_pos = TokenizerTextBox(
+                                        elem_id="restorer_tokenizer_prompt",
+                                        label="Positive Tokenizer",
+                                        hide_input=True,
+                                        model="Xenova/clip-vit-large-patch14",
+                                    )
+                                    res_negative_prompt = gr.Textbox(
+                                        elem_id="restorer_negative_prompt",
+                                        label="Negative Prompt",
+                                        lines=3,
+                                        info="Specify what you doesn't want to see",
+                                        value="low-res, disfigured, analog artifacts, smudged, animate, (out of focus:1.2), catchlights, over-smooth, extra eyes, worst quality, unreal engine, art, aberrations, surreal, pastel drawing, (tattoo patterns on walls:1.4), tatto patterns on skin, text on walls, green wall, grainy wall texture, harsh lighting, (tribal patterns on clothing text:1.3), tattoo on chest, dead eyes, deformed fingers, undistinct fingers outlines",
+                                    )
+                                    res_tokenizer_neg = TokenizerTextBox(
+                                        elem_id="restorer_tokenizer_negative_prompt",
+                                        label="Negative Tokenizer",
+                                        hide_input=True,
+                                        model="Xenova/clip-vit-large-patch14",
+                                    )
+                                    with gr.Accordion("Face Restoration", open=False, visible=False):
+                                        preview_restoration_mask_chk = gr.Checkbox(
+                                            elem_id="use_restoration_mask",
+                                            label="Enable Face Restoration",
+                                            value=False,
+                                        )
+                                        with gr.Row(
+                                            elem_classes=[
+                                                "fake-input-container",
+                                                "no-border-dropdown",
+                                                "row-form-size",
+                                            ]
+                                        ):
+                                            restoration_mask_prompt = gr.Textbox(
+                                                elem_id="restoration_mask_prompt",
+                                                label="Mask prompt",
+                                                placeholder="head",
+                                                value="head",
+                                                interactive=False,
+                                            )
+                                            preview_restoration_mask_btn = ButtonPlus(
+                                                value=f"{uidata.preview_symbol}",
+                                                elem_id="preview_restoration_mask_btn",
+                                                elem_classes=["integrated-ear-btn"],
+                                                interactive=False,
+                                                help="Click to open preview restoration mask...",
+                                            )
+                                    with gr.Column(
+                                        elem_id="flyout_restoration_mask_panel",
+                                        elem_classes=["flyout-source-hidden"],
+                                    ):
+                                        flyout_restoration_image_close_btn = gr.Button("×", elem_classes=["flyout-close-btn"])
+                                        restoration_mask = gr.Image(
+                                            elem_id="flyout_restoration_mask",
+                                            label="Masking preview",
+                                            type="pil",
+                                            interactive=False,
+                                            show_download_button=False,
+                                            show_share_button=False,
+                                            height=300,
+                                        )
+                                    restorer_sheet = PropertySheet(
+                                        elem_id="restorer_settings",
+                                        label="Restoration Settings",
+                                        value=SUPIR_Config(),
+                                    )
+                                    restorer_sheet_supir_advanced = PropertySheet(
+                                        elem_id="restorer_supir_advanced_settings",
+                                        label="SFT Injection Settings (Experimental parameters for advanced users)",
+                                        open=False,
+                                        value=get_initial_supir_advanced_values(),
+                                    )
+
+                                with gr.TabItem("Upscaling", id=1, visible=False, elem_id="ups-tab") as upscaler_tab:
+                                    ups_prompt_method = gr.Dropdown(
+                                        elem_id="upscaler_prompt_method",
+                                        label="Prompt Method",
+                                        choices=uidata.PROMPT_METHODS,
+                                        value=uidata.PROMPT_METHODS[1],
+                                        info="Method used to generate prompt embedding",
+                                    )
+                                    with gr.Group(elem_classes=["group"]):
+                                        with gr.Row(
+                                            elem_classes=[
+                                                "fake-input-container",
+                                                "no-border-dropdown",
+                                                "row-form-size-2",
+                                            ]
+                                        ):
+                                            ups_prompt = gr.Textbox(
+                                                elem_id="upscaler_prompt_1",
+                                                label="Prompt",
+                                                lines=3,
+                                                info="Your positive prompt",
+                                            )
+                                            ups_prompt_generate_btn = ButtonPlus(
+                                                value=f"{uidata.caption_symbol}",
+                                                elem_id="ups_prompt_generate_btn",
+                                                elem_classes=["integrated-ear-btn"],
+                                                help="Click to auto generate the initial caption...",
+                                                visible=False
+                                            )
+                                    ups_prompt_2 = gr.Textbox(
+                                        elem_id="upscaler_prompt_2",
+                                        label="Prompt 2",
+                                        lines=2,
+                                        info="Your positive prompt complement",
+                                    )
+                                    ups_tokenizer_pos = TokenizerTextBox(
+                                        elem_id="upscaler_tokenizer_prompt",
+                                        label="Positive Tokenizer",
+                                        hide_input=True,
+                                        model="Xenova/clip-vit-large-patch14",
+                                    )
+                                    ups_negative_prompt = gr.Textbox(
+                                        elem_id="upscaler_negative_prompt",
+                                        label="Negative Prompt",
+                                        lines=3,
+                                        info="Specify what you doesn't want to see",
+                                    )
+                                    ups_tokenizer_neg = TokenizerTextBox(
+                                        elem_id="upscaler_tokenizer_negative_prompt",
+                                        label="Negative Tokenizer",
+                                        hide_input=True,
+                                        model="Xenova/clip-vit-large-patch14",
+                                    )
+                                    upscaler_sheet = PropertySheet(
+                                        elem_id="upscaler_settings",
+                                        label="Upscaling Settings",
+                                        value=ControlNetTile_Config(),
+                                    )
+                                    upscaler_sheet_supir_advanced = PropertySheet(
+                                        elem_id="upscaler_supir_advanced_settings",
+                                        label="SFT Injection Settings (Experimental parameters for advanced users)",
+                                        open=False,
+                                        value=get_initial_supir_advanced_values(),
+                                    )
+
+            with gr.TabItem(f"{uidata.folder_symbol} Generated") as generated_tab:
+                with gr.Row(equal_height=True, elem_classes="media-gallery-row"):
+                    with gr.Column(scale=0, min_width=300):
+                        folder_explorer = FolderExplorer(
+                            label="Select a Folder",
+                            root_dir=uidata.config.output_dir,
+                            value=uidata.config.output_dir,
+                        )
+                    with gr.Column(scale=2):
+                        generated_image_viewer = MediaGallery(
+                            label="Media in Folder",
+                            columns=4,
+                            height="auto",
+                            preview=False,
+                            show_download_button=False,
+                            only_custom_metadata=False,
+                            popup_metadata_width="40%",
+                        )
+
+            with gr.Tab(f"{uidata.settings_symbol} Settings", interactive=False) as settings_tab:
+                settings_sheet = PropertySheet(elem_id="settings_sheet", label="General Setting", value=AppSettings())
+                with gr.Row(elem_id="settings-buttons-row"):
+                    reset_settings_btn = gr.Button(
+                        value=f"{uidata.refresh_symbol} Load defaults and restart",
+                        elem_id="reset_settings_button",
+                    )
+                    save_settings_btn = gr.Button(
+                        value=f"{uidata.save_symbol} Save and restart",
+                        elem_id="save_settings_button",
+                    )
+
+            with gr.Tab(f"{uidata.about_symbol} About") as about_tab:
+                CreditsPanel(
+                    elem_classes="credit-panel",
+                    height="auto",
+                    credits=CREDIT_LIST,
+                    licenses=LICENSE_PATHS,
+                    effect="scroll",
+                    speed=60.0,
+                    base_font_size=1.5,
+                    intro_title="SUP Toolbox",
+                    intro_subtitle="Scaling-UP Application",
+                    sidebar_position="right",
+                    logo_path=None,
+                    show_logo=True,
+                    show_licenses=True,
+                    show_credits=True,
+                    logo_position="center",
+                    logo_sizing="resize",
+                    logo_width="200px",
+                    logo_height="100px",
+                    scroll_background_color="#000000",
+                    scroll_title_color="#FFFFFF",
+                    scroll_name_color="#FFFFFF",
+                    scroll_section_title_color="#FFFFFF",
+                    layout_style="two-column",
+                    title_uppercase=True,
+                    name_uppercase=True,
+                    section_title_uppercase=True,
+                    swap_font_sizes_on_two_column=True,
+                    scroll_logo_path="assets/devaixp_logo-white.png",
+                    scroll_logo_height="200px",
+                )
+
+        with gr.Sidebar(position="right", width=360):
+            gr.Markdown("### Helpers")
+            tag_helper_pos = TagGroupHelper(
+                elem_id="tag_helper_pos",
+                label="Positive Keywords",
+                value=dict(TAG_DATA_POSITIVE),
+                target_textbox_id="upscaler_prompt_1",
+                separator=", ",
+                width=290,
+                font_size_scale=90,
+                interactive=True,
+                open=False,
+            )
+            tag_helper_neg = TagGroupHelper(
+                elem_id="tag_helper_neg",
+                label="Negative Keywords",
+                value=dict(TAG_DATA_NEGATIVE),
+                target_textbox_id="upscaler_negative_prompt",
+                separator=", ",
+                width=290,
+                font_size_scale=90,
+                interactive=True,
+                open=False,
+            )
+
+        with BottomBar("Status", bring_to_front=False, height=340, open=False, rounded_borders=True) as bottom_bar:
+            livelog_viewer = LiveLog(label="Process output", height=250, autoscroll=True, line_numbers=False)
+
+    all_ui_components_for_presets = {
+        restorer_engine.elem_id: restorer_engine,
+        upscaler_engine.elem_id: upscaler_engine,
+        restorer_model.elem_id: restorer_model,
+        upscaler_model.elem_id: upscaler_model,
+        vae_model.elem_id: vae_model,
+        restorer_sampler.elem_id: restorer_sampler,
+        upscaler_sampler.elem_id: upscaler_sampler,
+        res_prompt_method.elem_id: res_prompt_method,
+        res_prompt.elem_id: res_prompt,
+        res_prompt_2.elem_id: res_prompt_2,
+        res_negative_prompt.elem_id: res_negative_prompt,
+        preview_restoration_mask_chk.elem_id: preview_restoration_mask_chk,
+        restoration_mask_prompt.elem_id: restoration_mask_prompt,
+        restorer_sheet.elem_id: restorer_sheet,
+        restorer_sheet_supir_advanced.elem_id: restorer_sheet_supir_advanced,
+        ups_prompt_method.elem_id: ups_prompt_method,
+        ups_prompt.elem_id: ups_prompt,
+        ups_prompt_2.elem_id: ups_prompt_2,
+        ups_negative_prompt.elem_id: ups_negative_prompt,
+        upscaler_sheet.elem_id: upscaler_sheet,
+        upscaler_sheet_supir_advanced.elem_id: upscaler_sheet_supir_advanced,
+    }
+
+    components_dict = {
+        "html_injector": html_injector,
+        "flyout_visible": flyout_visible,
+        "active_anchor_id": active_anchor_id,
+        "js_data_bridge": js_data_bridge,
+        "total_inference_steps": total_inference_steps,
+        "run_btn": run_btn,
+        "cancel_btn": cancel_btn,
+        "preset_name": preset_name,
+        "presets": presets,
+        "save_preset_btn": save_preset_btn,
+        "load_preset_btn": load_preset_btn,
+        "restorer_engine": restorer_engine,
+        "upscaler_engine": upscaler_engine,
+        "restorer_model": restorer_model,
+        "upscaler_model": upscaler_model,
+        "vae_model": vae_model,
+        "restorer_sampler": restorer_sampler,
+        "restorer_sampler_ear_btn": restorer_sampler_ear_btn,
+        "upscaler_sampler": upscaler_sampler,
+        "upscaler_sampler_ear_btn": upscaler_sampler_ear_btn,
+        "flyout_property_sheet_close_btn": flyout_property_sheet_close_btn,
+        "flyout_sheet": flyout_sheet,
+        "main_tabs": main_tabs,
+        "input_image": input_image,
+        "result_slider": result_slider,
+        "ec_accordion": ec_accordion,
+        "config_tabs": config_tabs,
+        "restorer_tab": restorer_tab,
+        "res_prompt_method": res_prompt_method,
+        "res_prompt": res_prompt,
+        "res_prompt_generate_btn": res_prompt_generate_btn,
+        "res_prompt_2": res_prompt_2,
+        "res_tokenizer_pos": res_tokenizer_pos,
+        "res_negative_prompt": res_negative_prompt,
+        "res_tokenizer_neg": res_tokenizer_neg,
+        "preview_restoration_mask_chk": preview_restoration_mask_chk,
+        "restoration_mask_prompt": restoration_mask_prompt,
+        "preview_restoration_mask_btn": preview_restoration_mask_btn,
+        "flyout_restoration_image_close_btn": flyout_restoration_image_close_btn,
+        "restoration_mask": restoration_mask,
+        "restorer_sheet": restorer_sheet,
+        "restorer_sheet_supir_advanced": restorer_sheet_supir_advanced,
+        "upscaler_tab": upscaler_tab,
+        "ups_prompt_method": ups_prompt_method,
+        "ups_prompt": ups_prompt,
+        "ups_prompt_generate_btn": ups_prompt_generate_btn,
+        "ups_prompt_2": ups_prompt_2,
+        "ups_tokenizer_pos": ups_tokenizer_pos,
+        "ups_negative_prompt": ups_negative_prompt,
+        "ups_tokenizer_neg": ups_tokenizer_neg,
+        "upscaler_sheet": upscaler_sheet,
+        "upscaler_sheet_supir_advanced": upscaler_sheet_supir_advanced,
+        "generated_tab": generated_tab,
+        "folder_explorer": folder_explorer,
+        "generated_image_viewer": generated_image_viewer,
+        "settings_tab": settings_tab,
+        "settings_sheet": settings_sheet,
+        "reset_settings_btn": reset_settings_btn,
+        "save_settings_btn": save_settings_btn,
+        "about_tab": about_tab,
+        "tag_helper_pos": tag_helper_pos,
+        "tag_helper_neg": tag_helper_neg,
+        "bottom_bar": bottom_bar,
+        "livelog_viewer": livelog_viewer,
+        "ALL_UI_COMPONENTS": all_ui_components_for_presets,
+    }
+
+    return components_dict

ui/ui_state.py

@@ -0,0 +1,38 @@
+# Copyright 2025 The DEVAIEXP Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dataclasses import dataclass, field
+from threading import Event
+
+# Forward reference for type hint to avoid circular import
+from typing import Any
+
+from ui.ui_data import UIData
+
+
+@dataclass
+class AppState:
+    """A container for the shared state of the Gradio application."""
+
+    uidata: UIData
+    cancel_event: Event = field(default_factory=Event)
+
+    # All other state variables that were previously global
+    input_image_path: str = None
+    restorer_config_class: Any = None    
+    restorer_supir_advanced_config_class: Any = None
+    upscaler_config_class: Any = None
+    upscaler_supir_advanced_config_class: Any = None
+    restorer_engine_selected: str = "SUPIR"  # Initial value
+    upscaler_engine_selected: str = "None"  # Initial value

ui/util/dataclass_helpers.py

@@ -0,0 +1,300 @@
+# Copyright 2025 The DEVAIEXP Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import dataclasses
+import functools
+from dataclasses import Field
+from typing import Any, Dict, List, Tuple, Type
+
+from typing_extensions import Literal
+
+
+# General Helper Functions
+def get_nested_attr(obj: Any, path: str, default: Any = None) -> Any:
+    """
+    Accesses a nested attribute from an object using 'dot notation'.
+
+    Returns a default value if any attribute in the chain is missing or if
+    the object itself is None.
+
+    Args:
+        obj:
+            The root object.
+        path:
+            A string path like "parent.child.attribute".
+        default:
+            The value to return if the path is not found.
+
+    Returns:
+        The value of the nested attribute or the default value.
+    """
+    try:
+        return functools.reduce(getattr, path.split("."), obj)
+    except AttributeError:
+        return default
+
+
+def _set_nested_dict_value(d: dict, path: str, value: Any):
+    """
+    Sets a value in a nested dictionary using 'dot notation'.
+
+    Args:
+        d:
+            The dictionary to modify.
+        path:
+            A string path like "parent.child.key".
+        value:
+            The new value to set.
+    """
+    keys = path.split(".")
+    for key in keys[:-1]:
+        d = d.setdefault(key, {})
+    d[keys[-1]] = value
+
+
+def get_nested_field(dc_type: Type, path: str) -> Field:
+    """
+    Retrieves the dataclasses.Field object for a nested attribute.
+
+    Args:
+        dc_type:
+            The top-level dataclass type.
+        path:
+            A string path like "parent.child.field_name".
+
+    Returns:
+        The dataclasses.Field definition object.
+    """
+    parts = path.split(".")
+    current_type = dc_type
+    for i, part in enumerate(parts):
+        field_info = current_type.__dataclass_fields__[part]
+        if i == len(parts) - 1:
+            return field_info
+        current_type = field_info.type
+    raise KeyError(f"Field path '{path}' could not be fully resolved in {dc_type}.")
+
+
+def get_nested_parent_and_field(obj: object, path: str) -> Tuple[object, str]:
+    """
+    Navigates a nested object path and returns the parent object and the
+    final field name.
+
+    Example: for path "general.sampler.seed", returns (sampler_object, "seed").
+
+    Args:
+        obj:
+            The root object to navigate.
+        path:
+            A dot-separated string path.
+
+    Returns:
+        A tuple containing the direct parent object and the final field name.
+    """
+    parts = path.split(".")
+    parent = obj
+    for part in parts[:-1]:
+        parent = getattr(parent, part)
+    return parent, parts[-1]
+
+
+# Dataclass Instantiation Helper
+def dataclass_from_dict(data_class: Type, data: dict) -> Any:
+    """
+    Recursively constructs a dataclass instance from a dictionary.
+
+    This helper is essential for creating a dataclass instance from dictionary
+    data, especially when dealing with nested dataclasses. It correctly
+    handles nested structures by recursively calling itself.
+
+    Args:
+        data_class:
+            The dataclass type to instantiate (e.g., `AppSettings`).
+        data:
+            A dictionary containing the data to populate the instance.
+            Keys should correspond to field names in the dataclass.
+
+    Returns:
+        An instance of `data_class` populated with data from the dictionary.
+    """
+    field_names = {f.name for f in dataclasses.fields(data_class)}
+    filtered_data = {k: v for k, v in data.items() if k in field_names}
+
+    for f in dataclasses.fields(data_class):
+        field_name = f.name
+        field_type = f.type
+
+        if field_name in filtered_data and dataclasses.is_dataclass(field_type):
+            if isinstance(filtered_data[field_name], dict):
+                nested_instance = dataclass_from_dict(field_type, filtered_data[field_name])
+                filtered_data[field_name] = nested_instance
+
+    return data_class(**filtered_data)
+
+
+# The Core Engine for Dynamic Dataclass Reconstruction
+def _rebuild_dataclass_recursively(dc_type: Type, path: str, new_field: Field) -> Type:
+    """
+    Internal function to recursively rebuild a nested dataclass structure.
+
+    It replaces an entire target field definition, allowing for changes to
+    any part of the field (type, metadata, default value, etc.).
+
+    Args:
+        dc_type:
+            The current dataclass type to rebuild.
+        path:
+            The remaining dot-separated path to the target field.
+        new_field:
+            The complete new dataclasses.Field object to insert.
+
+    Returns:
+        A new, dynamically created dataclass type with the updated structure.
+    """
+    parts = path.split(".")
+    field_to_change = parts[0]
+
+    if len(parts) == 1:
+        new_fields_spec = []
+        for f in dataclasses.fields(dc_type):
+            if f.name == field_to_change:
+                new_spec = (f.name, new_field.type, new_field)
+                new_fields_spec.append(new_spec)
+            else:
+                new_fields_spec.append((f.name, f.type, f))
+        class_name = f"Updated_{dc_type.__name__.rpartition('_')[-1]}"
+        return dataclasses.make_dataclass(
+            class_name,
+            new_fields_spec,
+            bases=dc_type.__bases__,
+        )
+    else:
+        nested_dc_type = dc_type.__dataclass_fields__[field_to_change].type
+        remaining_path = ".".join(parts[1:])
+        rebuilt_nested_type = _rebuild_dataclass_recursively(nested_dc_type, remaining_path, new_field)
+
+        new_parent_fields_spec = []
+        for f in dataclasses.fields(dc_type):
+            if f.name == field_to_change:
+                new_parent_nested_field = dataclasses.field(default_factory=f.default_factory, metadata=f.metadata, init=f.init)
+                new_spec = (f.name, rebuilt_nested_type, new_parent_nested_field)
+                new_parent_fields_spec.append(new_spec)
+            else:
+                new_parent_fields_spec.append((f.name, f.type, f))
+        class_name = f"Updated_{dc_type.__name__.rpartition('_')[-1]}"
+        return dataclasses.make_dataclass(class_name, new_parent_fields_spec, bases=dc_type.__bases__)
+
+
+def apply_dynamic_changes(dc_instance: object, rules: dict) -> object:
+    """
+    Processes a dataclass instance against a set of UI rules.
+
+    This version ensures consistency by always rebuilding the dataclass
+    instance if any rule that modifies the class structure (like changing
+    options or visibility) is present. This prevents state inconsistencies
+    within the Gradio UI lifecycle.
+
+    Args:
+        dc_instance:
+            The source dataclass instance.
+        rules:
+            A dictionary containing the UI rules.
+
+    Returns:
+        A new dataclass instance of a dynamically created type, with all
+        structural rules applied.
+    """
+    current_dc = dc_instance
+    actions_to_process: List[Dict] = []
+
+    # Part 1: Gather dynamic actions based on current field values
+    if "dynamic_dependencies" in rules:
+        for modifier_path, rule_group in rules["dynamic_dependencies"].items():
+            modifier_value = get_nested_attr(current_dc, modifier_path)
+            for action in rule_group.get("actions", []):
+                mapping = action.get("mapping", {})
+                if modifier_value in mapping:
+                    outcome = mapping[modifier_value]
+                    actions_to_process.append({**action, "outcome": outcome})
+
+    # Part 2: Gather unconditional "on_load" actions
+    if "on_load_actions" in rules:
+        actions_to_process.extend(rules["on_load_actions"])
+
+    # Part 3: Process all gathered actions
+    for action in actions_to_process:
+        action_type = action.get("type")
+        target_path = action.get("target_field_path")
+        outcome = action.get("outcome")  # Will be None for on_load_actions
+
+        if not all([action_type, target_path]):
+            continue
+
+        target_field_info = get_nested_field(type(current_dc), target_path)
+
+        # Handle actions that require rebuilding the dataclass
+        if action_type in ["update_options", "update_visibility"]:
+            new_field_type = target_field_info.type
+            new_metadata = dict(target_field_info.metadata)
+
+            if action_type == "update_options":
+                new_options = outcome.get("options", [])
+                new_field_type = Literal[tuple(new_options)] if new_options else str
+
+            elif action_type == "update_visibility":
+                is_visible = action.get("visible")
+                if is_visible is not None:
+                    new_metadata["visible"] = is_visible
+
+            # Create the new field definition based on the changes
+            new_field = dataclasses.field(
+                default=target_field_info.default,
+                default_factory=target_field_info.default_factory,
+                init=target_field_info.init,
+                repr=target_field_info.repr,
+                hash=target_field_info.hash,
+                compare=target_field_info.compare,
+                metadata=new_metadata,
+            )
+            new_field.type = new_field_type
+            new_field.name = target_field_info.name
+
+            # Rebuild the dataclass and replace the current instance
+            NewDcClass = _rebuild_dataclass_recursively(type(current_dc), target_path, new_field)
+            values_dict = dataclasses.asdict(current_dc)
+
+            # Correct the value if it became invalid after an `update_options` action
+            if action_type == "update_options":
+                current_value = get_nested_attr(current_dc, target_path)
+                new_options = outcome.get("options", [])
+                new_default = outcome.get("new_default")
+                should_update = current_value not in new_options or (new_default is not None and current_value != new_default)
+                if should_update:
+                    value_to_set = new_default if new_default is not None else (new_options[0] if new_options else None)
+                    if value_to_set is not None:
+                        _set_nested_dict_value(values_dict, target_path, value_to_set)
+
+            # The `current_dc` instance is replaced. The next loop iteration
+            # will operate on this newly created instance.
+            current_dc = dataclass_from_dict(NewDcClass, values_dict)
+
+        # Handle actions that modify the instance directly
+        elif action_type == "set_value":
+            new_value = outcome
+            current_value = get_nested_attr(current_dc, target_path)
+            if new_value != current_value:
+                parent_obj, field_name = get_nested_parent_and_field(current_dc, target_path)
+                setattr(parent_obj, field_name, new_value)
+
+    return current_dc