feat: OneTrainerWeb — Electron + React frontend with FastAPI bridge

Replaces the customtkinter desktop GUI with an Electron + React web
frontend, connected to the existing Python training backend via a
FastAPI bridge. Existing backend code (modules/, scripts/,
training_presets/) is unchanged — the bridge communicates only
through the TrainCallbacks / TrainCommands interface.

Adds:
- web/gui/     Electron + React + Vite + Tailwind (TypeScript strict)
- web/backend/ FastAPI bridge importing existing modules/ directly
- web/scripts/ AST-based generators that emit TypeScript types and
               UI schema from the Python config/enum/CTk sources
- start-web-ui.{bat,sh}, install/update script integration
- .github/workflows/web-ui-lint.yml (ESLint + Prettier check on PRs)
- .pre-commit-config.yaml hooks: ESLint shim + hardcoded-options guard

Also folds in a follow-up pass porting general code-quality
improvements (bugfixes, refactors, small UX additions) from a parallel
fork's more advanced branch, while deliberately excluding that branch's
new features (job queue, DPO training, cloud/RunPod, validation
checker, OFT merging, distillation, bucket analysis) and the
field-override binding system those features depend on:

- Drop the allowed_roots allow-list from validate_path(); presets.py
  sandboxes its own paths via base_match() instead.
- main.py reuses paths.py's PROJECT_ROOT instead of duplicating the
  project-root/sys.path bootstrap.
- Add real tensorboard process management (/tensorboard/launch, /stop).
- Add /system/cache/status, /system/cache/clear, and Scalene-backed
  profiling endpoints (dump-stacks, toggle).
- Simplify custom-sample field copying to sample_config.from_dict(...).
- Let /concepts GET/PUT target a path override, and add
  POST /concepts/save-caption for the mask editor's caption panel.
- Let /tools/convert accept per-conversion quantization overrides.
- start_training() accepts a pre-built config; fix the always-on
  tensorboard subprocess handle not being a class attribute (a fresh
  TrainerService instance could otherwise lose track of an
  already-running subprocess).
- _safe_literal_eval() in generate_types.py fixes optimizer defaults
  using float('inf') silently extracting as {} (ast.literal_eval
  rejects Call nodes); the OptimizerKeyDetail type union is now
  derived from actual data.
- _sanitize_default() in generate_ui_schema.py encodes
  Infinity/-Infinity/NaN as strings so the browser's JSON.parse
  doesn't choke on them.
- FormEntry no longer clobbers what the user is typing when the parsed
  value echoes back through config (e.g. "-0" -> "0" mid-keystroke).
- ModalBase gains size="full" and closeOnEscape.
- TopBar's preset dropdown is now a custom menu supporting inline
  deletion of user presets.
- SampleParamsModal gains prompt/negative-prompt fields and a seed
  reroll.
- MaskEditorPage gains a caption editor panel with arrow-key
  navigation.
- BottomBar gains a tensorboard launch button.
- Fixed default-value/config bugs: ConceptsPage's resolution_override
  ("" -> "512"), and SamplingPage's hardcoded image-format dropdown
  now sources from the generated ImageFormatValues enum.
- Vite's dev server already falls back off a busy port 5173, but
  Electron's main process had no way to discover which port it landed
  on; added a Vite plugin that writes the resolved port to
  .vite-port and an Electron-side poller that reads it, replacing the
  hardcoded dev-server URL and a wait-on-a-fixed-port step that would
  have hung forever if 5173 was taken. Verified with a standalone
  script (web/gui/scripts/verify-port-fallback.mjs, run via
  `npm run verify:port-fallback`).

Claude-Session: https://claude.ai/code/session_019pHqnjipbR4G8eGRQcemTq

Author: BitcrushedHeart

.github/workflows/web-ui-lint.yml

@@ -0,0 +1,26 @@
+name: web-ui-lint
+
+on:
+  pull_request:
+    paths:
+      - "web/gui/**"
+      - ".github/workflows/web-ui-lint.yml"
+  push:
+    branches: [master, Webui]
+    paths:
+      - "web/gui/**"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web/gui
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm install --no-audit --no-fund
+      - run: npm run lint
+      - run: npm run format:check

.gitignore

@@ -20,6 +20,8 @@ debug*.py
 config.json
 secrets.json
 *.zip
+.env*
+!.env.example
 
 # environments
 /.venv*
@@ -38,3 +40,14 @@ pixi.toml
 train.bat
 debug_report.log
 config_diff.txt
+
+# Web UI
+web/gui/dist/
+web/gui/release/
+web/gui/node_modules/
+web/gui/public/ui-schema.json
+web/gui/src/renderer/types/generated/
+web/gui/.vite-port
+web/backend/__pycache__/
+web/backend/**/__pycache__/
+web/backend/generated/

.pre-commit-config.yaml

@@ -16,10 +16,25 @@ repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   rev: v0.15.17
   hooks:
-    # Run the Ruff linter, but not the formatter.
     - id: ruff
       args: ["--fix"]
       types_or: [ python, pyi, jupyter ]
 
+- repo: local
+  hooks:
+    - id: eslint
+      name: ESLint (frontend)
+      entry: python -m web.scripts.run_eslint
+      language: system
+      files: '^web/gui/.*\.(ts|tsx)$'
+      pass_filenames: false
+
+    - id: check-hardcoded-dropdown-options
+      name: No hardcoded <Select options> outside types/generated/
+      entry: python -m web.scripts.check_hardcoded_options
+      language: system
+      files: '^web/gui/src/renderer/.*\.(ts|tsx)$'
+      pass_filenames: false
+
 ci:
   autofix_prs: false

install.bat

@@ -273,6 +273,38 @@ if errorlevel 1 (
     echo %GRN%CUDA is available.%RESET%
 )
 
+rem 7) Generate UI schema and build web UI
+echo.
+echo %CYAN%Generating UI schema...%RESET%
+python -m web.scripts.generate_ui_schema
+if errorlevel 1 (
+  echo %YEL%WARNING: UI schema generation failed. Using existing schema.%RESET%
+)
+
+echo.
+where node >NUL 2>NUL
+if errorlevel 1 (
+  echo %YEL%Node.js not found. Skipping web UI build.%RESET%
+  echo To use the web UI, install Node.js from https://nodejs.org/ and re-run install.bat
+) else (
+  echo %CYAN%Building web UI...%RESET%
+  pushd web\gui
+  call npm install
+  if errorlevel 1 (
+    echo %YEL%WARNING: npm install failed. Web UI will not be available.%RESET%
+    popd
+    goto :skip_web_build
+  )
+  call npm run build:electron
+  if errorlevel 1 (
+    echo %YEL%WARNING: Web UI build failed. Web UI will not be available.%RESET%
+  ) else (
+    echo %GRN%Web UI built successfully.%RESET%
+  )
+  popd
+)
+:skip_web_build
+
 echo.
 echo %GRN%**** Install successful^^! ****%RESET%
 echo.

lib.include.sh

@@ -444,4 +444,39 @@ function prepare_runtime_environment {
     else
         install_requirements_in_active_env_if_necessary
     fi
+
+    # Regenerate the web UI schema and rebuild the Electron bundle when possible.
+    print "Generating UI schema..."
+    if ! run_python_in_active_env -m web.scripts.generate_ui_schema; then
+        print_warning "UI schema generation failed. Using existing schema."
+    fi
+
+    build_web_ui_if_available
+}
+
+# Builds the Electron+React web UI when Node.js is available.
+# During "install" runs it builds unconditionally; otherwise only rebuilds
+# when a previously built bundle is detected, so regular headless users
+# are not forced to install Node.js.
+function build_web_ui_if_available {
+    if ! command -v node &> /dev/null; then
+        print "Node.js not found. Skipping web UI build."
+        print "To use the web UI, install Node.js from https://nodejs.org/"
+        return 0
+    fi
+
+    local gui_dir="${SCRIPT_DIR}/web/gui"
+    local dist_marker="${gui_dir}/dist/main/main/index.cjs"
+
+    if [[ -f "${dist_marker}" ]] || [[ "${1:-}" == "install" ]]; then
+        print "Building web UI..."
+        (
+            cd "${gui_dir}"
+            npm install || { print_warning "npm install failed. Web UI may be stale."; return 0; }
+            npm run build:electron || { print_warning "Web UI build failed. Web UI may be stale."; return 0; }
+            print "Web UI built successfully."
+        )
+    else
+        print "Web UI not previously built. Run start-web-ui.sh to build and launch."
+    fi
 }

start-web-ui.bat

@@ -0,0 +1,80 @@
+@echo off
+cd /d "%~dp0"
+
+set "OT_DEV="
+for %%a in (%*) do (
+    if "%%a"=="--dev" set "OT_DEV=1"
+)
+
+if not exist "scripts\train_ui.py" (
+    echo Error: train_ui.py does not exist, you have done something very wrong. Reclone the repository.
+    goto :end
+)
+
+if not defined PYTHON (
+    where python >NUL 2>NUL
+    if errorlevel 1 (
+        echo Error: Python is not installed or not in PATH
+        goto :end
+    )
+    set PYTHON=python
+)
+if not defined VENV_DIR (set "VENV_DIR=%~dp0venv")
+
+:check_venv
+dir "%VENV_DIR%" > NUL 2> NUL
+if not errorlevel 1 goto :activate_venv
+echo venv not found, please run install.bat first
+goto :end
+
+:activate_venv
+echo activating venv %VENV_DIR%
+if not exist "%VENV_DIR%\Scripts\python.exe" (
+    echo Error: Python executable not found in virtual environment
+    goto :end
+)
+set PYTHON="%VENV_DIR%\Scripts\python.exe" -X utf8
+echo Using Python %PYTHON%
+
+REM Disable Xet (buggy) - https://github.com/Nerogar/OneTrainer/issues/949
+if not defined HF_HUB_DISABLE_XET (
+    set "HF_HUB_DISABLE_XET=1"
+)
+
+:check_python_version
+%PYTHON% --version
+if errorlevel 1 (
+    echo Error: Failed to get Python version
+    goto :end
+)
+%PYTHON% "%~dp0scripts\util\version_check.py" 3.10 3.14 2>&1
+if errorlevel 1 (
+    goto :end
+)
+
+:check_node
+where node >NUL 2>NUL
+if errorlevel 1 (
+    echo Error: Node.js is not installed or not in PATH
+    echo Please install Node.js from https://nodejs.org/
+    goto :end
+)
+
+:check_gui_built
+if not exist "web\gui\dist\main\main\index.cjs" (
+    echo Error: Web GUI has not been built yet.
+    echo Please run install.bat or update.bat first to build the web UI.
+    goto :end
+)
+
+:launch
+echo Starting OneTrainer Web UI...
+cd web\gui
+call npx electron .
+cd ..\..
+if errorlevel 1 (
+    echo Error: Web UI exited with code %ERRORLEVEL%
+)
+
+:end
+pause

start-web-ui.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+set -e
+
+source "${BASH_SOURCE[0]%/*}/lib.include.sh"
+
+for arg in "$@"; do
+    if [[ "$arg" == "--dev" ]]; then
+        export OT_DEV=1
+    fi
+done
+
+# Xet is buggy - https://github.com/Nerogar/OneTrainer/issues/949
+if [[ -z "${HF_HUB_DISABLE_XET+x}" ]]; then
+    export HF_HUB_DISABLE_XET=1
+fi
+
+prepare_runtime_environment
+
+if ! command -v node &> /dev/null; then
+    echo "Error: Node.js is not installed or not in PATH"
+    echo "Please install Node.js from https://nodejs.org/"
+    exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if [[ ! -f "$SCRIPT_DIR/web/gui/dist/main/main/index.cjs" ]]; then
+    echo "Error: Web GUI has not been built yet."
+    echo "Please run install.sh or update.sh first to build the web UI."
+    exit 1
+fi
+
+echo "Starting OneTrainer Web UI..."
+cd "$SCRIPT_DIR/web/gui"
+npx electron .

update.bat

@@ -141,6 +141,41 @@ if errorlevel 1 (
     goto :end_error
 )
 
+REM Regenerate UI schema and rebuild web UI if previously built
+echo.
+echo Generating UI schema...
+"%PYTHON%" -m web.scripts.generate_ui_schema
+if errorlevel 1 (
+  echo WARNING: UI schema generation failed. Using existing schema.
+)
+REM Reset errorlevel so schema failure does not affect exit code
+cmd /c "exit /b 0"
+
+where node >NUL 2>NUL
+if errorlevel 1 (
+  echo Node.js not found. Skipping web UI rebuild.
+) else (
+  if exist "web\gui\dist\main\main\index.cjs" (
+    echo Rebuilding web UI...
+    pushd web\gui
+    call npm install
+    if errorlevel 1 (
+      echo WARNING: npm install failed. Web UI may be stale.
+      popd
+      goto :end_success
+    )
+    call npm run build:electron
+    if errorlevel 1 (
+      echo WARNING: Web UI rebuild failed. Web UI may be stale.
+    ) else (
+      echo Web UI rebuilt successfully.
+    )
+    popd
+  ) else (
+    echo Web UI not previously built. Run start-web-ui.bat to launch.
+  )
+)
+
 :end_success
 echo.
 echo ***********