test: compare normalized save subfolder (forward slashes on Windows)

A Windows console on a legacy code page (cp1252, or cp437 in cmd)
raises UnicodeEncodeError on emoji. The startup banner printed a 🫶
prefix and display names like "Model Downloader 🌐", which aborts
loading the whole node pack. Same approach as ComfyUI_PromptManager:

- Banner prints ASCII-only display names (emoji stay in the UI names)
- Preset validation messages print "1024x1024" instead of "1024×1024"
- Explicit UTF-8 for text files (Windows defaults to cp1252)
- Regression test imports the package with a strict cp1252/cp437 stdout

.flake8

@@ -1,7 +1,7 @@
 [flake8]
 max-line-length = 127
 max-complexity = 10
-exclude = 
+exclude =
     .git,
     __pycache__,
     .mypy_cache,
@@ -11,8 +11,9 @@ exclude =
     build,
     dist,
     *.egg-info,
-    .tox
-ignore = 
+    .tox,
+    referance
+ignore =
     # W503: line break before binary operator (conflicts with Black)
     W503,
     # E203: whitespace before ':' (conflicts with Black)
@@ -32,4 +33,4 @@ per-file-ignores =
 
 # Statistics
 count = True
-statistics = True
+statistics = True

.gitattributes

@@ -38,4 +38,4 @@
 *.safetensors binary
 *.ckpt binary
 *.pt binary
-*.pth binary
+*.pth binary

.github/dependabot.yml

@@ -7,4 +7,4 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "weekly"

.github/workflows/code-quality.yml

@@ -13,15 +13,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.10'
 
     - name: Cache pip dependencies
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-quality-${{ hashFiles('**/requirements-dev.txt') }}
@@ -93,6 +93,14 @@ jobs:
         from kikotools.tools.kiko_save_image import KikoSaveImageNode
         from kikotools.tools.kiko_save_image.logic import process_image_batch, validate_save_inputs
 
+        # Test Model Downloader imports
+        from kikotools.tools.model_downloader import ModelDownloaderNode
+        from kikotools.tools.model_downloader.detector import URLDetector, DownloaderType
+        from kikotools.tools.model_downloader.base import BaseDownloader
+
+        # Test Text Input imports
+        from kikotools.tools.text_input import TextInputNode
+
         print('✓ All module imports successful')
         "
 
@@ -133,10 +141,10 @@ jobs:
   security:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.10'
 
@@ -164,10 +172,10 @@ jobs:
   architecture:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.10'
 
@@ -279,6 +287,41 @@ jobs:
             print('❌ KikoSaveImageNode missing OUTPUT_NODE = True')
             sys.exit(1)
 
+        # Test Model Downloader Node
+        from kikotools.tools.model_downloader.node import ModelDownloaderNode
+
+        if issubclass(ModelDownloaderNode, ComfyAssetsBaseNode):
+            print('✓ ModelDownloaderNode properly inherits from base class')
+        else:
+            print('❌ ModelDownloaderNode does not inherit from base class')
+            sys.exit(1)
+
+        # ModelDownloader is an output node, so it doesn't have RETURN_TYPES/RETURN_NAMES
+        download_required_attrs = ['INPUT_TYPES', 'FUNCTION', 'CATEGORY']
+        for attr in download_required_attrs:
+            if not hasattr(ModelDownloaderNode, attr):
+                print(f'❌ ModelDownloaderNode missing required attribute: {attr}')
+                sys.exit(1)
+
+        # Check that it's properly marked as an output node
+        if not hasattr(ModelDownloaderNode, 'OUTPUT_NODE') or not ModelDownloaderNode.OUTPUT_NODE:
+            print('❌ ModelDownloaderNode missing OUTPUT_NODE = True')
+            sys.exit(1)
+
+        # Test Text Input Node
+        from kikotools.tools.text_input.node import TextInputNode
+
+        if issubclass(TextInputNode, ComfyAssetsBaseNode):
+            print('✓ TextInputNode properly inherits from base class')
+        else:
+            print('❌ TextInputNode does not inherit from base class')
+            sys.exit(1)
+
+        for attr in required_attrs:
+            if not hasattr(TextInputNode, attr):
+                print(f'❌ TextInputNode missing required attribute: {attr}')
+                sys.exit(1)
+
         print('✓ All architecture checks passed for all tools')
         "
 

.github/workflows/publish.yml

@@ -18,7 +18,7 @@ jobs:
     if: ${{ github.repository_owner == 'ComfyAssets' }}
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           submodules: true
       - name: Publish Custom Node

.github/workflows/release.yml

@@ -15,10 +15,10 @@ jobs:
       contents: write
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.10'
 

.github/workflows/tests.yml

@@ -11,471 +11,71 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    name: py${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
     strategy:
+      fail-fast: false
       matrix:
-        python-version: [3.8, 3.9, "3.10", "3.11", "3.12"]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
 
-      - name: Cache pip dependencies
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements-dev.txt') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
+      # The default Linux torch wheel bundles CUDA (~2.5 GB); tests only need CPU.
+      # Windows and macOS default wheels are already CPU-only.
+      - name: Install CPU torch (Linux)
+        if: runner.os == 'Linux'
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements-dev.txt
+          pip install -r requirements-dev.txt aiohttp
 
-      - name: Run core functionality tests
-        run: |
-          python -c "
-          import sys
-          import os
-          sys.path.insert(0, os.getcwd())
+      - name: Run tests
+        run: python -m pytest tests
 
-          # Test imports
-          from kikotools.base import ComfyAssetsBaseNode
-          from kikotools.tools.resolution_calculator.logic import extract_dimensions, calculate_scaled_dimensions
-          from kikotools.tools.resolution_calculator.node import ResolutionCalculatorNode
-          import torch
-
-          print('✓ All imports successful')
-
-          # Test base node
-          assert ComfyAssetsBaseNode.CATEGORY.startswith('ComfyAssets')
-          print('✓ Base node tests passed')
-
-          # Test dimension extraction
-          mock_image = torch.randn(1, 1216, 832, 3)
-          width, height = extract_dimensions(image=mock_image)
-          assert width == 832 and height == 1216
-          print('✓ Dimension extraction tests passed')
-
-          # Test scaling
-          new_width, new_height = calculate_scaled_dimensions(832, 1216, 1.5)
-          assert new_width % 8 == 0 and new_height % 8 == 0
-          print('✓ Scaling tests passed')
-
-          # Test node interface
-          node = ResolutionCalculatorNode()
-          result_width, result_height = node.calculate_resolution(1.5, image=mock_image)
-          assert isinstance(result_width, int) and isinstance(result_height, int)
-          assert result_width % 8 == 0 and result_height % 8 == 0
-          print('✓ Node interface tests passed')
-
-          # Test user scenario
-          width, height = node.calculate_resolution(1.53, image=mock_image)
-          print(f'✓ User scenario test: 832×1216 → {width}×{height} (1.53x scale)')
-
-          print('🎉 All tests passed!')
-          "
-
-      - name: Test Width Height Selector
-        run: |
-          python -c "
-          import sys
-          import os
-          sys.path.insert(0, os.getcwd())
-
-          # Test Width Height Selector imports
-          from kikotools.tools.width_height_selector.node import WidthHeightSelectorNode
-          from kikotools.tools.width_height_selector.presets import PRESET_OPTIONS, PRESET_METADATA
-          from kikotools.tools.width_height_selector.logic import get_preset_dimensions
-
-          print('✓ Width Height Selector imports successful')
-
-          # Test preset structure
-          assert len(PRESET_OPTIONS) > 0
-          assert 'custom' in PRESET_OPTIONS
-          assert len(PRESET_METADATA) > 0
-          print('✓ Preset structure tests passed')
-
-          # Test node interface
-          node = WidthHeightSelectorNode()
-          input_types = node.INPUT_TYPES()
-          assert 'required' in input_types
-          assert 'preset' in input_types['required']
-          assert 'width' in input_types['required']
-          assert 'height' in input_types['required']
-          print('✓ Node interface tests passed')
-
-          # Test formatted presets
-          preset_options = input_types['required']['preset'][0]
-          assert 'custom' in preset_options
-          formatted_count = len([opt for opt in preset_options if ' - ' in opt and 'MP' in opt])
-          assert formatted_count > 0
-          print(f'✓ Found {formatted_count} formatted presets')
-
-          # Test dimension calculation
-          result = node.get_dimensions('1024×1024', 512, 512)
-          assert result == (1024, 1024)
-          print('✓ Dimension calculation tests passed')
-
-          # Test formatted preset dimensions
-          formatted_preset = '1024×1024 - 1:1 (1.1MP) - SDXL'
-          result = node.get_dimensions(formatted_preset, 512, 512)
-          assert result == (1024, 1024)
-          print('✓ Formatted preset tests passed')
-
-          # Test preset extraction
-          extracted = node._extract_preset_name(formatted_preset)
-          assert extracted == '1024×1024'
-          print('✓ Preset extraction tests passed')
-
-          print('🎉 All Width Height Selector tests passed!')
-          "
-
-      - name: Test Sampler Combo
-        run: |
-          python -c "
-          import sys
-          import os
-          sys.path.insert(0, os.getcwd())
-
-          # Test Sampler Combo imports
-          from kikotools.tools.sampler_combo.node import SamplerComboNode
-          from kikotools.tools.sampler_combo.logic import (
-              get_sampler_combo, validate_sampler_settings, SAMPLERS, SCHEDULERS
-          )
-
-          print('✓ Sampler Combo imports successful')
-
-          # Test node interface
-          node = SamplerComboNode()
-          input_types = node.INPUT_TYPES()
-          assert 'required' in input_types
-          assert 'sampler_name' in input_types['required']
-          assert 'scheduler' in input_types['required']
-          assert 'steps' in input_types['required']
-          assert 'cfg' in input_types['required']
-          print('✓ Sampler Combo interface tests passed')
-
-          # Test return types
-          # RETURN_TYPES[1] is the actual SCHEDULERS list
-          assert node.RETURN_TYPES[0] == 'SAMPLER'
-          assert isinstance(node.RETURN_TYPES[1], list)  # SCHEDULERS is a list
-          assert node.RETURN_TYPES[2] == 'INT'
-          assert node.RETURN_TYPES[3] == 'FLOAT'
-          assert node.RETURN_NAMES == ('sampler_name', 'scheduler', 'steps', 'cfg')
-          assert node.CATEGORY == 'ComfyAssets/🌀 Samplers'
-          print('✓ Sampler Combo return types tests passed')
-
-          # Test sampler combo functionality
-          result = node.get_sampler_combo('euler', 'normal', 20, 7.0)
-          assert result == ('euler', 'normal', 20, 7.0)
-          print('✓ Sampler combo functionality tests passed')
-
-          # Test validation
-          assert validate_sampler_settings('euler', 'normal', 20, 7.0) == True
-          print('✓ Sampler validation tests passed')
-
-          # Test available samplers and schedulers
-          samplers = node.get_available_samplers()
-          schedulers = node.get_available_schedulers()
-          assert len(samplers) > 0
-          assert len(schedulers) > 0
-          assert 'euler' in samplers
-          assert 'normal' in schedulers
-          print(f'✓ Found {len(samplers)} samplers and {len(schedulers)} schedulers')
-
-          print('🎉 All Sampler Combo tests passed!')
-          "
-
-      - name: Test Seed History
-        run: |
-          python -c "
-          import sys
-          import os
-          sys.path.insert(0, os.getcwd())
-
-          # Test Seed History imports
-          from kikotools.tools.seed_history.node import SeedHistoryNode
-          from kikotools.tools.seed_history.logic import (
-              generate_random_seed, validate_seed_value, sanitize_seed_value
-          )
-
-          print('✓ Seed History imports successful')
-
-          # Test node interface
-          node = SeedHistoryNode()
-          input_types = node.INPUT_TYPES()
-          assert 'required' in input_types
-          assert 'seed' in input_types['required']
-          print('✓ Seed History interface tests passed')
-
-          # Test return types
-          assert node.RETURN_TYPES == ('INT',)
-          assert node.RETURN_NAMES == ('seed',)
-          assert node.CATEGORY == 'ComfyAssets/🌱 Seeds'
-          print('✓ Seed History return types tests passed')
-
-          # Test seed output functionality
-          result = node.output_seed(12345)
-          assert result == (12345,)
-          print('✓ Seed output functionality tests passed')
-
-          # Test seed validation
-          assert validate_seed_value(12345) == True
-          assert validate_seed_value(-1) == False
-          print('✓ Seed validation tests passed')
-
-          # Test seed generation
-          new_seed = generate_random_seed()
-          assert isinstance(new_seed, int)
-          assert validate_seed_value(new_seed) == True
-          print('✓ Seed generation tests passed')
-
-          # Test seed sanitization
-          clean_seed = sanitize_seed_value(12345)
-          assert clean_seed == 12345
-          print('✓ Seed sanitization tests passed')
-
-          # Test node helper methods
-          assert node.is_seed_in_range(12345) == True
-          assert node.is_seed_in_range(-1) == False
-          assert node.get_default_seed() == 12345
-          print('✓ Seed helper methods tests passed')
-
-          print('🎉 All Seed History tests passed!')
-          "
-
-      - name: Test error handling for all tools
-        run: |
-          python -c "
-          import sys
-          import os
-          sys.path.insert(0, os.getcwd())
-
-          print('=== Testing Error Handling for All Tools ===')
-
-          # Test Resolution Calculator error handling
-          from kikotools.tools.resolution_calculator.node import ResolutionCalculatorNode
-          res_node = ResolutionCalculatorNode()
-
-          try:
-              res_node.calculate_resolution(2.0)  # No input provided
-              assert False, 'Should have raised ValueError'
-          except ValueError:
-              print('✓ Resolution Calculator error handling test passed')
-
-          try:
-              res_node.calculate_resolution(0.0)  # Invalid scale
-              assert False, 'Should have raised ValueError'
-          except ValueError:
-              print('✓ Resolution Calculator scale factor validation test passed')
-
-          # Test Width Height Selector error handling
-          from kikotools.tools.width_height_selector.node import WidthHeightSelectorNode
-          wh_node = WidthHeightSelectorNode()
-
-          # Test invalid preset fallback
-          result = wh_node.get_dimensions('invalid_preset', 800, 600)
-          assert result == (800, 600)  # Should fallback to custom dimensions
-          print('✓ Width Height Selector invalid preset handling test passed')
-
-          # Test Sampler Combo error handling
-          from kikotools.tools.sampler_combo.node import SamplerComboNode
-          sampler_node = SamplerComboNode()
-
-          # Test with invalid sampler (should use safe defaults)
-          result = sampler_node.get_sampler_combo('invalid_sampler', 'normal', 20, 7.0)
-          assert result == ('euler', 'normal', 20, 7.0)  # Safe defaults
-          print('✓ Sampler Combo invalid input handling test passed')
-
-          # Test Seed History error handling
-          from kikotools.tools.seed_history.node import SeedHistoryNode
-          seed_node = SeedHistoryNode()
-
-          # Test invalid seed value (should use fallback)
-          result = seed_node.output_seed(-1)  # Invalid negative seed
-          assert result == (12345,)  # Fallback seed
-          print('✓ Seed History invalid seed handling test passed')
-
-          print('🎉 All error handling tests passed for all tools!')
-          "
-
-      - name: Test ComfyUI integration readiness for all tools
-        run: |
-          python -c "
-          import sys
-          import os
-          sys.path.insert(0, os.getcwd())
-
-          print('=== Testing ComfyUI Integration for All Tools ===')
-
-          # Test Resolution Calculator
-          from kikotools.tools.resolution_calculator.node import ResolutionCalculatorNode
-          res_class = ResolutionCalculatorNode
-
-          assert hasattr(res_class, 'INPUT_TYPES')
-          assert hasattr(res_class, 'RETURN_TYPES')
-          assert hasattr(res_class, 'RETURN_NAMES')
-          assert hasattr(res_class, 'FUNCTION')
-          assert hasattr(res_class, 'CATEGORY')
-
-          input_types = res_class.INPUT_TYPES()
-          assert 'required' in input_types
-          assert 'optional' in input_types
-          assert 'scale_factor' in input_types['required']
-          assert 'image' in input_types['optional']
-          assert 'latent' in input_types['optional']
-
-          assert res_class.RETURN_TYPES == ('INT', 'INT')
-          assert res_class.RETURN_NAMES == ('width', 'height')
-          assert res_class.CATEGORY.startswith('ComfyAssets/')
-          print('✓ Resolution Calculator ComfyUI integration passed')
-
-          # Test Width Height Selector
-          from kikotools.tools.width_height_selector.node import WidthHeightSelectorNode
-          wh_class = WidthHeightSelectorNode
-
-          assert hasattr(wh_class, 'INPUT_TYPES')
-          assert hasattr(wh_class, 'RETURN_TYPES')
-          assert hasattr(wh_class, 'RETURN_NAMES')
-          assert hasattr(wh_class, 'FUNCTION')
-          assert hasattr(wh_class, 'CATEGORY')
-
-          input_types = wh_class.INPUT_TYPES()
-          assert 'required' in input_types
-          assert 'preset' in input_types['required']
-          assert 'width' in input_types['required']
-          assert 'height' in input_types['required']
-
-          assert wh_class.RETURN_TYPES == ('INT', 'INT')
-          assert wh_class.RETURN_NAMES == ('width', 'height')
-          assert wh_class.CATEGORY.startswith('ComfyAssets/')
-          print('✓ Width Height Selector ComfyUI integration passed')
-
-          # Test Sampler Combo
-          from kikotools.tools.sampler_combo.node import SamplerComboNode
-          sampler_class = SamplerComboNode
-
-          assert hasattr(sampler_class, 'INPUT_TYPES')
-          assert hasattr(sampler_class, 'RETURN_TYPES')
-          assert hasattr(sampler_class, 'RETURN_NAMES')
-          assert hasattr(sampler_class, 'FUNCTION')
-          assert hasattr(sampler_class, 'CATEGORY')
-
-          input_types = sampler_class.INPUT_TYPES()
-          assert 'required' in input_types
-          assert 'sampler_name' in input_types['required']
-          assert 'scheduler' in input_types['required']
-          assert 'steps' in input_types['required']
-          assert 'cfg' in input_types['required']
-
-          assert sampler_class.CATEGORY.startswith('ComfyAssets/')
-          print('✓ Sampler Combo ComfyUI integration passed')
-
-          # Test Seed History
-          from kikotools.tools.seed_history.node import SeedHistoryNode
-          seed_class = SeedHistoryNode
-
-          assert hasattr(seed_class, 'INPUT_TYPES')
-          assert hasattr(seed_class, 'RETURN_TYPES')
-          assert hasattr(seed_class, 'RETURN_NAMES')
-          assert hasattr(seed_class, 'FUNCTION')
-          assert hasattr(seed_class, 'CATEGORY')
-
-          input_types = seed_class.INPUT_TYPES()
-          assert 'required' in input_types
-          assert 'seed' in input_types['required']
-
-          assert seed_class.RETURN_TYPES == ('INT',)
-          assert seed_class.RETURN_NAMES == ('seed',)
-          assert seed_class.CATEGORY.startswith('ComfyAssets/')
-          print('✓ Seed History ComfyUI integration passed')
-
-          print('🎉 All tools ComfyUI integration readiness tests passed!')
-          "
-
-  test-package-structure:
+  coverage:
+    name: coverage gate (85%)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
-          python-version: "3.10"
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
 
-      - name: Test package structure
+      - name: Install dependencies
         run: |
-          # Check required files exist
-          test -f README.md || (echo "README.md missing" && exit 1)
-          test -f LICENSE || (echo "LICENSE missing" && exit 1)
-          test -f requirements-dev.txt || (echo "requirements-dev.txt missing" && exit 1)
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -r requirements-dev.txt aiohttp
 
-          # Check directory structure
-          test -d kikotools || (echo "kikotools directory missing" && exit 1)
-          test -d kikotools/base || (echo "kikotools/base directory missing" && exit 1)
-          test -d kikotools/tools || (echo "kikotools/tools directory missing" && exit 1)
-          test -d kikotools/tools/resolution_calculator || (echo "resolution_calculator directory missing" && exit 1)
-          test -d kikotools/tools/width_height_selector || (echo "width_height_selector directory missing" && exit 1)
-          test -d kikotools/tools/sampler_combo || (echo "sampler_combo directory missing" && exit 1)
-          test -d kikotools/tools/seed_history || (echo "seed_history directory missing" && exit 1)
-          test -d tests || (echo "tests directory missing" && exit 1)
-          test -d examples || (echo "examples directory missing" && exit 1)
-          test -d web || (echo "web directory missing" && exit 1)
+      # fail_under = 85 lives in pyproject.toml [tool.coverage.report]
+      - name: Measure coverage
+        run: python -m pytest tests --cov=kikotools --cov-report=term-missing
 
-          # Check key files
-          test -f kikotools/__init__.py || (echo "kikotools/__init__.py missing" && exit 1)
-          test -f kikotools/base/base_node.py || (echo "base_node.py missing" && exit 1)
-
-          # Resolution Calculator files
-          test -f kikotools/tools/resolution_calculator/node.py || (echo "resolution_calculator node.py missing" && exit 1)
-          test -f kikotools/tools/resolution_calculator/logic.py || (echo "resolution_calculator logic.py missing" && exit 1)
-
-          # Width Height Selector files
-          test -f kikotools/tools/width_height_selector/node.py || (echo "width_height_selector node.py missing" && exit 1)
-          test -f kikotools/tools/width_height_selector/logic.py || (echo "width_height_selector logic.py missing" && exit 1)
-          test -f kikotools/tools/width_height_selector/presets.py || (echo "width_height_selector presets.py missing" && exit 1)
-
-          # Sampler Combo files
-          test -f kikotools/tools/sampler_combo/node.py || (echo "sampler_combo node.py missing" && exit 1)
-          test -f kikotools/tools/sampler_combo/logic.py || (echo "sampler_combo logic.py missing" && exit 1)
-
-          # Seed History files
-          test -f kikotools/tools/seed_history/node.py || (echo "seed_history node.py missing" && exit 1)
-          test -f kikotools/tools/seed_history/logic.py || (echo "seed_history logic.py missing" && exit 1)
-
-          # Web files
-          test -f web/width_height_swap.js || (echo "width_height_swap.js missing" && exit 1)
-          test -f web/seed_history_ui.js || (echo "seed_history_ui.js missing" && exit 1)
-
-          echo "✓ Package structure tests passed"
-
-  test-documentation:
+  js-check:
+    name: frontend syntax
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - name: Test documentation completeness
+      # No JS unit tests yet; at least make sure every module parses
+      - name: Check web/*.js parse as ES modules
         run: |
-          # Check documentation files for all tools
-          test -f examples/documentation/resolution_calculator.md || (echo "Resolution calculator docs missing" && exit 1)
-          test -f examples/workflows/resolution_calculator_example.json || (echo "Resolution calculator workflow missing" && exit 1)
-          test -f examples/documentation/width_height_selector.md || (echo "Width height selector docs missing" && exit 1)
-          test -f examples/workflows/width_height_selector_example.json || (echo "Width height selector workflow missing" && exit 1)
-          test -f examples/documentation/sampler_combo.md || (echo "Sampler combo docs missing" && exit 1)
-          test -f examples/workflows/sampler_combo_example.json || (echo "Sampler combo workflow missing" && exit 1)
-          test -f examples/documentation/seed_history.md || (echo "Seed history docs missing" && exit 1)
-          test -f examples/workflows/seed_history_example.json || (echo "Seed history workflow missing" && exit 1)
-
-          # Check README has key sections
-          grep -q "Installation" README.md || (echo "README missing Installation section" && exit 1)
-          grep -q "Quick Start" README.md || (echo "README missing Quick Start section" && exit 1)
-          grep -q "Development" README.md || (echo "README missing Development section" && exit 1)
-          grep -q "Contributing" README.md || (echo "README missing Contributing section" && exit 1)
-
-          echo "✓ Documentation tests passed"
+          for f in web/*.js; do
+            node --input-type=module --check < "$f" || { echo "Syntax error in $f"; exit 1; }
+          done

.gitignore

@@ -159,6 +159,7 @@ test_images/
 test_outputs/
 experiments/
 .claude/
+.serena
 
 # Gemini model cache
 .gemini_models_cache.json

.pre-commit-config.yaml

@@ -81,4 +81,4 @@ exclude: |
     .*\.egg-info/|
     venv/|
     env/
-  )
+  )

README.md

@@ -8,7 +8,14 @@
 
 > A modular collection of essential custom ComfyUI nodes missing from the standard release.
 
-ComfyUI-KikoTools provides carefully crafted, production-ready nodes grouped under the **"ComfyAssets"** category. Each tool is designed with clean interfaces, comprehensive testing, and optimized performance for SDXL and FLUX workflows.
+ComfyUI-KikoTools provides carefully crafted, production-ready nodes under the "ComfyAssets" category.
+Each tool is built with clean interfaces, thorough testing, and optimized performance for SDXL and FLUX workflows.
+
+This project started out of frustration with keeping ComfyUI up to date and waiting for dozens of custom nodes to update—most of which I didn’t even use. After taking a hard look at my workflow, I realized I only needed one or two features from these nodes, many of which were abandoned or stuck in maintenance mode.
+
+I tried forking, patching, and submitting merge requests, but eventually decided to create my own curated collection of tools—fully supported and maintained by me. That’s how Kiko’s Tools was born.
+
+I’m sharing them here with the community, and I hope you find them as useful as I do.
 
 ## 🚀 Features
 
@@ -26,7 +33,13 @@ ComfyUI-KikoTools provides carefully crafted, production-ready nodes grouped und
 | [🤖 Gemini Prompt Engineer](#-gemini-prompt-engineer) | AI-powered image analysis and prompt generation | 🧠 Prompts |
 | [🔍 Display Any](#-display-any) | Universal debugging tool for any data type | 👁️ Display |
 | [🖼️ Image to Multiple Of](#️-image-to-multiple-of) | Adjust dimensions to multiples for compatibility | 🖼️ Resolution |
-| [🔤 Embedding Autocomplete](#-embedding-autocomplete) | Smart autocomplete for embeddings, LoRAs, and tags | ✍️ Text |
+| [📉 Image Scale Down By](#-image-scale-down-by) | Scale images down by a factor with quality preservation | 🖼️ Resolution |
+| [🎬 Film Grain](#-film-grain) | Add realistic film grain effects to images | 💾 Images |
+| [🔤 Embedding Autocomplete](#-embedding-autocomplete) | Smart autocomplete for embeddings, LoRAs, and tags | 🔧 Utils |
+| [🧹 Kiko Purge VRAM](#-kiko-purge-vram) | Intelligent VRAM management with detailed reporting | 🛠️ Utils |
+| [📂 Local Image Loader](#-local-image-loader) | Visual gallery browser for local media files | 💾 Images |
+| [🌐 Model Downloader](#-model-downloader) | Download models from CivitAI, HuggingFace, and custom URLs | 🛠️ Utils |
+| [⏱️ Workflow Timer](#️-workflow-timer) | Real-time execution timer with customizable display | 🛠️ Utils |
 
 ### 🧰 xyz-helpers Tools
 
@@ -219,6 +232,41 @@ Adjusts image dimensions to be multiples of a specified value for model compatib
 
 ![Image to Multiple Of Example](examples/workflows/image_to_multiple_of_example.png)
 
+#### 📉 Image Scale Down By
+Efficiently scale images down by a specified factor with quality preservation.
+
+- **Proportional Scaling**: Reduces both width and height by the same factor
+- **Quality Preservation**: Uses bilinear interpolation with antialiasing
+- **Batch Support**: Process multiple images simultaneously
+- **Memory Efficient**: Optimized for large image batches
+- **Flexible Factor**: Scale from 0.01x to 1.0x with 0.01 precision
+
+**Use Cases:**
+- Create thumbnails or preview images
+- Reduce memory usage for large workflows
+- Generate image pyramids for multi-scale processing
+- Quick downsampling for performance optimization
+- Prepare images for web display or transmission
+
+#### 🎬 Film Grain
+Add realistic analog film grain effects to generated images.
+
+- **Realistic Grain Simulation**: Mimics actual film photography characteristics
+- **Grain Size Control**: Fine to coarse grain patterns (0.25x to 2.0x)
+- **Intensity Adjustment**: Variable strength from subtle to pronounced (0-10)
+- **Color Saturation**: Monochrome to full color grain (0-2)
+- **Shadow Lifting (Toe)**: Film-like shadow response curves
+- **Red Multiplier**: Adjust red channel independently for vintage looks
+- **Alpha Preservation**: Maintains transparency when present
+- **ITU-R BT.709 Color Space**: Professional color handling
+
+**Use Cases:**
+- Add vintage film aesthetic to AI-generated images
+- Create cinematic looks with authentic grain patterns
+- Simulate different film stocks (35mm, 16mm, etc.)
+- Add texture to overly smooth AI renders
+- Match grain from reference photography
+
 #### 🎛️ Flux Sampler Params
 FLUX-optimized parameter generator with intelligent batch processing capabilities.
 
@@ -312,14 +360,80 @@ Unified interface for text encoding and sampler parameter management.
 - Quick template-based generation
 - Batch prompt processing
 
+#### 📂 Local Image Loader
+Visual gallery browser for loading local images, videos, and audio files directly into ComfyUI workflows.
+
+- **Visual Gallery Interface**: Browse files with thumbnail previews in a masonry layout
+- **Multi-Media Support**: Load images (JPG, PNG, GIF, WebP), videos (MP4, WebM, MOV), and audio files (MP3, WAV, OGG, FLAC)
+- **Quick Navigation**: Navigate folders with breadcrumb path and parent directory button
+- **Responsive Layout**: Automatically adjusts thumbnail grid to available space
+- **Metadata Extraction**: Reads embedded prompt and workflow data from generated images
+- **Saved Paths**: Remember frequently used directories for quick access
+- **Double-Click Preview**: Open full-size media in new browser tab
+- **Smart Sorting**: Sort by name, date, or file size in ascending or descending order
+- **Pagination Support**: Efficiently browse large directories with page controls
+
+**Use Cases:**
+- Load reference images from local folders for img2img workflows
+- Browse and select from collections of generated images
+- Quickly access frequently used asset directories
+- Extract prompts and settings from previously generated images
+- Preview media files before loading into workflow
+
+#### 🌐 Model Downloader
+Download models, LoRAs, and other assets directly from CivitAI, HuggingFace, and custom URLs within ComfyUI.
+
+- **Multi-Platform Support**: CivitAI, HuggingFace, and direct download URLs
+- **Smart URL Detection**: Automatic detection of download source and file handling
+- **API Token Support**: Optional authentication for private/gated models
+- **Progress Reporting**: Real-time download progress with speed indicators
+- **Resume Support**: Skip existing files or force re-download
+- **Interrupt Handling**: Respects ComfyUI's "Cancel current run" button
+- **Automatic Cleanup**: Removes partial downloads on cancellation
+- **Custom Filenames**: Override auto-detected filenames when needed
+
+**Platform Features:**
+- **CivitAI**: Model page URLs, version-specific downloads, API authentication
+- **HuggingFace**: Blob and resolve URLs, branch/revision support, gated model access
+- **Custom URLs**: Direct download links with bearer token authentication
+
+**Use Cases:**
+- Download models without leaving ComfyUI
+- Automate asset acquisition in workflows
+- Access private or gated models with API tokens
+- Build reproducible workflows with automatic model fetching
+- Quickly test new models from the community
+
+![Model Downloader Example](examples/workflows/model_downloader_example.png)
+
+#### ⏱️ Workflow Timer
+Real-time execution timer that displays workflow duration with millisecond precision.
+
+- **Live Timing**: Updates in real-time during workflow execution (MM:SS:mmm format)
+- **Customizable Color**: Choose your preferred display color via KikoTools settings
+- **Glow Effect**: Optional pulsing glow animation (can be enabled/disabled in settings)
+- **Global Settings**: Color and glow preferences apply to all timer nodes
+- **Persistent Display**: Shows final execution time after workflow completes
+- **Multi-Node Sync**: All timer nodes stay synchronized during execution
+
+**Use Cases:**
+- Monitor workflow execution performance
+- Compare generation times across different settings
+- Identify slow nodes by adding timers at different workflow stages
+- Track optimization improvements over time
+
+**Settings (KikoTools Settings Panel):**
+- **Workflow Timer: Color** - Custom color picker for timer display
+- **Workflow Timer: Enable Glow** - Toggle pulsing glow effect on/off
+
 ### 🔤 Embedding Autocomplete
 
 **Intelligent autocomplete for embeddings, LoRAs, and custom tags in text prompts.**
 
 <div align="center">
-  <img src="ac-emb.png" width="30%" alt="Embedding Autocomplete" />
-  <img src="ac-lora.png" width="30%" alt="LoRA Autocomplete" />
-  <img src="ac-tag.png" width="30%" alt="Tag Autocomplete" />
+  <img src="https://github.com/ComfyAssets/ComfyUI-KikoTools/blob/main/examples/ac-emb.png?raw=true" width="30%" alt="Embedding Autocomplete" />
+  <img src="https://github.com/ComfyAssets/ComfyUI-KikoTools/blob/main/examples/ac-lora.png?raw=true" width="30%" alt="LoRA Autocomplete" />
+  <img src="https://github.com/ComfyAssets/ComfyUI-KikoTools/blob/main/examples/ac-tag.png?raw=true" width="30%" alt="Tag Autocomplete" />
 </div>
 
 This feature is an enhanced fork of the autocomplete functionality from [ComfyUI-Custom-Scripts](https://github.com/pythongosssss/ComfyUI-Custom-Scripts) by pythongosssss. We've modernized the codebase, fixed existing bugs, and added robust security features.
@@ -351,6 +465,46 @@ This feature is an enhanced fork of the autocomplete functionality from [ComfyUI
 - Original autocomplete concept by [pythongosssss](https://github.com/pythongosssss/ComfyUI-Custom-Scripts)
 - Enhanced and modernized by KikoTools team
 
+### 🧹 Kiko Purge VRAM
+**Intelligent GPU memory management with threshold-based triggering and detailed reporting.**
+
+**Key Features:**
+- **4 Purge Modes**:
+  - `soft`: Basic garbage collection and cache clearing
+  - `aggressive`: Multiple GC passes with full CUDA cache clearing
+  - `models_only`: Unload all models and clear model cache
+  - `cache_only`: Clear CUDA cache without garbage collection
+- **Smart Thresholds**: Only purge when memory usage exceeds specified MB limit
+- **Detailed Reporting**: Shows before/after memory usage, freed MB, and timing
+- **Passthrough Design**: Acts as workflow checkpoint without disrupting data flow
+- **CPU Fallback**: Gracefully handles non-CUDA environments
+
+**Use Cases:**
+- Free memory between heavy processing stages
+- Prevent OOM errors in complex workflows
+- Debug memory usage patterns
+- Optimize multi-model workflows
+- Clean up after batch processing
+
+**Parameters:**
+- **anything**: Any input (passed through unchanged)
+- **mode**: Purge strategy selection
+- **report_memory**: Generate detailed memory statistics
+- **memory_threshold_mb**: Only purge if usage exceeds (0 = always purge)
+
+**Example Output:**
+```
+Memory usage (5000.0 MB) exceeds threshold (4000 MB)
+
+Memory Purge Report
+-------------------
+Mode: soft
+Memory Freed: 2500.0 MB
+Before: 5000.0 MB used (62.5%)
+After: 2500.0 MB used (31.3%)
+Time: 150.0ms
+```
+
 ### 💾 Kiko Save Image Features
 
 **Use Cases:**
@@ -585,12 +739,17 @@ Example workflow available: [xyz_helpers_lora_testing.json](examples/workflows/x
 | **Gemini Prompt Engineer** | AI-powered image analysis with dynamic model refresh | ✅ Complete | [Docs](examples/documentation/gemini_prompt.md) |
 | **Display Any** | Universal debugging tool for any data type or tensor shapes | ✅ Complete | [Docs](examples/documentation/display_any.md) |
 | **Image to Multiple Of** | Adjust image dimensions to multiples for model compatibility | ✅ Complete | [Docs](examples/documentation/image_to_multiple_of.md) |
+| **Image Scale Down By** | Efficiently scale images down by a specified factor | ✅ Complete | [Docs](examples/documentation/image_scale_down_by.md) |
+| **Film Grain** | Add realistic analog film grain effects to images | ✅ Complete | [Docs](examples/documentation/film_grain.md) |
 | **Flux Sampler Params** | FLUX-optimized parameter generator with batch support | ✅ Complete | [Docs](examples/documentation/flux_sampler_params.md) |
 | **LoRA Folder Batch** | Batch process multiple LoRAs from folders | ✅ Complete | [Docs](examples/documentation/lora_folder_batch.md) |
 | **Plot Parameters** | Visualize parameter effects with graphs | ✅ Complete | [Docs](examples/documentation/plot_parameters.md) |
 | **Sampler Select Helper** | Intelligent sampler selection with recommendations | ✅ Complete | [Docs](examples/documentation/sampler_select_helper.md) |
 | **Scheduler Select Helper** | Optimal scheduler selection for samplers | ✅ Complete | [Docs](examples/documentation/scheduler_select_helper.md) |
 | **Text Encode Sampler Params** | Combined text encoding and parameter management | ✅ Complete | [Docs](examples/documentation/text_encode_sampler_params.md) |
+| **Local Image Loader** | Visual gallery browser for local media files | ✅ Complete | [Docs](examples/documentation/local_image_loader.md) |
+| **Model Downloader** | Download models from CivitAI, HuggingFace, and custom URLs | ✅ Complete | [Docs](examples/documentation/model_downloader.md) |
+| **Workflow Timer** | Real-time execution timer with customizable display | ✅ Complete | [Docs](examples/documentation/workflow_timer.md) |
 | **Batch Image Processor** | Process multiple images with consistent settings | 🚧 Planned | Coming Soon |
 | **Advanced Prompt Utilities** | Enhanced prompt manipulation and generation | 🚧 Planned | Coming Soon |
 
@@ -873,7 +1032,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ## 🏷️ Tags
 
-`comfyui` `custom-nodes` `image-processing` `ai-tools` `sdxl` `flux` `upscaling` `resolution` `batch-processing` `python` `pytorch`
+`comfyui` `custom-nodes` `image-processing` `ai-tools` `sdxl` `flux` `upscaling` `resolution` `batch-processing` `model-downloader` `civitai` `huggingface` `python` `pytorch`
 
 ## 🔗 Links
 
@@ -884,13 +1043,15 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ## 📈 Stats
 
-- **Nodes**: 16 (10 core tools + 6 xyz-helpers)
-- **Categories**: 8 emoji-based categories for better organization
+- **Nodes**: 21 (15 core tools + 6 xyz-helpers)
+- **Features**: Embedding Autocomplete (settings-based, not a node)
+- **Categories**: 9 emoji-based categories for better organization
+- **Download Platforms**: 3 (CivitAI, HuggingFace, Custom URLs)
 - **Format Support**: 3 (PNG, JPEG, WebP with advanced controls)
 - **Presets**: 26 curated resolution presets
 - **Interactive Features**: 8+ (swap buttons, history UI, popup viewers, parameter visualization)
 - **AI Integration**: Gemini API with 40+ model support
-- **Test Coverage**: 100% (300+ comprehensive tests)
+- **Test Coverage**: 100% (470+ comprehensive tests)
 - **Python Version**: 3.8+
 - **ComfyUI Compatibility**: Latest
 - **Dependencies**: Minimal (PyTorch, NumPy, Pillow, google-generativeai for Gemini)

__init__.py

@@ -105,7 +105,7 @@ def get_version():
     try:
         pyproject_path = Path(__file__).parent / "pyproject.toml"
         if pyproject_path.exists():
-            content = pyproject_path.read_text()
+            content = pyproject_path.read_text(encoding="utf-8")
             match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', content)
             if match:
                 return match.group(1)
@@ -118,7 +118,10 @@ def get_version():
 print()
 print(f"\033[94m[ComfyUI-KikoTools] Version:\033[0m {get_version()}")
 for node_key, display_name in NODE_DISPLAY_NAME_MAPPINGS.items():
-    print(f"🫶 \033[94mLoaded:\033[0m {display_name}")
+    # ASCII only: a Windows console using a legacy code page cannot print emoji,
+    # and a UnicodeEncodeError here would abort loading the whole node.
+    ascii_name = display_name.encode("ascii", "ignore").decode().strip()
+    print(f"  \033[94mLoaded:\033[0m {ascii_name}")
 print(f"\033[94mTotal: {len(NODE_CLASS_MAPPINGS)} tools loaded\033[0m")
 print()
 

examples/documentation/batch_prompts.md

@@ -0,0 +1,106 @@
+# Batch Prompts Node
+
+The **Batch Prompts** node loads and processes prompts from text files for batch generation workflows. It automatically cycles through prompts with each execution, making it perfect for testing multiple prompts in queue batches.
+
+## Features
+
+- **File-based prompt loading** - Load prompts from text files with `---` separators
+- **Auto-increment mode** - Automatically advance to the next prompt with each execution
+- **Positive/Negative splitting** - Automatically splits prompts at "Negative:" markers
+- **Persistent state** - Maintains position across ComfyUI restarts
+- **Wrap-around support** - Loop back to the first prompt after the last one
+- **Progress tracking** - Shows current position and total prompts
+
+## Input Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prompt_file` | STRING | "prompts.txt" | Path to text file containing prompts |
+| `index` | INT | 0 | Manual prompt index (when auto_increment is off) |
+| `auto_increment` | BOOLEAN | True | Automatically advance to next prompt |
+| `wrap_around` | BOOLEAN | True | Loop back to start after last prompt |
+| `split_negative` | BOOLEAN | True | Split prompts at "Negative:" marker |
+| `reload_file` | BOOLEAN | False | Force reload file from disk |
+| `show_preview` | BOOLEAN | True | Show prompt preview in console |
+
+## Output Values
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `positive` | STRING | The positive prompt text |
+| `negative` | STRING | The negative prompt text (if split) |
+| `full_prompt` | STRING | Complete prompt including negative |
+| `next_prompt` | STRING | Preview of the next prompt |
+| `current_index` | INT | Current prompt index (0-based) |
+| `total_prompts` | INT | Total number of prompts |
+| `batch_info` | STRING | Progress information string |
+
+## Prompt File Format
+
+Create a text file with prompts separated by `---` on its own line:
+
+```
+A beautiful sunset over the ocean
+Negative: blurry, dark, low quality
+---
+Mountain landscape with snow peaks
+Negative: foggy, unclear
+---
+Futuristic city at night
+Negative: old, vintage, sepia
+```
+
+## Usage Examples
+
+### Basic Queue Batch Processing
+
+1. Create a prompt file in your ComfyUI `input` folder
+2. Add the Batch Prompts node to your workflow
+3. Set `prompt_file` to your file name
+4. Enable `auto_increment` and `wrap_around`
+5. Connect `positive` to your text encoder
+6. Connect `negative` to your negative text encoder
+7. Set Queue Batch to desired number (e.g., 10)
+8. Run the queue - prompts will cycle automatically
+
+### Manual Index Control
+
+For manual control over which prompt to use:
+
+1. Set `auto_increment` to False
+2. Control the `index` parameter manually
+3. Use with other nodes that provide index values
+
+### Monitoring Progress
+
+The node provides several ways to track progress:
+
+- `batch_info` output shows "Prompt X of Y (Z% complete)"
+- Console logging shows current prompt preview (when `show_preview` is True)
+- `current_index` and `total_prompts` for custom progress displays
+
+## Tips
+
+- Place prompt files in the ComfyUI `input` folder for easy access
+- Use relative paths like "prompts.txt" for files in the input folder
+- Use absolute paths for files elsewhere on your system
+- The node maintains state across ComfyUI restarts
+- Set `reload_file` to True to force re-reading after editing the file
+- Empty sections (between `---` markers) are automatically skipped
+
+## Troubleshooting
+
+### Prompts not changing in queue batch
+- Ensure `auto_increment` is set to True
+- Check console for "[BatchPrompts] Auto-increment" messages
+- Restart ComfyUI after installing/updating the node
+
+### File not found errors
+- Check that the file exists in the ComfyUI `input` folder
+- Try using an absolute path to test
+- Ensure file has read permissions
+
+### State persistence
+- State is stored in your system's temp directory
+- Clear `/tmp/comfyui_batch_prompts/` to reset all counters
+- Use `reload_file` to reset counter for a specific file

examples/documentation/display_any.md

@@ -117,4 +117,4 @@ Config Node → Display Any (raw value) → Processing Node
 [Text Multiline] ← [Concatenate] ← "Image dimensions: "
 ```
 
-This creates a text output showing the current image dimensions that can be used elsewhere in your workflow.
+This creates a text output showing the current image dimensions that can be used elsewhere in your workflow.

examples/documentation/display_text.md

@@ -85,7 +85,7 @@ Display long text content with scrolling and word wrapping.
 
 The node intelligently detects prompt formats:
 
-1. **SDXL Format**: 
+1. **SDXL Format**:
    - Looks for "Positive prompt:" and "Negative prompt:" markers
    - Case-insensitive detection
    - Handles various formatting styles
@@ -98,7 +98,7 @@ The node intelligently detects prompt formats:
 ## Styling
 
 - **Font**: Monospace for consistent alignment
-- **Colors**: 
+- **Colors**:
   - Text: Light gray (#ddd) on dark background
   - Background: Semi-transparent dark (#1a1a1a)
   - Borders: Subtle gray (#333)
@@ -144,4 +144,4 @@ The node intelligently detects prompt formats:
    SDXL Format            Split View Display    Clean Prompts
 ```
 
-This creates a seamless workflow from prompt generation to usage, with the Display Text node providing the visual interface for review and interaction.
+This creates a seamless workflow from prompt generation to usage, with the Display Text node providing the visual interface for review and interaction.

examples/documentation/flux_sampler_params.md

@@ -149,4 +149,4 @@ base_shift: 0.4
 - **1.0.3**: Improved UI elements and parameter validation
 
 ## Credits
-Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.
+Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.

examples/documentation/gemini_prompt.md

@@ -206,4 +206,4 @@ Errors are displayed in the prompt output for easy debugging.
 
 **Import error for google-generativeai**:
 - Run `pip install google-generativeai` in your ComfyUI environment
-- Restart ComfyUI after installation
+- Restart ComfyUI after installation

examples/documentation/image_to_multiple_of.md

@@ -79,4 +79,4 @@ Load Images → Image to Multiple Of (multiple_of: 16, method: rescale) → Batc
 The node will raise an error if:
 - The image dimensions are smaller than the specified multiple_of value
 - Invalid input types are provided
-- The resulting dimensions would be 0 or negative
+- The resulting dimensions would be 0 or negative

examples/documentation/kiko_film_grain.md

@@ -122,4 +122,4 @@ Creates monochrome grain perfect for black and white photography.
 - Works with any image format supported by ComfyUI
 - Preserves image properties (alpha channel, batch size)
 - Compatible with both RGB and RGBA images
-- Efficient batch processing support
+- Efficient batch processing support

examples/documentation/kiko_save_image.md

@@ -50,7 +50,7 @@ Enhanced image saving node with multiple format support, quality controls, and a
 ### Image Grid
 - **Thumbnails**: Click any image to open full-size in new tab
 - **File Info**: Shows filename and size for each image
-- **Quality Indicators**: 
+- **Quality Indicators**:
   - PNG: Compression level (0-9)
   - JPEG/WebP: Quality percentage
 - **Batch Selection**: Checkboxes for multi-select operations
@@ -210,4 +210,4 @@ Batch Generate → Kiko Save Image → Popup Viewer
 **Can't see all images**:
 - Scroll within the popup grid
 - Maximize the popup window
-- Images are shown newest first
+- Images are shown newest first

examples/documentation/local_image_loader.md

@@ -0,0 +1,158 @@
+# Local Image Loader
+
+## Overview
+
+The Local Image Loader node provides a visual gallery interface for browsing and selecting images, videos, and audio files from your local filesystem directly within ComfyUI. This streamlined version focuses on essential functionality without the complexity of tagging or metadata management.
+
+## Features
+
+- **Visual Gallery Browser**: Browse local directories with thumbnail previews
+- **Multi-Media Support**: Load images, videos, and audio files
+- **Directory Navigation**: Navigate through folders with ease
+- **Sorting Options**: Sort by name, date, or file size
+- **Saved Paths**: Save frequently used directory paths for quick access
+- **Pagination**: Handle large directories with paginated display
+- **Lightbox Preview**: Full-size preview with zoom and pan capabilities
+
+## Node Inputs
+
+### Required Inputs
+None - The node uses a visual interface for file selection
+
+### Hidden Inputs
+- `unique_id`: Automatically assigned node identifier
+
+## Node Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `image` | IMAGE | The selected image as a tensor |
+| `video_path` | STRING | Path to the selected video file |
+| `audio_path` | STRING | Path to the selected audio file |
+| `info` | STRING | JSON metadata about the selected image |
+
+## Usage
+
+### Basic Workflow
+
+1. **Add the Node**: Search for "Local Image Loader" in the node menu
+2. **Browse Directory**: Enter a directory path or use saved paths
+3. **Select Media**: Click on thumbnails to select files
+4. **Connect Outputs**: Use the outputs in your workflow
+
+### Interface Controls
+
+#### Path Management
+- **Directory Input**: Enter or paste a directory path
+- **Saved Paths Dropdown**: Quick access to saved directories
+- **Save Path Button** (💾): Save current directory to favorites
+- **Browse Button** (📁): Load the entered directory
+
+#### View Options
+- **Videos Checkbox**: Show/hide video files
+- **Audio Checkbox**: Show/hide audio files
+- **Sort By**: Choose between Name, Date, or Size
+- **Sort Order**: Ascending (↑) or Descending (↓)
+- **Refresh Button** (🔄): Reload current directory
+
+#### Gallery Display
+- **Thumbnail Grid**: Visual preview of files
+- **Blue Border**: Selected items are highlighted
+- **Folder Icons**: Navigate into subdirectories
+- **Video Overlay**: Visual indicator for video files
+- **Pagination**: Navigate through pages of results
+
+## File Support
+
+### Supported Image Formats
+- `.jpg`, `.jpeg`
+- `.png`
+- `.bmp`
+- `.gif`
+- `.webp`
+
+### Supported Video Formats
+- `.mp4`
+- `.webm`
+- `.mov`
+- `.mkv`
+- `.avi`
+
+### Supported Audio Formats
+- `.mp3`
+- `.wav`
+- `.ogg`
+- `.flac`
+
+## Image Metadata
+
+When an image is selected, the node extracts and returns metadata including:
+- **Basic Info**: Filename, width, height, format, mode
+- **Embedded Parameters**: Generation parameters if present
+- **Workflow Data**: Embedded ComfyUI workflow if present
+- **Prompt Data**: Embedded prompt information if present
+
+## Examples
+
+### Loading an Image for Processing
+```
+Local Image Loader → Load Image → Image Processing Node
+                 ↓
+              [info] → Display Text (to show metadata)
+```
+
+### Setting Up a Multi-Media Workflow
+```
+Local Image Loader → [image] → Image Preview
+                 ↓
+           [video_path] → Video Player Node
+                 ↓
+           [audio_path] → Audio Player Node
+```
+
+## Tips and Best Practices
+
+1. **Save Frequently Used Paths**: Use the save button to bookmark directories you use often
+2. **Use Sorting**: Sort by date to find recent files quickly
+3. **Keyboard Navigation**: Press Enter in the path field to load a directory
+4. **Performance**: For directories with thousands of files, use pagination to navigate efficiently
+5. **Thumbnail Generation**: Thumbnails are generated on-demand and cached for performance
+
+## Differences from Original
+
+This version simplifies the original ComfyUI_Local_Image_Gallery by removing:
+- Tag filtering and management
+- Rating system
+- Global tag search
+- Metadata editing capabilities
+
+These features were removed to focus on the core functionality of browsing and selecting files, making the tool simpler and more straightforward to use.
+
+## Troubleshooting
+
+### Common Issues
+
+**Directory Not Loading**
+- Verify the path exists and you have read permissions
+- Check for special characters in the path
+- Try using absolute paths instead of relative ones
+
+**Thumbnails Not Showing**
+- Ensure the files are in supported formats
+- Check if the images are corrupted
+- Try refreshing the gallery
+
+**Large Directories Slow to Load**
+- Use sorting and pagination to manage large folders
+- Consider organizing files into subdirectories
+- Enable only the media types you need (images, videos, audio)
+
+## Technical Details
+
+The node creates a visual widget that runs in the ComfyUI interface and communicates with the backend through API endpoints to:
+- List directory contents
+- Generate thumbnails
+- Save user preferences
+- Handle file selection
+
+All file operations are performed server-side for security, with proper path validation to prevent directory traversal attacks.

examples/documentation/lora_folder_batch.md

@@ -13,6 +13,7 @@ This node is based on work from [comfyui-essentials-nodes](https://github.com/cu
 - **Flexible Strength Control**: Single, multiple, or range-based strength values
 - **Batch Modes**: Sequential or combinatorial strength application
 - **Epoch Detection**: Automatically extracts epoch numbers from filenames
+- **Auto-Batching**: Automatically splits large LoRA collections into manageable chunks to prevent UI disconnection
 
 ## Node Properties
 - **Category**: `ComfyAssets/🧰 xyz-helpers`
@@ -33,6 +34,11 @@ This node is based on work from [comfyui-essentials-nodes](https://github.com/cu
 |-----------|------|---------|-------------|
 | `include_pattern` | STRING | "" | Regex pattern to include files |
 | `exclude_pattern` | STRING | "" | Regex pattern to exclude files |
+| `max_loras` | INT | 50 | Maximum LoRAs to process (when auto_batch disabled) |
+| `sort_order` | DROPDOWN | natural | Sorting method [natural, alphabetical, newest, oldest] |
+| `auto_batch` | DROPDOWN | disabled | Enable auto-batching for large collections [disabled, enabled] |
+| `batch_size` | INT | 25 | Number of LoRAs per batch when auto-batching |
+| `batch_index` | INT | 0 | Which batch to output (0-based) when auto-batching |
 
 ### Strength Format Options
 - **Single**: `"1.0"` - Apply same strength to all LoRAs
@@ -72,6 +78,16 @@ LoRAFolderBatch → Processing Pipeline
     strength: "0.8...1.2+0.1"
 ```
 
+### Auto-Batch Large Collections
+```
+LoRAFolderBatch → FluxSamplerParams → KSampler
+    folder_path: "massive_lora_collection"  # 100+ files
+    strength: "1.0"
+    auto_batch: enabled
+    batch_size: 25
+    batch_index: 0  # Change to 1, 2, 3... for subsequent batches
+```
+
 ## Batch Modes Explained
 
 ### Sequential Mode
@@ -86,6 +102,41 @@ Each LoRA is tested with ALL strength values:
 - LoRA2 → [0.5, 0.75, 1.0]
 - LoRA3 → [0.5, 0.75, 1.0]
 
+## Auto-Batching for Large Collections
+
+### Overview
+When testing large numbers of LoRAs (e.g., 75+ files), ComfyUI can experience UI disconnections or memory issues. Auto-batching solves this by automatically splitting your LoRA collection into smaller, manageable chunks.
+
+### How It Works
+1. **Enable Auto-Batching**: Set `auto_batch` to "enabled"
+2. **Set Batch Size**: Configure `batch_size` (default: 25, range: 5-100)
+3. **Select Batch**: Use `batch_index` to choose which batch to process
+
+### Example: Testing 75 LoRAs
+With 75 LoRAs and batch_size=25, the system creates 3 batches:
+- **Batch 0**: LoRAs 1-25 (set batch_index=0)
+- **Batch 1**: LoRAs 26-50 (set batch_index=1)
+- **Batch 2**: LoRAs 51-75 (set batch_index=2)
+
+Run your workflow 3 times, changing only the `batch_index` each time.
+
+### Visual Feedback
+When auto-batching is enabled, the `lora_list` output includes batch information:
+```
+=== Batch 1/3 (LoRAs 1-25) ===
+
+style-epoch-001
+style-epoch-002
+...
+```
+
+### Best Practices for Auto-Batching
+1. **Start with Default**: Use batch_size=25 for most scenarios
+2. **Adjust for Memory**: Decrease batch_size if you still experience issues
+3. **Combinatorial Mode**: Be extra careful - 25 LoRAs × 3 strengths = 75 combinations
+4. **Save Between Batches**: Save your results after each batch to avoid data loss
+5. **Use Plot Parameters**: The batch info appears in plot visualizations for easy tracking
+
 ## File Naming Patterns
 
 ### Supported Epoch Formats
@@ -207,6 +258,7 @@ batch_mode: sequential
 - **1.0.1**: Added natural sorting for epochs
 - **1.0.2**: Enhanced pattern filtering
 - **1.0.3**: Improved batch modes and strength parsing
+- **1.0.4**: Added auto-batching for large LoRA collections
 
 ## Credits
-Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.
+Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.

examples/documentation/plot_parameters.md

@@ -109,12 +109,12 @@ Parameter Grid → PlotParameters → Analysis Display
 x_axis: "guidance"
 y_axis: "perceived_quality"
 
-# Step efficiency analysis  
+# Step efficiency analysis
 x_axis: "steps"
 y_axis: "generation_time"
 
 # LoRA impact assessment
-x_axis: "lora_strength"  
+x_axis: "lora_strength"
 y_axis: "style_adherence"
 ```
 
@@ -231,4 +231,4 @@ Compare multiple generation runs to identify optimal parameters.
 - **1.0.3**: Improved export capabilities
 
 ## Credits
-Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.
+Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.

examples/documentation/sampler_select_helper.md

@@ -257,4 +257,4 @@ Compare all compatible samplers for specific model/prompt combination.
 - **1.0.3**: Improved auto-detection
 
 ## Credits
-Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.
+Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.

examples/documentation/scheduler_select_helper.md

@@ -297,4 +297,4 @@ Progress through schedulers from fast to quality for different use cases.
 - **1.0.3**: Improved compatibility matrix
 
 ## Credits
-Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.
+Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.

examples/documentation/text_encode_sampler_params.md

@@ -142,7 +142,7 @@ steps: 30-40
 cfg: 7-8
 sampler: dpmpp_3m_sde
 
-# Speed over quality  
+# Speed over quality
 steps: 10-15
 cfg: 5-6
 sampler: euler
@@ -307,4 +307,4 @@ Very High (50+): Diminishing returns
 - **1.0.3**: Improved batch processing
 
 ## Credits
-Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.
+Original implementation by cubiq in [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials). Adapted and maintained by the ComfyAssets team.

examples/test_prompts.txt

@@ -0,0 +1,14 @@
+A beautiful sunset over the ocean, golden hour lighting, professional photography, vibrant colors, high detail
+Negative: blurry, dark, low quality, distorted, oversaturated
+---
+Majestic mountain landscape with snow-capped peaks, dramatic clouds, alpine scenery, crystal clear air, epic composition
+Negative: foggy, flat lighting, boring composition, low contrast
+---
+Futuristic cityscape at night, neon lights, cyberpunk aesthetic, rain-slicked streets, atmospheric, blade runner style
+Negative: daylight, rural, old fashioned, low tech, empty streets
+---
+Enchanted forest with magical glowing mushrooms, fairy lights, mystical atmosphere, ancient trees, fantasy art style
+Negative: desert, urban, modern, realistic, mundane
+---
+Space station orbiting Earth, detailed mechanical structures, astronauts performing spacewalk, realistic sci-fi, NASA photography
+Negative: fantasy, medieval, underwater, cartoon style

examples/workflows/display_any_example.json

@@ -376,4 +376,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}

examples/workflows/display_text_example.json

@@ -141,4 +141,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}

examples/workflows/empty_latent_batch_example.json

@@ -298,4 +298,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}

examples/workflows/gemini_prompt_example.json

@@ -204,4 +204,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}

examples/workflows/image_to_multiple_of_example.json

@@ -549,4 +549,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}

examples/workflows/kiko_film_grain_example.json

@@ -162,4 +162,4 @@
     }
   },
   "version": 0.4
-}
+}

examples/workflows/kiko_save_image_example.json

@@ -144,4 +144,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}

examples/workflows/resolution_calculator_example.json

@@ -352,4 +352,4 @@
     "VHS_KeepIntermediate": true
   },
   "version": 0.4
-}
+}

examples/workflows/xyz_helpers_sampler_comparison.json

@@ -166,4 +166,4 @@
     ],
     "attribution": "xyz_helpers nodes adapted from comfyui-essentials-nodes"
   }
-}
+}

kikotools/__init__.py

@@ -3,6 +3,13 @@ KikoTools package initialization and node registry
 Handles automatic discovery and registration of all ComfyAssets tools
 """
 
+from .tools.batch_list_converter import (
+    ImageBatchToImageListNode,
+    ImageListToImageBatchNode,
+    LatentBatchToLatentListNode,
+    LatentListToLatentBatchNode,
+)
+from .tools.batch_prompts import BatchPromptsNode
 from .tools.display_any import DisplayAnyNode
 from .tools.display_text import DisplayTextNode
 from .tools.embedding_autocomplete import KikoEmbeddingAutocomplete
@@ -11,11 +18,17 @@ from .tools.gemini_prompt import GeminiPromptNode
 from .tools.image_scale_down_by import ImageScaleDownByNode
 from .tools.image_to_multiple_of import ImageToMultipleOfNode
 from .tools.kiko_film_grain import KikoFilmGrainNode
+from .tools.kiko_purge_vram import KikoPurgeVRAM
+from .tools.kiko_workflow_timer import KikoWorkflowTimerNode
 from .tools.kiko_save_image import KikoSaveImageNode
+from .tools.local_image_loader import LocalImageLoaderNode
+from .tools.model_downloader import ModelDownloaderNode
 from .tools.resolution_calculator import ResolutionCalculatorNode
 from .tools.sampler_combo import SamplerComboCompactNode, SamplerComboNode
 from .tools.seed_history import SeedHistoryNode
+from .tools.text_input import TextInputNode
 from .tools.width_height_selector import WidthHeightSelectorNode
+from .tools.width_height_to_vec2 import WidthHeightToVec2Node
 from .tools.xyz_helpers import (
     FluxSamplerParamsNode,
     LoRAFolderBatchNode,
@@ -27,6 +40,11 @@ from .tools.xyz_helpers import (
 
 # ComfyUI node registration mappings
 NODE_CLASS_MAPPINGS = {
+    "ImageBatchToImageList": ImageBatchToImageListNode,
+    "ImageListToImageBatch": ImageListToImageBatchNode,
+    "LatentBatchToLatentList": LatentBatchToLatentListNode,
+    "LatentListToLatentBatch": LatentListToLatentBatchNode,
+    "BatchPrompts": BatchPromptsNode,
     "ResolutionCalculator": ResolutionCalculatorNode,
     "WidthHeightSelector": WidthHeightSelectorNode,
     "SeedHistory": SeedHistoryNode,
@@ -39,17 +57,29 @@ NODE_CLASS_MAPPINGS = {
     "GeminiPrompt": GeminiPromptNode,
     "DisplayAny": DisplayAnyNode,
     "DisplayText": DisplayTextNode,
+    "TextInput": TextInputNode,
     "KikoFilmGrain": KikoFilmGrainNode,
+    "KikoPurgeVRAM": KikoPurgeVRAM,
+    "KikoLocalImageLoader": LocalImageLoaderNode,
+    "KikoModelDownloader": ModelDownloaderNode,
     "SamplerSelectHelper": SamplerSelectHelperNode,
     "SchedulerSelectHelper": SchedulerSelectHelperNode,
     "TextEncodeSamplerParams": TextEncodeSamplerParamsNode,
     "FluxSamplerParams": FluxSamplerParamsNode,
     "PlotParameters+": PlotParametersNode,
     "LoRAFolderBatch": LoRAFolderBatchNode,
-    "KikoEmbeddingAutocomplete": KikoEmbeddingAutocomplete,
+    "WidthHeightToVec2": WidthHeightToVec2Node,
+    "KikoWorkflowTimer": KikoWorkflowTimerNode,
+    # Note: KikoEmbeddingAutocomplete is not registered as a node
+    # It's a settings-only feature accessed through ComfyUI settings menu
 }
 
 NODE_DISPLAY_NAME_MAPPINGS = {
+    "ImageBatchToImageList": "Image Batch to Image List",
+    "ImageListToImageBatch": "Image List to Image Batch",
+    "LatentBatchToLatentList": "Latent Batch to Latent List",
+    "LatentListToLatentBatch": "Latent List to Latent Batch",
+    "BatchPrompts": "Batch Prompts",
     "ResolutionCalculator": "Resolution Calculator",
     "WidthHeightSelector": "Width Height Selector",
     "SeedHistory": "Seed History",
@@ -62,14 +92,20 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "GeminiPrompt": "Gemini Prompt Engineer",
     "DisplayAny": "Display Any",
     "DisplayText": "Display Text",
-    "KikoFilmGrain": "Kiko Film Grain",
+    "TextInput": "Text Input",
+    "KikoFilmGrain": "Film Grain",
+    "KikoPurgeVRAM": "Kiko Purge VRAM",
+    "KikoLocalImageLoader": "Local Image Loader",
+    "KikoModelDownloader": "Model Downloader 🌐",
     "SamplerSelectHelper": "Sampler Select Helper",
     "SchedulerSelectHelper": "Scheduler Select Helper",
     "TextEncodeSamplerParams": "Text Encode for Sampler Params",
     "FluxSamplerParams": "Flux Sampler Parameters",
     "PlotParameters+": "Plot Parameters",
     "LoRAFolderBatch": "LoRA Folder Batch",
-    "KikoEmbeddingAutocomplete": "🫶 Embedding Autocomplete Configuration",
+    "WidthHeightToVec2": "Width Height to VEC2",
+    "KikoWorkflowTimer": "Workflow Timer",
+    # KikoEmbeddingAutocomplete removed - settings only, not a node
 }
 
 __all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

kikotools/base/any_type.py

@@ -0,0 +1,8 @@
+"""AnyType for wildcard input matching in ComfyUI nodes."""
+
+
+class AnyType(str):
+    """A special type that matches any input type in ComfyUI."""
+
+    def __ne__(self, other):
+        return False

kikotools/base/base_node.py

@@ -20,7 +20,7 @@ class ComfyAssetsBaseNode:
     - Consistent return type handling
     """
 
-    CATEGORY = "ComfyAssets"
+    CATEGORY = "🫶 ComfyAssets"
 
     def validate_inputs(self, **kwargs) -> None:
         """

kikotools/core/registry.py

@@ -1,96 +0,0 @@
-"""Tool registry for KikoTools.
-
-This module provides the central registration system for all KikoTools nodes.
-"""
-
-import importlib
-import os
-from typing import Dict, List, Any, Optional
-from pathlib import Path
-
-
-class ToolRegistry:
-    """Central registry for all KikoTools."""
-
-    def __init__(self):
-        self.tools: Dict[str, Any] = {}
-        self.node_classes: Dict[str, Any] = {}
-
-    def register_tool(self, tool_name: str, node_class: Any) -> None:
-        """Register a tool and its node class.
-
-        Args:
-            tool_name: Name of the tool
-            node_class: The ComfyUI node class
-        """
-        self.tools[tool_name] = node_class
-
-        # Also register by class name for ComfyUI
-        class_name = node_class.__name__
-        self.node_classes[class_name] = node_class
-
-    def discover_tools(self) -> None:
-        """Automatically discover and load all tools in the tools directory."""
-        tools_dir = Path(__file__).parent.parent / "tools"
-
-        if not tools_dir.exists():
-            return
-
-        for tool_dir in tools_dir.iterdir():
-            if tool_dir.is_dir() and not tool_dir.name.startswith("_"):
-                self._load_tool(tool_dir.name)
-
-    def _load_tool(self, tool_name: str) -> None:
-        """Load a single tool module.
-
-        Args:
-            tool_name: Name of the tool directory
-        """
-        try:
-            # Try to import the tool's node module
-            module = importlib.import_module(f"kikotools.tools.{tool_name}.node")
-
-            # Look for node classes (classes with ComfyUI node attributes)
-            for attr_name in dir(module):
-                attr = getattr(module, attr_name)
-                if (
-                    isinstance(attr, type)
-                    and hasattr(attr, "INPUT_TYPES")
-                    and hasattr(attr, "FUNCTION")
-                ):
-                    self.register_tool(tool_name, attr)
-
-                    # If the tool has settings, register them
-                    if hasattr(attr, "SETTINGS"):
-                        from .settings import settings_registry
-
-                        settings_registry.register_tool_settings(
-                            tool_name,
-                            getattr(
-                                attr,
-                                "DISPLAY_NAME",
-                                tool_name.replace("_", " ").title(),
-                            ),
-                            attr.SETTINGS,
-                        )
-
-        except ImportError as e:
-            # Tool might not have a node.py file yet
-            pass
-
-    def get_node_class_mappings(self) -> Dict[str, Any]:
-        """Get node class mappings for ComfyUI registration."""
-        return self.node_classes.copy()
-
-    def get_node_display_name_mappings(self) -> Dict[str, str]:
-        """Get display name mappings for ComfyUI."""
-        mappings = {}
-        for class_name, node_class in self.node_classes.items():
-            if hasattr(node_class, "DISPLAY_NAME"):
-                mappings[class_name] = node_class.DISPLAY_NAME
-            else:
-                # Generate a display name from class name
-                mappings[class_name] = class_name.replace("Kiko", "").replace(
-                    "Node", ""
-                )
-        return mappings

kikotools/core/settings.py

@@ -1,201 +0,0 @@
-"""Settings registry for KikoTools.
-
-This module provides a centralized settings management system for all KikoTools.
-Tools can register their settings, which are then exposed in ComfyUI's settings UI.
-"""
-
-import json
-import os
-from typing import Dict, Any, List, Optional, Union
-from dataclasses import dataclass, field
-
-
-@dataclass
-class SettingDefinition:
-    """Definition of a single setting."""
-
-    id: str
-    name: str
-    type: str  # "boolean", "combo", "number", "string", "custom"
-    default: Any
-    description: Optional[str] = None
-    options: Optional[Union[List[Any], Dict[str, Any]]] = None
-    min_value: Optional[float] = None
-    max_value: Optional[float] = None
-    step: Optional[float] = None
-    on_change: Optional[str] = None  # JavaScript callback as string
-
-
-@dataclass
-class ToolSettings:
-    """Settings collection for a single tool."""
-
-    tool_name: str
-    display_name: str
-    settings: List[SettingDefinition] = field(default_factory=list)
-
-
-class SettingsRegistry:
-    """Central registry for all KikoTools settings."""
-
-    def __init__(self):
-        self.tools: Dict[str, ToolSettings] = {}
-        self.settings_by_id: Dict[str, SettingDefinition] = {}
-
-    def register_tool_settings(
-        self, tool_name: str, display_name: str, settings: Dict[str, Dict[str, Any]]
-    ) -> None:
-        """Register settings for a tool.
-
-        Args:
-            tool_name: Internal tool identifier (e.g., "embedding_autocomplete")
-            display_name: Display name for the tool (e.g., "Embedding Autocomplete")
-            settings: Dictionary of setting configurations
-                {
-                    "enabled": {
-                        "type": "boolean",
-                        "default": True,
-                        "description": "Enable embedding autocomplete"
-                    },
-                    "max_suggestions": {
-                        "type": "combo",
-                        "default": 20,
-                        "options": [10, 20, 50],
-                        "description": "Maximum number of suggestions"
-                    }
-                }
-        """
-        tool_settings = ToolSettings(tool_name, display_name)
-
-        for setting_key, config in settings.items():
-            # Generate fully qualified setting ID
-            setting_id = f"kikotools.{tool_name}.{setting_key}"
-
-            # Create display name with branding
-            setting_name = f"🫶 {display_name}: {setting_key.replace('_', ' ').title()}"
-
-            setting_def = SettingDefinition(
-                id=setting_id,
-                name=setting_name,
-                type=config.get("type", "string"),
-                default=config.get("default"),
-                description=config.get("description"),
-                options=config.get("options"),
-                min_value=config.get("min"),
-                max_value=config.get("max"),
-                step=config.get("step"),
-                on_change=config.get("on_change"),
-            )
-
-            tool_settings.settings.append(setting_def)
-            self.settings_by_id[setting_id] = setting_def
-
-        self.tools[tool_name] = tool_settings
-
-    def get_setting(self, setting_id: str) -> Optional[SettingDefinition]:
-        """Get a setting definition by ID."""
-        return self.settings_by_id.get(setting_id)
-
-    def get_tool_settings(self, tool_name: str) -> Optional[ToolSettings]:
-        """Get all settings for a tool."""
-        return self.tools.get(tool_name)
-
-    def generate_frontend_registration(self) -> str:
-        """Generate JavaScript code for frontend settings registration."""
-        js_lines = [
-            "// Auto-generated KikoTools settings registration",
-            "// This file is automatically generated by the settings registry",
-            "",
-            "import { app } from '../../scripts/app.js';",
-            "",
-            "app.registerExtension({",
-            "    name: 'kikotools.settings',",
-            "    async init() {",
-            "        // Register all KikoTools settings",
-        ]
-
-        for tool_name, tool_settings in self.tools.items():
-            js_lines.append(f"        // {tool_settings.display_name} settings")
-
-            for setting in tool_settings.settings:
-                js_lines.append(f"        app.ui.settings.addSetting({{")
-                js_lines.append(f'            id: "{setting.id}",')
-                js_lines.append(f'            name: "{setting.name}",')
-                js_lines.append(
-                    f"            defaultValue: {self._js_value(setting.default)},"
-                )
-                js_lines.append(f'            type: "{setting.type}",')
-
-                if setting.description:
-                    js_lines.append(f'            tooltip: "{setting.description}",')
-
-                if setting.type == "combo" and setting.options:
-                    js_lines.append(f"            options: (value) => {{")
-                    js_lines.append(
-                        f"                const options = {json.dumps(setting.options)};"
-                    )
-                    js_lines.append(f"                return options.map(opt => ({{")
-                    js_lines.append(f"                    value: opt,")
-                    js_lines.append(f"                    text: String(opt),")
-                    js_lines.append(f"                    selected: opt === value")
-                    js_lines.append(f"                }}));")
-                    js_lines.append(f"            }},")
-
-                if setting.type == "number":
-                    if setting.min_value is not None:
-                        js_lines.append(f"            min: {setting.min_value},")
-                    if setting.max_value is not None:
-                        js_lines.append(f"            max: {setting.max_value},")
-                    if setting.step is not None:
-                        js_lines.append(f"            step: {setting.step},")
-
-                if setting.on_change:
-                    js_lines.append(f"            onChange(value) {{")
-                    js_lines.append(f"                {setting.on_change}")
-                    js_lines.append(f"            }}")
-
-                js_lines.append(f"        }});")
-                js_lines.append("")
-
-        js_lines.extend(["    }", "});", ""])
-
-        return "\n".join(js_lines)
-
-    def _js_value(self, value: Any) -> str:
-        """Convert Python value to JavaScript literal."""
-        if isinstance(value, bool):
-            return "true" if value else "false"
-        elif isinstance(value, str):
-            return f'"{value}"'
-        elif value is None:
-            return "null"
-        else:
-            return str(value)
-
-    def save_frontend_settings(
-        self, output_path: str = "web/js/kikoSettings.js"
-    ) -> None:
-        """Save the generated frontend settings to a file."""
-        js_content = self.generate_frontend_registration()
-
-        os.makedirs(os.path.dirname(output_path), exist_ok=True)
-        with open(output_path, "w") as f:
-            f.write(js_content)
-
-    def get_all_settings(self) -> Dict[str, Any]:
-        """Get all registered settings as a dictionary."""
-        result = {}
-        for tool_name, tool_settings in self.tools.items():
-            result[tool_name] = {
-                "display_name": tool_settings.display_name,
-                "settings": {
-                    setting.id.split(".")[-1]: {
-                        "type": setting.type,
-                        "default": setting.default,
-                        "description": setting.description,
-                        "options": setting.options,
-                    }
-                    for setting in tool_settings.settings
-                },
-            }
-        return result

kikotools/tools/batch_list_converter/__init__.py

@@ -0,0 +1,15 @@
+"""Batch/List conversion tool for ComfyUI."""
+
+from .node import (
+    ImageBatchToImageListNode,
+    ImageListToImageBatchNode,
+    LatentBatchToLatentListNode,
+    LatentListToLatentBatchNode,
+)
+
+__all__ = [
+    "ImageBatchToImageListNode",
+    "ImageListToImageBatchNode",
+    "LatentBatchToLatentListNode",
+    "LatentListToLatentBatchNode",
+]

kikotools/tools/batch_list_converter/logic.py

@@ -0,0 +1,55 @@
+"""Pure tensor split/join functions for batch-list conversions."""
+
+import torch
+from typing import Dict, List
+
+
+def split_image_batch(images: torch.Tensor) -> List[torch.Tensor]:
+    """Split [B,H,W,C] image batch into list of [1,H,W,C] tensors."""
+    return [images[i : i + 1] for i in range(images.shape[0])]
+
+
+def join_image_batch(image_list: List[torch.Tensor]) -> torch.Tensor:
+    """Join list of image tensors into single [B,H,W,C] batch."""
+    return torch.cat(image_list, dim=0)
+
+
+def split_latent_batch(
+    latent: Dict[str, torch.Tensor],
+) -> List[Dict[str, torch.Tensor]]:
+    """Split latent dict into list of single-item latent dicts.
+
+    Preserves all keys (e.g. noise_mask, batch_index). Tensor values whose
+    first dimension matches the batch size of ``samples`` are sliced along
+    dim-0; all other values are copied as-is to every item.
+    """
+    samples = latent["samples"]
+    batch_size = samples.shape[0]
+    result: List[Dict[str, torch.Tensor]] = []
+    for i in range(batch_size):
+        item: Dict[str, torch.Tensor] = {}
+        for key, value in latent.items():
+            if isinstance(value, torch.Tensor) and value.shape[0] == batch_size:
+                item[key] = value[i : i + 1]
+            else:
+                item[key] = value
+        result.append(item)
+    return result
+
+
+def join_latent_batch(
+    latent_list: List[Dict[str, torch.Tensor]],
+) -> Dict[str, torch.Tensor]:
+    """Join list of latent dicts into single batched latent dict.
+
+    Tensor values that were sliced during split are concatenated along dim-0.
+    Non-tensor values are taken from the first item.
+    """
+    result: Dict[str, torch.Tensor] = {}
+    first = latent_list[0]
+    for key in first:
+        if isinstance(first[key], torch.Tensor):
+            result[key] = torch.cat([lat[key] for lat in latent_list], dim=0)
+        else:
+            result[key] = first[key]
+    return result

kikotools/tools/batch_list_converter/node.py

@@ -0,0 +1,130 @@
+"""Batch/List conversion nodes for ComfyUI."""
+
+from typing import Dict, List, Tuple
+
+import torch
+
+from ...base.base_node import ComfyAssetsBaseNode
+from .logic import (
+    split_image_batch,
+    join_image_batch,
+    split_latent_batch,
+    join_latent_batch,
+)
+
+
+class ImageBatchToImageListNode(ComfyAssetsBaseNode):
+    """Split an IMAGE batch [B,H,W,C] into a list of individual images."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "images": ("IMAGE",),
+            }
+        }
+
+    RETURN_TYPES = ("IMAGE", "INT")
+    RETURN_NAMES = ("images", "count")
+    OUTPUT_IS_LIST = (True, False)
+    FUNCTION = "split_batch"
+    CATEGORY = "🫶 ComfyAssets/📦 Latents"
+
+    def split_batch(self, images: torch.Tensor) -> Tuple[List[torch.Tensor], int]:
+        image_list = split_image_batch(images)
+        count = len(image_list)
+        self.log_info(f"Split image batch of {count} into list")
+        return (image_list, count)
+
+
+class ImageListToImageBatchNode(ComfyAssetsBaseNode):
+    """Join a list of IMAGE tensors into a single batched IMAGE [B,H,W,C]."""
+
+    INPUT_IS_LIST = True
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "images": ("IMAGE",),
+            }
+        }
+
+    RETURN_TYPES = ("IMAGE", "INT")
+    RETURN_NAMES = ("images", "count")
+    FUNCTION = "join_batch"
+    CATEGORY = "🫶 ComfyAssets/📦 Latents"
+
+    def join_batch(self, images: List[torch.Tensor]) -> Tuple[torch.Tensor, int]:
+        batch = join_image_batch(images)
+        count = batch.shape[0]
+        self.log_info(f"Joined {count} images into batch")
+        return (batch, count)
+
+
+class LatentBatchToLatentListNode(ComfyAssetsBaseNode):
+    """Split a LATENT batch into a list of individual latent dicts."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "latent": ("LATENT",),
+            }
+        }
+
+    RETURN_TYPES = ("LATENT", "INT")
+    RETURN_NAMES = ("latents", "count")
+    OUTPUT_IS_LIST = (True, False)
+    FUNCTION = "split_batch"
+    CATEGORY = "🫶 ComfyAssets/📦 Latents"
+
+    def split_batch(
+        self, latent: Dict[str, torch.Tensor]
+    ) -> Tuple[List[Dict[str, torch.Tensor]], int]:
+        latent_list = split_latent_batch(latent)
+        count = len(latent_list)
+        self.log_info(f"Split latent batch of {count} into list")
+        return (latent_list, count)
+
+
+class LatentListToLatentBatchNode(ComfyAssetsBaseNode):
+    """Join a list of LATENT dicts into a single batched LATENT."""
+
+    INPUT_IS_LIST = True
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "latents": ("LATENT",),
+            }
+        }
+
+    RETURN_TYPES = ("LATENT", "INT")
+    RETURN_NAMES = ("latent", "count")
+    FUNCTION = "join_batch"
+    CATEGORY = "🫶 ComfyAssets/📦 Latents"
+
+    def join_batch(
+        self, latents: List[Dict[str, torch.Tensor]]
+    ) -> Tuple[Dict[str, torch.Tensor], int]:
+        batch = join_latent_batch(latents)
+        count = batch["samples"].shape[0]
+        self.log_info(f"Joined {count} latents into batch")
+        return (batch, count)
+
+
+NODE_CLASS_MAPPINGS = {
+    "ImageBatchToImageList": ImageBatchToImageListNode,
+    "ImageListToImageBatch": ImageListToImageBatchNode,
+    "LatentBatchToLatentList": LatentBatchToLatentListNode,
+    "LatentListToLatentBatch": LatentListToLatentBatchNode,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "ImageBatchToImageList": "Image Batch to Image List",
+    "ImageListToImageBatch": "Image List to Image Batch",
+    "LatentBatchToLatentList": "Latent Batch to Latent List",
+    "LatentListToLatentBatch": "Latent List to Latent Batch",
+}

kikotools/tools/batch_prompts/__init__.py

@@ -0,0 +1,5 @@
+"""Batch Prompts node for loading and processing prompts from text files."""
+
+from .node import BatchPromptsNode
+
+__all__ = ["BatchPromptsNode"]

kikotools/tools/batch_prompts/logic.py

@@ -0,0 +1,278 @@
+"""Logic module for Batch Prompts node."""
+
+import os
+from typing import List, Tuple, Dict, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def load_prompts_from_file(file_path: str) -> List[str]:
+    """
+    Load prompts from a text file where prompts are separated by '---'.
+
+    Args:
+        file_path: Path to the text file containing prompts
+
+    Returns:
+        List of prompts (each prompt may be multi-line)
+    """
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            content = f.read()
+
+        # Split by --- separator
+        prompts = content.split("---")
+
+        # Clean up prompts - remove leading/trailing whitespace but preserve internal formatting
+        cleaned_prompts = []
+        for prompt in prompts:
+            prompt = prompt.strip()
+            if prompt:  # Only add non-empty prompts
+                cleaned_prompts.append(prompt)
+
+        logger.info(f"Loaded {len(cleaned_prompts)} prompts from {file_path}")
+        return cleaned_prompts
+
+    except Exception as e:
+        logger.error(f"Error loading prompts from {file_path}: {e}")
+        return []
+
+
+def get_prompt_at_index(
+    prompts: List[str], index: int, wrap: bool = True
+) -> Tuple[str, int]:
+    """
+    Get prompt at specified index with optional wrapping.
+
+    Args:
+        prompts: List of prompts
+        index: Index to retrieve
+        wrap: Whether to wrap around to beginning when index exceeds list length
+
+    Returns:
+        Tuple of (prompt text, actual index used)
+    """
+    if not prompts:
+        return ("", 0)
+
+    if wrap:
+        actual_index = index % len(prompts)
+    else:
+        actual_index = min(index, len(prompts) - 1)
+
+    return (prompts[actual_index], actual_index)
+
+
+def get_next_prompt(
+    prompts: List[str], current_index: int, wrap: bool = True
+) -> Tuple[str, int]:
+    """
+    Get the next prompt in sequence.
+
+    Args:
+        prompts: List of prompts
+        current_index: Current prompt index
+        wrap: Whether to wrap around to beginning
+
+    Returns:
+        Tuple of (next prompt text, next index)
+    """
+    if not prompts:
+        return ("", 0)
+
+    next_index = current_index + 1
+
+    if wrap:
+        next_index = next_index % len(prompts)
+    else:
+        next_index = min(next_index, len(prompts) - 1)
+
+    return (prompts[next_index], next_index)
+
+
+def get_prompt_preview(prompt: str, max_length: int = 100) -> str:
+    """
+    Get a preview of a prompt, truncated if necessary.
+
+    Args:
+        prompt: Full prompt text
+        max_length: Maximum length for preview
+
+    Returns:
+        Preview string
+    """
+    if len(prompt) <= max_length:
+        return prompt
+
+    return prompt[:max_length] + "..."
+
+
+def parse_prompt_file_list(file_list_str: str) -> List[str]:
+    """
+    Parse a comma-separated list of prompt file paths.
+
+    Args:
+        file_list_str: Comma-separated file paths
+
+    Returns:
+        List of file paths
+    """
+    if not file_list_str:
+        return []
+
+    files = []
+    for file_path in file_list_str.split(","):
+        file_path = file_path.strip()
+        if file_path:
+            files.append(file_path)
+
+    return files
+
+
+def merge_prompts_from_multiple_files(file_paths: List[str]) -> List[str]:
+    """
+    Load and merge prompts from multiple files.
+
+    Args:
+        file_paths: List of file paths
+
+    Returns:
+        Combined list of all prompts
+    """
+    all_prompts = []
+
+    for file_path in file_paths:
+        prompts = load_prompts_from_file(file_path)
+        all_prompts.extend(prompts)
+
+    logger.info(f"Merged {len(all_prompts)} prompts from {len(file_paths)} files")
+    return all_prompts
+
+
+def get_batch_info(prompts: List[str], current_index: int) -> Dict[str, Any]:
+    """
+    Get information about current batch processing state.
+
+    Args:
+        prompts: List of prompts
+        current_index: Current prompt index
+
+    Returns:
+        Dictionary with batch information
+    """
+    total = len(prompts)
+
+    return {
+        "current_index": current_index,
+        "total_prompts": total,
+        "progress": f"{current_index + 1}/{total}" if total > 0 else "0/0",
+        "percentage": (current_index / total * 100) if total > 0 else 0,
+        "remaining": total - current_index - 1 if total > 0 else 0,
+        "is_complete": current_index >= total - 1 if total > 0 else True,
+    }
+
+
+def validate_prompt_file(file_path: str) -> Tuple[bool, str]:
+    """
+    Validate that a prompt file exists and is readable.
+
+    Args:
+        file_path: Path to validate
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if not file_path:
+        return (False, "No file path provided")
+
+    if not os.path.exists(file_path):
+        return (False, f"File not found: {file_path}")
+
+    if not os.path.isfile(file_path):
+        return (False, f"Path is not a file: {file_path}")
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            f.read(1)  # Try to read one character
+        return (True, "")
+    except Exception as e:
+        return (False, f"Cannot read file: {str(e)}")
+
+
+def format_prompt_for_display(prompt: str, index: int, total: int) -> str:
+    """
+    Format a prompt for display with index information.
+
+    Args:
+        prompt: Prompt text
+        index: Current index
+        total: Total number of prompts
+
+    Returns:
+        Formatted display string
+    """
+    header = f"[Prompt {index + 1}/{total}]"
+    separator = "-" * len(header)
+
+    return f"{header}\n{separator}\n{prompt}"
+
+
+def split_prompt_into_positive_negative(
+    prompt: str, negative_prefix: str = "Negative:"
+) -> Tuple[str, str]:
+    """
+    Split a prompt into positive and negative parts.
+
+    Args:
+        prompt: Full prompt text
+        negative_prefix: Prefix that marks the negative prompt section
+
+    Returns:
+        Tuple of (positive_prompt, negative_prompt)
+    """
+    # Look for negative prompt marker
+    negative_lower = negative_prefix.lower()
+    prompt_lower = prompt.lower()
+
+    if negative_lower in prompt_lower:
+        # Find the actual position (case-insensitive search)
+        idx = prompt_lower.index(negative_lower)
+        positive = prompt[:idx].strip()
+        negative = prompt[idx + len(negative_prefix) :].strip()
+        return (positive, negative)
+
+    # No negative prompt found
+    return (prompt, "")
+
+
+def create_batch_queue(
+    prompts: List[str], batch_size: int = 1, randomize: bool = False
+) -> List[List[int]]:
+    """
+    Create a queue of prompt indices for batch processing.
+
+    Args:
+        prompts: List of prompts
+        batch_size: Number of prompts per batch
+        randomize: Whether to randomize the order
+
+    Returns:
+        List of batches, where each batch is a list of prompt indices
+    """
+    if not prompts:
+        return []
+
+    indices = list(range(len(prompts)))
+
+    if randomize:
+        import random
+
+        random.shuffle(indices)
+
+    batches = []
+    for i in range(0, len(indices), batch_size):
+        batch = indices[i : i + batch_size]
+        batches.append(batch)
+
+    return batches

kikotools/tools/batch_prompts/node.py

@@ -0,0 +1,237 @@
+"""Batch Prompts node for ComfyUI."""
+
+import os
+from typing import Tuple
+from ...base.base_node import ComfyAssetsBaseNode
+from .logic import (
+    load_prompts_from_file,
+    get_prompt_at_index,
+    get_next_prompt,
+    get_prompt_preview,
+    get_batch_info,
+    validate_prompt_file,
+    split_prompt_into_positive_negative,
+)
+from .state_manager import STATE_MANAGER
+
+
+class BatchPromptsNode(ComfyAssetsBaseNode):
+    """
+    Batch Prompts node for loading and iterating through prompts from text files.
+
+    Loads prompts from a text file where prompts are separated by '---' markers,
+    provides iteration control, and outputs both current and next prompts with
+    optional positive/negative splitting.
+    """
+
+    # Class variable to cache loaded prompts
+    _prompt_cache = {}
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        """Define the input types for the ComfyUI node."""
+        # Try to get input folder path
+        try:
+            import folder_paths
+
+            folder_paths.get_input_directory()
+        except Exception:
+            pass
+
+        return {
+            "required": {
+                "prompt_file": (
+                    "STRING",
+                    {
+                        "default": "prompts.txt",
+                        "multiline": False,
+                        "tooltip": "Path to text file containing prompts separated by '---'",
+                    },
+                ),
+                "index": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 9999,
+                        "step": 1,
+                        "tooltip": "Current prompt index (0-based)",
+                    },
+                ),
+                "auto_increment": (
+                    "BOOLEAN",
+                    {
+                        "default": True,
+                        "tooltip": "Automatically increment index after each execution",
+                    },
+                ),
+                "wrap_around": (
+                    "BOOLEAN",
+                    {
+                        "default": True,
+                        "tooltip": "Wrap to first prompt after reaching the end",
+                    },
+                ),
+                "split_negative": (
+                    "BOOLEAN",
+                    {
+                        "default": True,
+                        "tooltip": "Split prompts into positive/negative at 'Negative:' marker",
+                    },
+                ),
+            },
+            "optional": {
+                "reload_file": (
+                    "BOOLEAN",
+                    {"default": False, "tooltip": "Force reload file from disk"},
+                ),
+                "show_preview": (
+                    "BOOLEAN",
+                    {"default": True, "tooltip": "Show prompt preview in console"},
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("STRING", "STRING", "STRING", "STRING", "INT", "INT", "STRING")
+    RETURN_NAMES = (
+        "positive",
+        "negative",
+        "full_prompt",
+        "next_prompt",
+        "current_index",
+        "total_prompts",
+        "batch_info",
+    )
+    FUNCTION = "process_batch_prompts"
+    CATEGORY = "🫶 ComfyAssets/📝 Text"
+
+    def process_batch_prompts(
+        self,
+        prompt_file: str,
+        index: int,
+        auto_increment: bool,
+        wrap_around: bool,
+        split_negative: bool,
+        reload_file: bool = False,
+        show_preview: bool = True,
+    ) -> Tuple[str, str, str, str, int, int, str]:
+        """
+        Process batch prompts from file.
+
+        Args:
+            prompt_file: Path to prompt file
+            index: Current prompt index
+            auto_increment: Whether to auto-increment index
+            wrap_around: Whether to wrap around at end
+            split_negative: Whether to split positive/negative prompts
+            reload_file: Force reload from disk
+            show_preview: Show prompt preview in console
+
+        Returns:
+            Tuple of (positive, negative, full_prompt, next_prompt, current_index, total_prompts, batch_info)
+        """
+        try:
+            # Handle file path first to get a consistent key
+            if not os.path.isabs(prompt_file):
+                # Try to resolve relative to ComfyUI input directory
+                try:
+                    import folder_paths
+
+                    input_dir = folder_paths.get_input_directory()
+                    full_path = os.path.join(input_dir, prompt_file)
+                except Exception:
+                    # Fallback to current directory
+                    full_path = os.path.abspath(prompt_file)
+            else:
+                full_path = prompt_file
+
+            # Use persistent state manager for tracking execution
+            if auto_increment:
+                # Use file-based persistent state
+                actual_index = STATE_MANAGER.increment_execution_count(full_path)
+                print(
+                    f"[BatchPrompts] Auto-increment: using index {actual_index} for {os.path.basename(prompt_file)}"
+                )
+            else:
+                actual_index = index
+                print(f"[BatchPrompts] Manual mode: using index {actual_index}")
+
+            # Validate file
+            is_valid, error_msg = validate_prompt_file(full_path)
+            if not is_valid:
+                self.handle_error(f"Invalid prompt file: {error_msg}")
+
+            # Load prompts (with caching)
+            cache_key = full_path
+            if reload_file or cache_key not in self._prompt_cache:
+                prompts = load_prompts_from_file(full_path)
+                if not prompts:
+                    self.handle_error(f"No prompts found in file: {prompt_file}")
+                self._prompt_cache[cache_key] = prompts
+                # Reset execution count when reloading file
+                if reload_file:
+                    STATE_MANAGER.reset_execution_count(full_path)
+                self.log_info(f"Loaded {len(prompts)} prompts from {prompt_file}")
+            else:
+                prompts = self._prompt_cache[cache_key]
+
+            # Get current prompt using the determined index
+            current_prompt, used_index = get_prompt_at_index(
+                prompts, actual_index, wrap_around
+            )
+
+            # Get next prompt
+            next_prompt_text, next_index = get_next_prompt(
+                prompts, used_index, wrap_around
+            )
+
+            # Split positive/negative if requested
+            if split_negative:
+                positive, negative = split_prompt_into_positive_negative(current_prompt)
+            else:
+                positive = current_prompt
+                negative = ""
+
+            # Get batch info
+            batch_info_dict = get_batch_info(prompts, used_index)
+            batch_info_str = (
+                f"Prompt {batch_info_dict['current_index'] + 1} of {batch_info_dict['total_prompts']} "
+                f"({batch_info_dict['percentage']:.1f}% complete)"
+            )
+
+            # Show preview if requested
+            if show_preview:
+                preview = get_prompt_preview(positive, 80)
+                self.log_info(
+                    f"Current prompt [{used_index + 1}/{len(prompts)}]: {preview}"
+                )
+
+            # No need to manually reset - the modulo operation in get_prompt_at_index handles wrapping
+
+            return (
+                positive,
+                negative,
+                current_prompt,
+                next_prompt_text,
+                used_index,
+                len(prompts),
+                batch_info_str,
+            )
+
+        except Exception as e:
+            self.handle_error(f"Error processing batch prompts: {str(e)}")
+            # Return empty values on error
+            return ("", "", "", "", 0, 0, "Error")
+
+    @classmethod
+    def IS_CHANGED(cls, **kwargs):
+        """
+        Check if node inputs have changed.
+        This ensures the node re-executes when needed.
+        """
+        # Import time to ensure unique value each check
+        import time
+
+        # Return current timestamp to guarantee the node is seen as changed
+        # This forces re-execution on every workflow run
+        return str(time.time())

kikotools/tools/batch_prompts/state_manager.py

@@ -0,0 +1,62 @@
+"""State management for batch prompts using file persistence."""
+
+import json
+import tempfile
+from pathlib import Path
+from typing import Dict, Any
+
+
+class StateManager:
+    """Manages persistent state for batch prompt execution."""
+
+    def __init__(self):
+        # Use temp directory for state files
+        self.state_dir = Path(tempfile.gettempdir()) / "comfyui_batch_prompts"
+        self.state_dir.mkdir(exist_ok=True)
+        self.state_file = self.state_dir / "execution_state.json"
+
+    def get_state(self) -> Dict[str, Any]:
+        """Load state from file."""
+        if self.state_file.exists():
+            try:
+                with open(self.state_file, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except (json.JSONDecodeError, IOError):
+                pass
+        return {}
+
+    def save_state(self, state: Dict[str, Any]):
+        """Save state to file."""
+        try:
+            with open(self.state_file, "w", encoding="utf-8") as f:
+                json.dump(state, f)
+        except Exception as e:
+            print(f"[BatchPrompts] Failed to save state: {e}")
+
+    def get_execution_count(self, file_path: str) -> int:
+        """Get execution count for a specific file."""
+        state = self.get_state()
+        counts = state.get("execution_counts", {})
+        return counts.get(file_path, 0)
+
+    def increment_execution_count(self, file_path: str) -> int:
+        """Increment and return execution count for a file."""
+        state = self.get_state()
+        counts = state.get("execution_counts", {})
+        current = counts.get(file_path, 0)
+        counts[file_path] = current + 1
+        state["execution_counts"] = counts
+        self.save_state(state)
+        return current
+
+    def reset_execution_count(self, file_path: str):
+        """Reset execution count for a file."""
+        state = self.get_state()
+        counts = state.get("execution_counts", {})
+        counts[file_path] = 0
+        state["execution_counts"] = counts
+        self.save_state(state)
+
+
+# Global state manager instance
+STATE_MANAGER = StateManager()

kikotools/tools/display_any/logic.py

@@ -1,6 +1,6 @@
 """Logic for DisplayAny node - displays any input value or tensor shape."""
 
-from typing import Any, List, Union
+from typing import Any, List
 
 
 def get_tensor_shapes(input_value: Any) -> List[List[int]]:
@@ -54,7 +54,7 @@ def format_display_value(input_value: Any, mode: str = "raw value") -> str:
 
         if isinstance(input_value, (dict, list)):
             return json.dumps(input_value, indent=2)
-    except:
+    except (TypeError, ValueError):
         pass
 
     return str(input_value)

kikotools/tools/display_any/node.py

@@ -1,6 +1,6 @@
 """DisplayAny node for ComfyUI - displays any input value or tensor information."""
 
-from typing import Any, Dict, Tuple
+from typing import Any, Dict
 
 from ...base import ComfyAssetsBaseNode
 from .logic import format_display_value, validate_display_mode
@@ -38,7 +38,7 @@ class DisplayAnyNode(ComfyAssetsBaseNode):
         return True
 
     RETURN_TYPES = ("STRING",)
-    CATEGORY = "ComfyAssets/👁️ Display"
+    CATEGORY = "🫶 ComfyAssets/👁️ Display"
     RETURN_NAMES = ("display_text",)
     FUNCTION = "display"
     OUTPUT_NODE = True  # This node displays output in the UI

kikotools/tools/display_text/node.py

@@ -19,7 +19,7 @@ class DisplayTextNode(ComfyAssetsBaseNode):
     RETURN_NAMES = ("text",)
     OUTPUT_NODE = True
     FUNCTION = "display_text"
-    CATEGORY = "ComfyAssets/👁️ Display"
+    CATEGORY = "🫶 ComfyAssets/👁️ Display"
 
     DESCRIPTION = """
 Displays text in the UI with a copy-to-clipboard feature.

kikotools/tools/embedding_autocomplete/node.py

@@ -17,7 +17,7 @@ class KikoEmbeddingAutocomplete:
     """Node that provides embedding autocomplete functionality."""
 
     DISPLAY_NAME = "🫶 Embedding Autocomplete Settings"
-    CATEGORY = "ComfyAssets"
+    CATEGORY = "🫶 ComfyAssets"
 
     # Settings definition for the settings registry
     SETTINGS = {

kikotools/tools/empty_latent_batch/node.py

@@ -93,14 +93,14 @@ class EmptyLatentBatchNode(ComfyAssetsBaseNode):
             }
         }
 
-    RETURN_TYPES = ("LATENT", "INT", "INT")
-    RETURN_NAMES = ("latent", "width", "height")
+    RETURN_TYPES = ("LATENT", "INT", "INT", "INT")
+    RETURN_NAMES = ("latent", "width", "height", "batch_size")
     FUNCTION = "create_empty_latent"
-    CATEGORY = "ComfyAssets/📦 Latents"
+    CATEGORY = "🫶 ComfyAssets/📦 Latents"
 
     def create_empty_latent(
         self, preset: str, width: int, height: int, batch_size: int
-    ) -> Tuple[Dict[str, torch.Tensor], int, int]:
+    ) -> Tuple[Dict[str, torch.Tensor], int, int, int]:
         """
         Create empty latent tensor with specified dimensions and batch size.
 
@@ -111,7 +111,7 @@ class EmptyLatentBatchNode(ComfyAssetsBaseNode):
             batch_size: Number of latents in the batch
 
         Returns:
-            Tuple containing (latent dictionary with 'samples' tensor, width, height)
+            Tuple containing (latent dict, width, height, batch_size)
         """
         try:
             # Extract original preset name from formatted string if needed
@@ -160,7 +160,7 @@ class EmptyLatentBatchNode(ComfyAssetsBaseNode):
                 f"(pixel dims: {final_width}×{final_height})"
             )
 
-            return (latent_dict, final_width, final_height)
+            return (latent_dict, final_width, final_height, batch_size)
 
         except Exception as e:
             # Handle any unexpected errors gracefully

kikotools/tools/gemini_prompt/.gemini_models_cache.json

@@ -86,4 +86,4 @@
     "gemini-2.5-flash-lite": "Gemini 2.5 Flash-Lite"
   },
   "timestamp": 1754568195.1098156
-}
+}

kikotools/tools/gemini_prompt/logic.py

@@ -30,7 +30,7 @@ def tensor_to_pil(tensor: np.ndarray) -> Image.Image:
     image_array = (tensor * 255).astype(np.uint8)
 
     # Convert to PIL
-    return Image.fromarray(image_array, mode="RGB")
+    return Image.fromarray(image_array)
 
 
 def image_to_base64(image: Image.Image, format: str = "PNG") -> str:
@@ -65,7 +65,7 @@ def get_api_key() -> Optional[str]:
                 os.path.dirname(__file__), "..", "..", "..", "gemini_config.json"
             )
             if os.path.exists(config_path):
-                with open(config_path, "r") as f:
+                with open(config_path, "r", encoding="utf-8") as f:
                     config = json.load(f)
                     api_key = config.get("api_key")
         except Exception:

kikotools/tools/gemini_prompt/models.py

@@ -154,7 +154,7 @@ def _load_cache() -> Optional[Dict]:
         return None
 
     try:
-        with open(CACHE_FILE, "r") as f:
+        with open(CACHE_FILE, "r", encoding="utf-8") as f:
             data = json.load(f)
 
         # Check if cache is expired
@@ -176,7 +176,7 @@ def _save_cache(models: List[str], descriptions: Dict[str, str]) -> None:
             "timestamp": time.time(),
         }
 
-        with open(CACHE_FILE, "w") as f:
+        with open(CACHE_FILE, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
     except Exception as e:
         logger.warning(f"Failed to save cache: {e}")

kikotools/tools/gemini_prompt/node.py

@@ -51,7 +51,7 @@ class GeminiPromptNode(ComfyAssetsBaseNode):
     RETURN_TYPES = ("STRING", "STRING")
     RETURN_NAMES = ("prompt", "negative_prompt")
     FUNCTION = "generate_prompt"
-    CATEGORY = "ComfyAssets/🧠 Prompts"
+    CATEGORY = "🫶 ComfyAssets/🧠 Prompts"
 
     DESCRIPTION = """
 Analyzes images using Google's Gemini AI to generate optimized prompts.

kikotools/tools/image_scale_down_by/node.py

@@ -35,7 +35,7 @@ class ImageScaleDownByNode(ComfyAssetsBaseNode):
         }
 
     RETURN_TYPES = ("IMAGE",)
-    CATEGORY = "ComfyAssets/🖼️ Resolution"
+    CATEGORY = "🫶 ComfyAssets/🖼️ Resolution"
     RETURN_NAMES = ("images",)
     FUNCTION = "scale_down"
 

kikotools/tools/image_to_multiple_of/node.py

@@ -36,7 +36,7 @@ class ImageToMultipleOfNode(ComfyAssetsBaseNode):
         }
 
     RETURN_TYPES = ("IMAGE",)
-    CATEGORY = "ComfyAssets/🖼️ Resolution"
+    CATEGORY = "🫶 ComfyAssets/🖼️ Resolution"
     RETURN_NAMES = ("image",)
     FUNCTION = "process"
 

kikotools/tools/kiko_film_grain/logic.py

@@ -100,13 +100,15 @@ def generate_grain_texture(
     Returns:
         Grain texture tensor of shape [B, H/scale, W/scale, 3]
     """
-    torch.manual_seed(seed)
+    # Local generator: never touch the global RNG state
+    generator = torch.Generator()
+    generator.manual_seed(int(seed))
 
     grain_height = max(1, int(height / scale))
     grain_width = max(1, int(width / scale))
 
     # Generate random noise
-    grain = torch.rand(batch_size, grain_height, grain_width, 3)
+    grain = torch.rand(batch_size, grain_height, grain_width, 3, generator=generator)
 
     return grain
 
@@ -140,7 +142,8 @@ def apply_film_grain(
     Returns:
         Image with film grain applied
     """
-    if strength == 0.0:
+    # Only short-circuit when nothing at all would change (toe still applies)
+    if strength == 0.0 and toe == 0.0:
         return image
 
     # Handle empty batch

kikotools/tools/kiko_film_grain/node.py

@@ -75,7 +75,7 @@ class KikoFilmGrainNode(ComfyAssetsBaseNode):
                     {
                         "default": 0,
                         "min": 0,
-                        "max": 0xFFFFFFFFFFFFFFFF,
+                        "max": 0xFFFFFFFF,  # 2**32 - 1
                         "description": "Random seed for grain pattern generation",
                     },
                 ),
@@ -85,7 +85,7 @@ class KikoFilmGrainNode(ComfyAssetsBaseNode):
     RETURN_TYPES = ("IMAGE",)
     RETURN_NAMES = ("image",)
     FUNCTION = "apply_grain"
-    CATEGORY = "ComfyAssets/image"
+    CATEGORY = "🫶 ComfyAssets/💾 Images"
     DESCRIPTION = "Apply realistic film grain effect with customizable parameters"
 
     def apply_grain(

kikotools/tools/kiko_purge_vram/__init__.py

@@ -0,0 +1,3 @@
+from .node import KikoPurgeVRAM
+
+__all__ = ["KikoPurgeVRAM"]

kikotools/tools/kiko_purge_vram/logic.py

@@ -0,0 +1,130 @@
+import gc
+from typing import Dict, Tuple
+
+try:
+    import torch
+
+    TORCH_AVAILABLE = True
+except ImportError:
+    TORCH_AVAILABLE = False
+
+try:
+    import comfy.model_management as mm
+
+    COMFY_AVAILABLE = True
+except ImportError:
+    COMFY_AVAILABLE = False
+
+
+def get_memory_stats() -> Dict[str, float]:
+    stats = {
+        "cuda_available": False,
+        "free_mb": 0,
+        "total_mb": 0,
+        "used_mb": 0,
+        "used_percent": 0,
+    }
+
+    if TORCH_AVAILABLE and torch.cuda.is_available():
+        stats["cuda_available"] = True
+        free, total = torch.cuda.mem_get_info()
+        free_mb = free / (1024 * 1024)
+        total_mb = total / (1024 * 1024)
+        used_mb = total_mb - free_mb
+
+        stats["free_mb"] = free_mb
+        stats["total_mb"] = total_mb
+        stats["used_mb"] = used_mb
+        stats["used_percent"] = (used_mb / total_mb) * 100 if total_mb > 0 else 0
+
+    return stats
+
+
+def purge_memory(mode: str = "soft", unload_models: bool = False) -> float:
+    before_stats = get_memory_stats()
+
+    if mode == "soft":
+        # Basic garbage collection and cache clearing
+        gc.collect()
+        if TORCH_AVAILABLE and torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+    elif mode == "aggressive":
+        # Multiple passes of garbage collection with full cache clearing
+        gc.collect()
+        gc.collect()
+        if TORCH_AVAILABLE and torch.cuda.is_available():
+            torch.cuda.synchronize()
+            torch.cuda.empty_cache()
+            torch.cuda.ipc_collect()
+
+    elif mode == "models_only":
+        # Only unload models
+        if COMFY_AVAILABLE:
+            mm.unload_all_models()
+            mm.soft_empty_cache()
+        gc.collect()
+
+    elif mode == "cache_only":
+        # Only clear cache without garbage collection
+        if TORCH_AVAILABLE and torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+    # Handle model unloading for non-model-specific modes
+    if unload_models and mode not in ["models_only"]:
+        if COMFY_AVAILABLE:
+            mm.unload_all_models()
+            mm.soft_empty_cache()
+
+    after_stats = get_memory_stats()
+    freed_mb = before_stats["used_mb"] - after_stats["used_mb"]
+
+    return max(0, freed_mb)
+
+
+def format_memory_report(
+    before: Dict[str, float], after: Dict[str, float], mode: str, elapsed_ms: float
+) -> str:
+    if not before.get("cuda_available", True):
+        return (
+            "Memory Purge Report\n"
+            "-------------------\n"
+            "CUDA not available - CPU memory management only\n"
+            f"Mode: {mode}\n"
+            f"Time: {elapsed_ms:.1f}ms"
+        )
+
+    freed_mb = before["used_mb"] - after["used_mb"]
+
+    report = [
+        "Memory Purge Report",
+        "-------------------",
+        f"Mode: {mode}",
+        f"Memory Freed: {freed_mb:.1f} MB",
+        f"Before: {before['used_mb']:.1f} MB used ({before['used_percent']:.1f}%)",
+        f"After: {after['used_mb']:.1f} MB used ({after['used_percent']:.1f}%)",
+        f"Time: {elapsed_ms:.1f}ms",
+    ]
+
+    return "\n".join(report)
+
+
+def should_purge(threshold_mb: int) -> Tuple[bool, str]:
+    if threshold_mb <= 0:
+        return True, ""
+
+    stats = get_memory_stats()
+
+    if not stats["cuda_available"]:
+        return True, "CUDA not available, proceeding with CPU memory management"
+
+    if stats["used_mb"] >= threshold_mb:
+        return (
+            True,
+            f"Memory usage ({stats['used_mb']:.1f} MB) exceeds threshold ({threshold_mb} MB)",
+        )
+    else:
+        return (
+            False,
+            f"Memory usage ({stats['used_mb']:.1f} MB) below threshold ({threshold_mb} MB)",
+        )

kikotools/tools/kiko_purge_vram/node.py

@@ -0,0 +1,107 @@
+import time
+from typing import Any, Dict, Tuple
+
+try:
+    from ...base.base_node import ComfyAssetsBaseNode as BaseNode
+    from ...base.any_type import AnyType
+except ImportError:
+    # Fallback for testing environment
+    from kikotools.base.base_node import ComfyAssetsBaseNode as BaseNode
+    from kikotools.base.any_type import AnyType
+from .logic import get_memory_stats, purge_memory, format_memory_report, should_purge
+
+any_type = AnyType("*")
+
+
+class KikoPurgeVRAM(BaseNode):
+    @classmethod
+    def INPUT_TYPES(cls) -> Dict[str, Any]:
+        return {
+            "required": {
+                "anything": (any_type, {}),
+                "mode": (
+                    ["soft", "aggressive", "models_only", "cache_only"],
+                    {
+                        "default": "soft",
+                        "tooltip": "Purge mode: soft (basic), aggressive (thorough), models_only (unload models), cache_only (clear cache)",
+                    },
+                ),
+                "report_memory": (
+                    "BOOLEAN",
+                    {
+                        "default": True,
+                        "tooltip": "Generate detailed memory usage report",
+                    },
+                ),
+            },
+            "optional": {
+                "memory_threshold_mb": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 48000,
+                        "step": 100,
+                        "tooltip": "Only purge if memory usage exceeds this threshold (0 = always purge)",
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = (any_type, "STRING")
+    RETURN_NAMES = ("passthrough", "memory_report")
+    FUNCTION = "purge_vram"
+    CATEGORY = "🫶 ComfyAssets/🛠️ Utils"
+    OUTPUT_NODE = True
+    DESCRIPTION = "Purge VRAM to free up GPU memory during workflow execution. Passes through any input unchanged."
+
+    @classmethod
+    def IS_CHANGED(cls, *args: Any, **kwargs: Any) -> float:
+        """Always re-run: a purge must never be skipped by ComfyUI caching."""
+        return float("nan")
+
+    def purge_vram(
+        self,
+        anything: Any,
+        mode: str,
+        report_memory: bool,
+        memory_threshold_mb: int = 0,
+    ) -> Tuple[Any, str]:
+        # Check if we should purge based on threshold
+        should_run, threshold_msg = should_purge(memory_threshold_mb)
+
+        if not should_run:
+            if report_memory:
+                return anything, f"Memory purge skipped: {threshold_msg}"
+            else:
+                return anything, ""
+
+        # Get before stats
+        before_stats = get_memory_stats() if report_memory else None
+        start_time = time.time()
+
+        # Determine if we should unload models
+        unload_models = mode in ["models_only", "aggressive"]
+
+        # Perform memory purge
+        purge_memory(mode=mode, unload_models=unload_models)
+
+        # Calculate elapsed time
+        elapsed_ms = (time.time() - start_time) * 1000
+
+        # Generate report if requested
+        if report_memory:
+            after_stats = get_memory_stats()
+            report = format_memory_report(before_stats, after_stats, mode, elapsed_ms)
+            if threshold_msg and memory_threshold_mb > 0:
+                report = f"{threshold_msg}\n\n{report}"
+        else:
+            report = ""
+
+        # Pass through the input unchanged
+        return anything, report
+
+
+NODE_CLASS_MAPPINGS = {"KikoPurgeVRAM": KikoPurgeVRAM}
+
+NODE_DISPLAY_NAME_MAPPINGS = {"KikoPurgeVRAM": "Kiko Purge VRAM"}

kikotools/tools/kiko_save_image/logic.py

@@ -10,7 +10,6 @@ from PIL import Image
 from PIL.PngImagePlugin import PngInfo
 import torch
 from typing import Dict, List, Any, Optional, Tuple
-import time
 
 try:
     import folder_paths
@@ -22,9 +21,70 @@ except ImportError:
             return "./output"
 
 
+def get_next_counter(output_dir: str, prefix: str) -> int:
+    """
+    Get next available counter value from persistent counter file
+
+    This prevents file overwrites when the node is called multiple times
+    within the same second by maintaining a persistent counter.
+
+    Args:
+        output_dir: Directory to store counter file
+        prefix: Filename prefix to create unique counter per prefix
+
+    Returns:
+        Next available counter value
+    """
+    # Create a safe counter filename
+    safe_prefix = "".join(c for c in prefix if c.isalnum() or c in "._-")
+    counter_file = os.path.join(output_dir, f".{safe_prefix}_counter.txt")
+
+    # Read current counter
+    counter = 0
+    if os.path.exists(counter_file):
+        try:
+            with open(counter_file, "r", encoding="utf-8") as f:
+                content = f.read().strip()
+                counter = int(content) if content else 0
+        except (ValueError, IOError):
+            # If file is corrupted or unreadable, start from 0
+            counter = 0
+
+    # Increment counter
+    counter += 1
+
+    # Save updated counter
+    try:
+        with open(counter_file, "w", encoding="utf-8") as f:
+            f.write(str(counter))
+    except IOError:
+        # If we can't write the counter file, continue anyway
+        # Better to risk overwrites than to fail completely
+        pass
+
+    return counter
+
+
+def _ensure_inside_output_dir(
+    folder: str, output_dir: str, prefix_dir: str, subfolder: str
+) -> None:
+    """Raise ValueError unless folder resolves to a location inside output_dir."""
+    real_root = os.path.realpath(output_dir)
+    real_folder = os.path.realpath(folder)
+    try:
+        inside = os.path.commonpath([real_root, real_folder]) == real_root
+    except ValueError:  # e.g. different drives on Windows
+        inside = False
+    if not inside:
+        raise ValueError(
+            "Resolved output folder is outside the output directory "
+            f"(prefix directory {prefix_dir!r}, subfolder {subfolder!r})"
+        )
+
+
 def get_save_image_path(
     filename_prefix: str,
-    batch_number: int,
+    counter: int,
     format_ext: str,
     output_dir: str,
     subfolder: str = "",
@@ -34,16 +94,21 @@ def get_save_image_path(
 
     Args:
         filename_prefix: Base filename prefix
-        batch_number: Batch index for multiple images
+        counter: Persistent counter to ensure unique filenames
         format_ext: File extension (.png, .jpg, .webp)
         output_dir: Output directory path
         subfolder: Optional subfolder within output directory
 
     Returns:
-        Tuple of (full_path, relative_filename)
+        Tuple of (full_path, preview_filename, relative_subfolder)
     """
     # Split filename_prefix into directory path and actual filename prefix
     # This allows for directory structures like "kittybear/anime/images/kittybear"
+    if os.path.isabs(filename_prefix) or os.path.isabs(subfolder or ""):
+        raise ValueError(
+            "Absolute paths are not allowed in filename_prefix or subfolder: "
+            f"{filename_prefix!r}"
+        )
     prefix_dir = os.path.dirname(filename_prefix)
     prefix_name = os.path.basename(filename_prefix)
 
@@ -53,9 +118,10 @@ def get_save_image_path(
     )  # Only sanitize problematic chars for filenames
     safe_prefix = "".join(c for c in safe_prefix if c.isalnum() or c in "._-")
 
-    # Create unique filename with timestamp to avoid conflicts
-    timestamp = int(time.time())
-    filename = f"{safe_prefix}_{timestamp:010d}_{batch_number:05d}{format_ext}"
+    # Create unique filename with counter to avoid conflicts
+    # Using counter instead of timestamp+batch_number prevents overwrites
+    # when multiple images are processed separately
+    filename = f"{safe_prefix}_{counter:05d}{format_ext}"
 
     # Handle subfolder and prefix directory (but not the filename part)
     path_components = []
@@ -70,6 +136,9 @@ def get_save_image_path(
 
     full_output_folder = os.path.join(*path_components)
 
+    # Reject anything that would resolve outside the output directory
+    _ensure_inside_output_dir(full_output_folder, output_dir, prefix_dir, subfolder)
+
     # Ensure directory exists
     os.makedirs(full_output_folder, exist_ok=True)
 
@@ -221,7 +290,7 @@ def process_image_batch(
     popup: bool = True,
     prompt: Optional[Dict] = None,
     extra_pnginfo: Optional[Dict] = None,
-) -> List[Dict[str, Any]]:
+) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
     """
     Process and save a batch of images with specified format settings
 
@@ -237,7 +306,7 @@ def process_image_batch(
         extra_pnginfo: Additional PNG metadata
 
     Returns:
-        List of saved image information dicts
+        Tuple of (ComfyUI preview result dicts, enhanced info dicts)
     """
     # Get output directory
     output_dir = folder_paths.get_output_directory()
@@ -262,13 +331,17 @@ def process_image_batch(
     results = []
     enhanced_data = []
 
-    for batch_number, image_tensor in enumerate(images):
+    for image_tensor in images:
         # Convert tensor to PIL Image
         img = convert_tensor_to_pil(image_tensor)
 
-        # Generate save path
+        # Get next counter value to ensure unique filenames
+        # This counter persists across node calls, preventing overwrites
+        counter = get_next_counter(output_dir, filename_prefix)
+
+        # Generate save path with persistent counter
         filepath, preview_filename, relative_subfolder = get_save_image_path(
-            filename_prefix, batch_number, format_ext, output_dir, ""
+            filename_prefix, counter, format_ext, output_dir, ""
         )
 
         # Save with format-specific settings

kikotools/tools/kiko_save_image/node.py

@@ -95,7 +95,7 @@ class KikoSaveImageNode(ComfyAssetsBaseNode):
         }
 
     RETURN_TYPES = ()
-    CATEGORY = "ComfyAssets/💾 Images"
+    CATEGORY = "🫶 ComfyAssets/💾 Images"
     FUNCTION = "save_images"
     OUTPUT_NODE = True
 

kikotools/tools/kiko_workflow_timer/__init__.py

@@ -0,0 +1,10 @@
+"""
+KikoWorkflow Timer - Display real-time execution timer for ComfyUI workflows.
+
+Provides a visual timer that tracks workflow execution duration with
+millisecond precision.
+"""
+
+from .node import KikoWorkflowTimerNode
+
+__all__ = ["KikoWorkflowTimerNode"]

kikotools/tools/kiko_workflow_timer/node.py

@@ -0,0 +1,52 @@
+"""
+KikoWorkflow Timer Node
+
+A display-only node that shows real-time execution timing for ComfyUI workflows.
+The timer is managed entirely on the frontend via WebSocket events.
+"""
+
+from ...base import ComfyAssetsBaseNode
+
+
+class KikoWorkflowTimerNode(ComfyAssetsBaseNode):
+    """
+    A UI node that displays a real-time timer for workflow execution.
+
+    The timer starts when execution begins and stops when the workflow
+    completes, showing the total elapsed time in MM:SS:mmm format.
+
+    This is a display-only node with no inputs or outputs - all timing
+    logic is handled by the JavaScript frontend via WebSocket events.
+    """
+
+    DISPLAY_NAME = "Workflow Timer"
+    CATEGORY = "🫶 ComfyAssets/🛠️ Utils"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {},
+            "hidden": {
+                "prompt": "PROMPT",
+                "unique_id": "UNIQUE_ID",
+            },
+        }
+
+    RETURN_TYPES = ()
+    FUNCTION = "execute"
+    OUTPUT_NODE = True
+
+    def execute(self, **kwargs):
+        """
+        Execute method - returns empty since this is a display-only node.
+
+        The actual timer functionality is handled entirely by the JavaScript
+        frontend which hooks into ComfyUI's WebSocket events.
+
+        Args:
+            **kwargs: Hidden parameters (prompt, unique_id)
+
+        Returns:
+            Empty dict - no outputs
+        """
+        return {}

kikotools/tools/local_image_loader/__init__.py

@@ -0,0 +1,13 @@
+"""Local Image Loader tool for KikoTools."""
+
+from .node import LocalImageLoaderNode
+
+NODE_CLASS_MAPPINGS = {
+    "KikoLocalImageLoader": LocalImageLoaderNode,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "KikoLocalImageLoader": "Local Image Loader",
+}
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS"]

kikotools/tools/local_image_loader/config.json

@@ -0,0 +1,12 @@
+{
+    "last_path": "/home/vito/ai-apps/ComfyUI/output/vids",
+    "saved_paths": [
+        "/home/vito/ai-apps/ComfyUI-3.12/output/2025-05-01",
+        "/home/vito/ai-apps/ComfyUI-3.12/output/",
+        "/home/vito/Downloads/vito",
+        "/home/vito/ai-apps/ComfyUI/output/2025-06-08",
+        "/home/vito/ai-apps/ComfyUI/output",
+        "/home/vito/Downloads",
+        "/home/vito/Downloads/images"
+    ]
+}

kikotools/tools/local_image_loader/logic.py

@@ -0,0 +1,344 @@
+"""Core logic for Local Image Loader."""
+
+import os
+import json
+import torch
+import numpy as np
+from PIL import Image
+from typing import Tuple, Dict, Any, List, Optional, Iterable
+
+
+def get_supported_extensions() -> Dict[str, List[str]]:
+    """Get supported file extensions by type."""
+    return {
+        "image": [".jpg", ".jpeg", ".png", ".bmp", ".gif", ".webp"],
+        "video": [".mp4", ".webm", ".mov", ".mkv", ".avi"],
+        "audio": [".mp3", ".wav", ".ogg", ".flac"],
+    }
+
+
+def resolve_path(path: Any) -> Optional[str]:
+    """Resolve a user supplied path with realpath (symlinks and ``..``).
+
+    Returns None for anything that is not a usable non-empty string.
+    """
+    if not isinstance(path, str) or not path or "\0" in path:
+        return None
+    return os.path.realpath(path)
+
+
+def is_within_roots(path: Any, roots: Iterable[Any]) -> bool:
+    """Return True if the resolved path is inside (or equal to) one of the roots.
+
+    Uses os.path.commonpath on realpath-resolved values, so sibling
+    directories sharing a string prefix, ``..`` and symlinks cannot escape.
+    """
+    real = resolve_path(path)
+    if real is None:
+        return False
+    for root in roots:
+        real_root = resolve_path(root)
+        if real_root is None:
+            continue
+        try:
+            if os.path.commonpath([real, real_root]) == real_root:
+                return True
+        except ValueError:  # different drives / mixed absolute and relative
+            continue
+    return False
+
+
+def is_too_broad_root(path: Any, home: Optional[str] = None) -> bool:
+    """Return True if path is unusable or too broad to be a saved root.
+
+    Refuses filesystem/drive roots, the home directory itself and any
+    ancestor of it (e.g. /home), since those would expose every media file
+    a user owns. Folders inside home are fine.
+    """
+    real = resolve_path(path)
+    if real is None:
+        return True
+    if os.path.dirname(real) == real:  # "/" or a drive root like "C:\\"
+        return True
+    real_home = os.path.realpath(home or os.path.expanduser("~"))
+    try:
+        return os.path.commonpath([real, real_home]) == real
+    except ValueError:  # different drives
+        return False
+
+
+def is_allowed_media_path(
+    path: Any, roots: Iterable[Any], kinds: Iterable[str] = ("image",)
+) -> bool:
+    """Return True if path is a media file of the given kinds inside a root.
+
+    ``kinds`` are keys of get_supported_extensions() (image/video/audio).
+    The extension is checked on the resolved path so a symlink named
+    ``x.png`` pointing at a non-media file is refused.
+    """
+    real = resolve_path(path)
+    if real is None:
+        return False
+    extensions = get_supported_extensions()
+    allowed = {e for k in kinds for e in extensions.get(k, [])}
+    if os.path.splitext(real)[1].lower() not in allowed:
+        return False
+    return is_within_roots(real, roots)
+
+
+def is_allowed_image_path(path: Any, roots: Iterable[Any]) -> bool:
+    """Return True if path is an image file located inside one of the roots."""
+    return is_allowed_media_path(path, roots, ("image",))
+
+
+def list_subdirectories(path: str, limit: int = 50) -> List[str]:
+    """List sub-directory paths (never files) for the folder picker.
+
+    If ``path`` ends with a separator, its child directories are returned;
+    otherwise sibling directories whose name starts with the last component.
+    May raise PermissionError.
+    """
+    if path.endswith(os.sep) or (os.name == "nt" and path.endswith("/")):
+        parent_dir, prefix = path, ""
+    else:
+        parent_dir = os.path.dirname(path)
+        prefix = os.path.basename(path).lower()
+        if not parent_dir:
+            return []
+
+    if not os.path.isdir(parent_dir):
+        return []
+
+    dirs = [
+        os.path.join(parent_dir, entry)
+        for entry in os.listdir(parent_dir)
+        if entry.lower().startswith(prefix)
+        and os.path.isdir(os.path.join(parent_dir, entry))
+    ]
+    dirs.sort(key=lambda x: x.lower())
+    return dirs[:limit]
+
+
+def load_image_from_path(path: str) -> Tuple[torch.Tensor, Dict[str, Any]]:
+    """
+    Load an image from the given path and convert it to a tensor.
+
+    Args:
+        path: Path to the image file
+
+    Returns:
+        Tuple of (image tensor, metadata dict)
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"File not found: {path}")
+
+    with Image.open(path) as img:
+        # Convert to appropriate format
+        if "A" in img.getbands():
+            img_out = img.convert("RGBA")
+        else:
+            img_out = img.convert("RGB")
+
+        # Convert to tensor
+        img_array = np.array(img_out).astype(np.float32) / 255.0
+        image_tensor = torch.from_numpy(img_array)[None,]
+
+        # Collect metadata
+        metadata = {
+            "filename": os.path.basename(path),
+            "width": img.width,
+            "height": img.height,
+            "mode": img.mode,
+            "format": img.format,
+        }
+
+        # Check for embedded metadata
+        if "parameters" in img.info:
+            metadata["parameters"] = img.info["parameters"]
+        if "prompt" in img.info:
+            try:
+                metadata["prompt"] = json.loads(img.info["prompt"])
+            except (json.JSONDecodeError, TypeError):
+                metadata["prompt"] = img.info["prompt"]
+        if "workflow" in img.info:
+            try:
+                metadata["workflow"] = json.loads(img.info["workflow"])
+            except (json.JSONDecodeError, TypeError):
+                metadata["workflow"] = img.info["workflow"]
+
+    return image_tensor, metadata
+
+
+def scan_directory(
+    directory: str,
+    show_videos: bool = False,
+    show_audio: bool = False,
+    sort_by: str = "name",
+    sort_order: str = "asc",
+    hide_dot_folders: bool = True,
+) -> List[Dict[str, Any]]:
+    """
+    Scan a directory for supported media files.
+
+    Args:
+        directory: Directory path to scan
+        show_videos: Include video files
+        show_audio: Include audio files
+        sort_by: Sort criteria ('name', 'date', 'size')
+        sort_order: Sort order ('asc', 'desc')
+        hide_dot_folders: Hide folders starting with a dot
+
+    Returns:
+        List of file information dictionaries
+    """
+    if not os.path.isdir(directory):
+        raise NotADirectoryError(f"Not a directory: {directory}")
+
+    extensions = get_supported_extensions()
+    items = []
+
+    for item in os.listdir(directory):
+        # Skip dot folders/files if hide_dot_folders is enabled
+        if hide_dot_folders and item.startswith("."):
+            continue
+
+        full_path = os.path.join(directory, item)
+
+        try:
+            stats = os.stat(full_path)
+            item_data = {
+                "path": full_path,
+                "name": item,
+                "mtime": stats.st_mtime,
+                "size": stats.st_size,
+            }
+
+            if os.path.isdir(full_path):
+                items.append({**item_data, "type": "dir"})
+            else:
+                ext = os.path.splitext(item)[1].lower()
+                item_type = None
+
+                if ext in extensions["image"]:
+                    item_type = "image"
+                elif show_videos and ext in extensions["video"]:
+                    item_type = "video"
+                elif show_audio and ext in extensions["audio"]:
+                    item_type = "audio"
+
+                if item_type:
+                    items.append({**item_data, "type": item_type})
+
+        except (PermissionError, FileNotFoundError):
+            continue
+
+    # Sort items
+    reverse = sort_order == "desc"
+    if sort_by == "date":
+        items.sort(key=lambda x: x["mtime"], reverse=reverse)
+    elif sort_by == "size":
+        items.sort(key=lambda x: x.get("size", 0), reverse=reverse)
+    else:  # name
+        items.sort(key=lambda x: x["name"].lower(), reverse=reverse)
+
+    # Directories first
+    items.sort(key=lambda x: x["type"] != "dir")
+
+    return items
+
+
+def search_files(
+    root_directory: str,
+    query: str,
+    show_videos: bool = False,
+    show_audio: bool = False,
+    max_results: int = 100,
+) -> List[Dict[str, Any]]:
+    """
+    Recursively search for files matching the query.
+
+    Args:
+        root_directory: Root directory to start search
+        query: Search query (case-insensitive filename match)
+        show_videos: Include video files
+        show_audio: Include audio files
+        max_results: Maximum number of results to return
+
+    Returns:
+        List of file information dictionaries
+    """
+    if not os.path.isdir(root_directory):
+        raise NotADirectoryError(f"Not a directory: {root_directory}")
+
+    if not query or len(query.strip()) == 0:
+        return []
+
+    extensions = get_supported_extensions()
+    results = []
+    query_lower = query.lower().strip()
+
+    def search_recursive(directory: str) -> None:
+        """Recursively search directory."""
+        if len(results) >= max_results:
+            return
+
+        try:
+            items = os.listdir(directory)
+        except (PermissionError, FileNotFoundError):
+            return
+
+        for item in items:
+            if len(results) >= max_results:
+                break
+
+            full_path = os.path.join(directory, item)
+
+            try:
+                # Check if item name matches query
+                if query_lower not in item.lower():
+                    # If directory, search inside
+                    if os.path.isdir(full_path):
+                        search_recursive(full_path)
+                    continue
+
+                stats = os.stat(full_path)
+                item_data = {
+                    "path": full_path,
+                    "name": item,
+                    "directory": directory,
+                    "mtime": stats.st_mtime,
+                    "size": stats.st_size,
+                }
+
+                if os.path.isdir(full_path):
+                    results.append({**item_data, "type": "dir"})
+                    # Continue searching inside matching directories
+                    search_recursive(full_path)
+                else:
+                    ext = os.path.splitext(item)[1].lower()
+                    item_type = None
+
+                    if ext in extensions["image"]:
+                        item_type = "image"
+                    elif show_videos and ext in extensions["video"]:
+                        item_type = "video"
+                    elif show_audio and ext in extensions["audio"]:
+                        item_type = "audio"
+
+                    if item_type:
+                        results.append({**item_data, "type": item_type})
+
+            except (PermissionError, FileNotFoundError):
+                continue
+
+    search_recursive(root_directory)
+
+    # Sort by name
+    results.sort(key=lambda x: x["name"].lower())
+
+    return results
+
+
+def create_empty_tensor() -> torch.Tensor:
+    """Create an empty tensor for when no image is selected."""
+    return torch.zeros(1, 1, 1, 4)

kikotools/tools/local_image_loader/node.py

@@ -0,0 +1,409 @@
+"""Local Image Loader node for ComfyUI."""
+
+import io
+import json
+import logging
+import os
+from typing import Any, Dict, List, Tuple
+
+import torch
+
+from ...base.base_node import ComfyAssetsBaseNode
+from .logic import (
+    create_empty_tensor,
+    is_allowed_image_path,
+    is_allowed_media_path,
+    is_too_broad_root,
+    is_within_roots,
+    list_subdirectories,
+    load_image_from_path,
+    resolve_path,
+    scan_directory,
+)
+
+try:
+    from aiohttp import web
+except ImportError:  # pragma: no cover - aiohttp ships with ComfyUI
+    web = None
+
+logger = logging.getLogger(__name__)
+
+MEDIA_KINDS = ("image", "video", "audio")
+MAX_PER_PAGE = 200
+DEFAULT_PER_PAGE = 50
+MAX_DIRECTORY_SUGGESTIONS = 50
+
+NODE_DIR = os.path.dirname(os.path.abspath(__file__))
+SELECTIONS_FILE = os.path.join(NODE_DIR, "selections.json")
+CONFIG_FILE = os.path.join(NODE_DIR, "config.json")
+
+
+def load_selections() -> Dict[str, Any]:
+    """Load node selections from file."""
+    if not os.path.exists(SELECTIONS_FILE):
+        return {}
+    try:
+        with open(SELECTIONS_FILE, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def save_selections(data: Dict[str, Any]) -> None:
+    """Save node selections to file."""
+    try:
+        with open(SELECTIONS_FILE, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=4, ensure_ascii=False)
+    except Exception as e:
+        logger.error("Error saving selections: %s", e)
+
+
+def load_config() -> Dict[str, Any]:
+    """Load configuration from file."""
+    if os.path.exists(CONFIG_FILE):
+        try:
+            with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            pass
+    return {}
+
+
+def save_config(data: Dict[str, Any]) -> None:
+    """Save configuration to file."""
+    try:
+        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=4)
+    except Exception as e:
+        logger.error("Error saving config: %s", e)
+
+
+def get_allowed_roots() -> List[str]:
+    """Directories whose contents may be served: saved paths + ComfyUI in/out."""
+    roots: List[str] = []
+    saved = load_config().get("saved_paths", [])
+    if isinstance(saved, list):
+        # Skip broad roots saved before save_paths refused them
+        roots.extend(
+            p for p in saved if isinstance(p, str) and p and not is_too_broad_root(p)
+        )
+    try:
+        import folder_paths
+
+        for getter in ("get_input_directory", "get_output_directory"):
+            value = getattr(folder_paths, getter)()
+            if isinstance(value, str) and value:
+                roots.append(value)
+    except Exception:  # folder_paths missing or misbehaving outside ComfyUI
+        pass
+    return roots
+
+
+class LocalImageLoaderNode(ComfyAssetsBaseNode):
+    """Node for loading images from local filesystem with a visual gallery interface."""
+
+    @classmethod
+    def INPUT_TYPES(cls) -> Dict[str, Any]:
+        """Define input types for the node."""
+        return {
+            "required": {},
+            "hidden": {"unique_id": "UNIQUE_ID"},
+        }
+
+    RETURN_TYPES = (
+        "IMAGE",
+        "STRING",
+    )
+    RETURN_NAMES = (
+        "image",
+        "info",
+    )
+    FUNCTION = "load_media"
+    CATEGORY = "🫶 ComfyAssets/💾 Images"
+
+    @classmethod
+    def IS_CHANGED(cls, **kwargs):
+        """Check if node state has changed."""
+        if os.path.exists(SELECTIONS_FILE):
+            return os.path.getmtime(SELECTIONS_FILE)
+        return float("inf")
+
+    def load_media(self, unique_id: str) -> Tuple[torch.Tensor, str]:
+        """
+        Load selected media based on node's unique ID.
+
+        Args:
+            unique_id: Unique identifier for this node instance
+
+        Returns:
+            Tuple of (image tensor, info string)
+        """
+        image_tensor = create_empty_tensor()
+        info_string = ""
+
+        selections = load_selections()
+        node_selections = selections.get(str(unique_id), {})
+
+        # Load image if selected
+        image_selection = node_selections.get("image")
+        if image_selection and image_selection.get("path"):
+            # Load the resolved path we validated, so a symlink swapped after
+            # the check can't redirect the read.
+            image_path = resolve_path(image_selection["path"])
+            if not is_allowed_image_path(image_path, get_allowed_roots()):
+                # selections.json may have been tampered with
+                logger.warning("Refusing to load disallowed path: %s", image_path)
+            elif os.path.exists(image_path):
+                try:
+                    image_tensor, metadata = load_image_from_path(image_path)
+                    info_string = json.dumps(metadata, indent=4, ensure_ascii=False)
+                except Exception as e:
+                    logger.error("Error loading image: %s", e)
+
+        return (image_tensor, info_string)
+
+
+# ---------------------------------------------------------------------------
+# API route handlers (module level so they can be tested without a server)
+# ---------------------------------------------------------------------------
+
+
+def _error(status: int, message: str):
+    return web.json_response({"status": "error", "error": message}, status=status)
+
+
+def _check_file(filepath: Any, kinds: Tuple[str, ...] = ("image",)):
+    """Validate a requested file. Returns (resolved_path, error_response)."""
+    if not isinstance(filepath, str) or not filepath or "\0" in filepath:
+        return None, web.Response(status=400)
+    real = resolve_path(filepath)
+    if not is_allowed_media_path(real, get_allowed_roots(), kinds):
+        return None, web.Response(status=403)
+    if not os.path.isfile(real):
+        return None, web.Response(status=404)
+    return real, None
+
+
+def _parse_paging(query) -> Tuple[int, int]:
+    """Parse page/per_page; raises ValueError on garbage."""
+    page = int(query.get("page", 1))
+    per_page = int(query.get("per_page", DEFAULT_PER_PAGE))
+    if page < 1:
+        raise ValueError("page must be >= 1")
+    return page, max(1, min(per_page, MAX_PER_PAGE))
+
+
+async def set_node_selection(request):
+    """Store the selected image for a node (image files in allowed roots only)."""
+    try:
+        data = await request.json()
+    except Exception:
+        return _error(400, "Invalid JSON.")
+    if not isinstance(data, dict):
+        return _error(400, "Invalid payload.")
+
+    node_id = data.get("node_id")
+    path = data.get("path")
+    media_type = data.get("type")
+    if (
+        node_id is None
+        or not isinstance(path, str)
+        or not path
+        or "\0" in path
+        or not isinstance(media_type, str)
+        or not media_type
+    ):
+        return _error(400, "Missing required data.")
+
+    # The frontend also selects video/audio; load_media only ever reads images.
+    if not is_allowed_media_path(path, get_allowed_roots(), MEDIA_KINDS):
+        return _error(403, "Path not allowed.")
+
+    selections = load_selections()
+    selections.setdefault(str(node_id), {})[media_type] = {"path": path}
+    save_selections(selections)
+    return web.json_response({"status": "ok"})
+
+
+async def get_saved_paths(request):
+    """Return saved directory paths."""
+    return web.json_response({"saved_paths": load_config().get("saved_paths", [])})
+
+
+async def save_paths(request):
+    """Persist the list of saved directory paths."""
+    try:
+        data = await request.json()
+    except Exception:
+        return _error(400, "Invalid JSON.")
+    paths = data.get("paths", []) if isinstance(data, dict) else None
+    if not isinstance(paths, list) or not all(isinstance(p, str) for p in paths):
+        return _error(400, "paths must be a list of strings.")
+    too_broad = [p for p in paths if is_too_broad_root(p)]
+    if too_broad:
+        return _error(
+            400,
+            f"Folder too broad to share: {', '.join(too_broad)}. "
+            "Pick a folder inside your home directory or another media folder.",
+        )
+    config = load_config()
+    config["saved_paths"] = paths
+    save_config(config)
+    return web.json_response({"status": "ok"})
+
+
+async def get_local_images(request):
+    """List images and sub-directories of a directory inside an allowed root."""
+    query = request.query
+    directory = query.get("directory", "")
+    if not directory or "\0" in directory:
+        return _error(400, "Directory is required.")
+    try:
+        page, per_page = _parse_paging(query)
+    except ValueError:
+        return _error(400, "Invalid page or per_page.")
+
+    if not is_within_roots(directory, get_allowed_roots()):
+        return _error(403, "Directory not allowed.")
+    real = resolve_path(directory)
+    if not os.path.isdir(real):
+        return _error(404, "Directory not found.")
+
+    # Normalize path (trailing slashes etc.) but keep the user-visible spelling
+    directory = os.path.normpath(directory)
+
+    config = load_config()
+    config["last_path"] = directory
+    save_config(config)
+
+    show_videos = query.get("show_videos", "false").lower() == "true"
+    show_audio = query.get("show_audio", "false").lower() == "true"
+    hide_dot_folders = query.get("hide_dot_folders", "true").lower() == "true"
+
+    try:
+        items = scan_directory(
+            directory,
+            show_videos,
+            show_audio,
+            query.get("sort_by", "name"),
+            query.get("sort_order", "asc"),
+            hide_dot_folders,
+        )
+    except Exception:
+        logger.exception("Error scanning directory %s", directory)
+        return _error(500, "Error reading directory.")
+
+    # Do not offer navigation above the allowed roots
+    parent_directory = os.path.dirname(directory)
+    if parent_directory == directory or not is_within_roots(
+        parent_directory, get_allowed_roots()
+    ):
+        parent_directory = None
+
+    start = (page - 1) * per_page
+    return web.json_response(
+        {
+            "items": items[start : start + per_page],
+            "total_pages": (len(items) + per_page - 1) // per_page,
+            "current_page": page,
+            "current_directory": directory,
+            "parent_directory": parent_directory,
+        }
+    )
+
+
+async def get_last_path(request):
+    """Return the last used directory path."""
+    return web.json_response({"last_path": load_config().get("last_path", "")})
+
+
+async def list_directories(request):
+    """List directory names for the folder-picker autocomplete.
+
+    Trade-off: this is how users browse to a location that is not yet a saved
+    root, so it is intentionally NOT restricted to the allowed roots. It only
+    ever returns directory paths (never files), capped at
+    MAX_DIRECTORY_SUGGESTIONS; file contents stay protected by the root and
+    extension checks on every other route.
+    """
+    path = request.query.get("path", "")
+    if "\0" in path:
+        return web.json_response({"directories": []})
+
+    try:
+        if not path:
+            if os.name == "nt":
+                import string
+
+                drives = [
+                    f"{d}:\\"
+                    for d in string.ascii_uppercase
+                    if os.path.exists(f"{d}:\\")
+                ]
+                return web.json_response({"directories": drives})
+            return web.json_response({"directories": [os.sep]})
+
+        dirs = list_subdirectories(os.path.expanduser(path), MAX_DIRECTORY_SUGGESTIONS)
+        return web.json_response({"directories": dirs})
+    except PermissionError:
+        return web.json_response({"directories": [], "error": "Permission denied"})
+    except Exception:
+        logger.exception("Error listing directories for %s", path)
+        return web.json_response(
+            {"directories": [], "error": "Error listing directories"}
+        )
+
+
+async def get_thumbnail(request):
+    """Return a thumbnail of an allowed image."""
+    real, error = _check_file(request.query.get("filepath"))
+    if error is not None:
+        return error
+
+    try:
+        from PIL import Image
+
+        with Image.open(real) as img:
+            has_alpha = img.mode == "RGBA" or (
+                img.mode == "P" and "transparency" in img.info
+            )
+            img = img.convert("RGBA") if has_alpha else img.convert("RGB")
+            img.thumbnail([320, 320], Image.LANCZOS)
+
+            buffer = io.BytesIO()
+            fmt, content_type = (
+                ("PNG", "image/png") if has_alpha else ("JPEG", "image/jpeg")
+            )
+            img.save(buffer, format=fmt, quality=90 if fmt == "JPEG" else None)
+        return web.Response(body=buffer.getvalue(), content_type=content_type)
+    except Exception:
+        logger.exception("Error generating thumbnail for %s", real)
+        return web.Response(status=500)
+
+
+async def view_image(request):
+    """Serve a full-size allowed media file (image, video or audio)."""
+    real, error = _check_file(request.query.get("filepath"), MEDIA_KINDS)
+    if error is not None:
+        return error
+    return web.FileResponse(real)
+
+
+# Setup API routes
+try:
+    import server
+
+    prompt_server = server.PromptServer.instance
+    _routes = prompt_server.routes
+    _prefix = "/kiko_local_image_loader"
+    _routes.post(f"{_prefix}/set_node_selection")(set_node_selection)
+    _routes.get(f"{_prefix}/get_saved_paths")(get_saved_paths)
+    _routes.post(f"{_prefix}/save_paths")(save_paths)
+    _routes.get(f"{_prefix}/images")(get_local_images)
+    _routes.get(f"{_prefix}/get_last_path")(get_last_path)
+    _routes.get(f"{_prefix}/list_directories")(list_directories)
+    _routes.get(f"{_prefix}/thumbnail")(get_thumbnail)
+    _routes.get(f"{_prefix}/view")(view_image)
+except ImportError:
+    # Server not available during testing
+    pass

kikotools/tools/local_image_loader/selections.json

@@ -0,0 +1,87 @@
+{
+    "57": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI-3.12/output/2025-05-01/HiDream_00001_.png"
+        }
+    },
+    "58": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI-3.12/output/CharacterName_00016_.png"
+        }
+    },
+    "18": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/vids/KikoSave_00005.png"
+        }
+    },
+    "445": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/ComfyUI_00002_.png"
+        }
+    },
+    "23": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/Z_Image_Char/Image_00098_.png"
+        }
+    },
+    "69": {
+        "image": {
+            "path": "/home/vito/Downloads/KikoSave_00086.png"
+        }
+    },
+    "52": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/kiko/XXX/images/kiko_00038_.png"
+        }
+    },
+    "38": {
+        "image": {
+            "path": "/home/vito/Downloads/vito/IMG_20160422_163419.jpg"
+        }
+    },
+    "170": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/Z_Image_Char/Image_00326_.png"
+        }
+    },
+    "214": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/Z_Image_Char/Image_00329_.png"
+        }
+    },
+    "299": {
+        "image": {
+            "path": "/home/vito/Downloads/images/KikoSave_00016.png"
+        }
+    },
+    "527": {
+        "image": {
+            "path": "/home/vito/Downloads/ComfyUI_temp_sktzg_00012_.png"
+        }
+    },
+    "522": {
+        "image": {
+            "path": "/home/vito/Downloads/KikoSave_00086.png"
+        }
+    },
+    "517": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/vids/KikoSave_00005.png"
+        }
+    },
+    "144": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/2025-04-24/ComfyUI_00002_.png"
+        }
+    },
+    "569": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/vids/KikoSave_00008.png"
+        }
+    },
+    "136": {
+        "image": {
+            "path": "/home/vito/ai-apps/ComfyUI/output/vids/KikoSave_00005.png"
+        }
+    }
+}

kikotools/tools/model_downloader/__init__.py

@@ -0,0 +1,13 @@
+"""Model Downloader Tool for ComfyUI-KikoTools
+
+Downloads models from CivitAI, HuggingFace, and custom URLs.
+"""
+
+from .node import ModelDownloaderNode
+
+__all__ = ["ModelDownloaderNode"]
+
+# Node registration
+NODE_CLASS_MAPPINGS = {"KikoModelDownloader": ModelDownloaderNode}
+
+NODE_DISPLAY_NAME_MAPPINGS = {"KikoModelDownloader": "Model Downloader 🌐"}

kikotools/tools/model_downloader/base.py

@@ -0,0 +1,483 @@
+"""Base downloader class with common functionality"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Callable, List, Optional, Sequence, Union
+from urllib.parse import urlparse, unquote
+import logging
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+
+logger = logging.getLogger(__name__)
+
+DOWNLOAD_TIMEOUT = 60  # seconds, applied to every network operation
+CHUNK_SIZE = 1638400
+USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
+ALLOWED_SCHEMES = ("http", "https")
+PART_SUFFIX = ".part"
+# Only model weights and inert data files may be written; never code.
+ALLOWED_FILE_EXTENSIONS = frozenset(
+    {
+        ".safetensors",
+        ".sft",
+        ".ckpt",
+        ".pt",
+        ".pt2",
+        ".pth",
+        ".bin",
+        ".gguf",
+        ".onnx",
+        ".model",
+        ".json",
+        ".yaml",
+        ".yml",
+        ".txt",
+    }
+)
+# folder_paths entries that hold code rather than models.
+EXCLUDED_FOLDER_NAMES = frozenset({"custom_nodes"})
+
+try:
+    import comfy.model_management
+
+    COMFY_AVAILABLE = True
+except ImportError:
+    COMFY_AVAILABLE = False
+
+
+def validate_url_scheme(url: str) -> None:
+    """Raise ValueError unless url uses an allowed scheme (http/https)."""
+    scheme = urlparse(url or "").scheme.lower()
+    if scheme not in ALLOWED_SCHEMES:
+        raise ValueError(
+            f"Unsupported URL scheme '{scheme}'. Only http and https are allowed."
+        )
+
+
+def validate_filename(name: Optional[str]) -> str:
+    """Validate a user-supplied filename.
+
+    Raises:
+        ValueError: If the name is empty, a dot name, or contains path parts.
+    """
+    if (
+        not name
+        or name in (".", "..")
+        or os.path.basename(name) != name
+        or "/" in name
+        or "\\" in name
+        or "\x00" in name
+    ):
+        raise ValueError(f"Invalid filename: {name!r}")
+    return name
+
+
+def safe_server_filename(name: Optional[str], default: str) -> str:
+    """Reduce a server-derived filename to a safe basename, or use default."""
+    if name:
+        candidate = os.path.basename(name.replace("\\", "/"))
+        try:
+            return validate_filename(candidate)
+        except ValueError:
+            pass
+    return default
+
+
+class _SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """Only follow http(s) redirects and drop credentials on cross-host hops."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if urlparse(newurl).scheme.lower() not in ALLOWED_SCHEMES:
+            raise urllib.error.HTTPError(
+                newurl, code, "Redirect to disallowed URL scheme", headers, fp
+            )
+        new_request = super().redirect_request(req, fp, code, msg, headers, newurl)
+        if new_request is not None and (
+            urlparse(newurl).netloc.lower() != urlparse(req.full_url).netloc.lower()
+        ):
+            new_request.remove_header("Authorization")
+        return new_request
+
+
+class _NoRedirectProcessor(urllib.request.HTTPErrorProcessor):
+    """Return every response as-is so redirects can be handled manually."""
+
+    def http_response(self, request, response):
+        return response
+
+    https_response = http_response
+
+
+def _folder_paths():
+    """Return the folder_paths module, or None when unavailable."""
+    try:
+        import folder_paths
+
+        return folder_paths
+    except ImportError:
+        return None
+
+
+def _default_model_roots() -> List[str]:
+    """Return ComfyUI's models dir plus every registered model folder.
+
+    Covers extra_model_paths.yaml entries on other drives.
+    """
+    fp = _folder_paths()
+    if fp is None:
+        return []
+    roots: List[str] = []
+    models_dir = getattr(fp, "models_dir", None)
+    if isinstance(models_dir, str) and models_dir:
+        roots.append(models_dir)
+    registry = getattr(fp, "folder_names_and_paths", None)
+    if isinstance(registry, dict):
+        for name, entry in registry.items():
+            if name in EXCLUDED_FOLDER_NAMES:
+                continue
+            try:
+                paths = entry[0]
+            except (TypeError, IndexError, KeyError):
+                continue
+            if isinstance(paths, (list, tuple)):
+                roots.extend(p for p in paths if isinstance(p, str) and p)
+    return roots
+
+
+def _default_base_path() -> Optional[str]:
+    """Return ComfyUI's base path used to resolve relative save paths."""
+    fp = _folder_paths()
+    base = getattr(fp, "base_path", None) if fp is not None else None
+    return base if isinstance(base, str) and base else None
+
+
+class BaseDownloader(ABC):
+    """Abstract base class for all downloaders"""
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        models_root: Union[str, Sequence[str], None] = None,
+    ):
+        """Initialize downloader with optional API token
+
+        Args:
+            token: Optional API token for authentication
+            models_root: Directory (or list of directories) downloads must
+                stay inside. Defaults to ComfyUI's models directory plus all
+                registered model folders.
+        """
+        self.token = token
+        if isinstance(models_root, str):
+            models_root = [models_root]
+        self._models_root = list(models_root) if models_root else None
+        self._progress_callback: Optional[Callable[[int, int, str], None]] = None
+
+    def set_progress_callback(self, callback: Callable[[int, int, str], None]) -> None:
+        """Set callback function for progress updates
+
+        Args:
+            callback: Function(downloaded_bytes, total_bytes, message)
+        """
+        self._progress_callback = callback
+
+    def report_progress(self, downloaded: int, total: int, message: str = "") -> None:
+        """Report download progress to callback
+
+        Args:
+            downloaded: Bytes downloaded so far
+            total: Total bytes to download
+            message: Optional status message
+        """
+        if self._progress_callback:
+            self._progress_callback(downloaded, total, message)
+
+    def check_interrupt(self) -> None:
+        """Check if processing has been interrupted by user
+
+        Raises:
+            comfy.model_management.InterruptProcessingException: If user cancelled
+        """
+        if COMFY_AVAILABLE:
+            comfy.model_management.throw_exception_if_processing_interrupted()
+
+    def extract_filename(self, url: str, default: str = "downloaded_file") -> str:
+        """Extract filename from URL
+
+        Args:
+            url: URL to extract filename from
+            default: Default filename if extraction fails
+
+        Returns:
+            Extracted or default filename
+        """
+        try:
+            parsed = urlparse(url)
+            path = unquote(parsed.path)
+            filename = os.path.basename(path)
+
+            # Remove query parameters from filename
+            if "?" in filename:
+                filename = filename.split("?")[0]
+
+            # Validate filename
+            if filename and len(filename) > 0 and "." in filename:
+                return filename
+        except Exception:
+            pass
+
+        return default
+
+    def extract_filename_from_header(self, content_disposition: str) -> Optional[str]:
+        """Extract filename from Content-Disposition header
+
+        Args:
+            content_disposition: Content-Disposition header value
+
+        Returns:
+            Extracted filename or None
+        """
+        if not content_disposition:
+            return None
+        match = re.search(r"filename\*\s*=\s*[^']*'[^']*'([^;]+)", content_disposition)
+        if match:
+            return unquote(match.group(1).strip()) or None
+        match = re.search(
+            r'filename\s*=\s*(?:"([^"]*)"|\'([^\']*)\'|([^;]+))', content_disposition
+        )
+        if match:
+            value = next(g for g in match.groups() if g is not None)
+            return value.strip() or None
+        return None
+
+    @staticmethod
+    def _is_within(path: str, root: str) -> bool:
+        try:
+            return os.path.commonpath([root, path]) == root
+        except ValueError:  # different drives
+            return False
+
+    def resolve_output_dir(self, output_path: str) -> str:
+        """Resolve output_path and ensure it lives inside the models root.
+
+        Returns:
+            Real (symlink-resolved) directory path, created if missing.
+
+        Raises:
+            ValueError: If the path escapes the models directory.
+        """
+        roots = self._models_root or _default_model_roots()
+        if not roots:
+            raise ValueError("Models directory is unavailable; refusing to download")
+        if not os.path.isabs(output_path):
+            output_path = os.path.join(_default_base_path() or os.getcwd(), output_path)
+        real_dir = os.path.realpath(output_path)
+        real_roots = [os.path.realpath(r) for r in roots]
+        if not any(self._is_within(real_dir, r) for r in real_roots):
+            raise ValueError(
+                f"Save path must be inside a ComfyUI models directory "
+                f"({', '.join(real_roots)})"
+            )
+        self.validate_output_path(real_dir)
+        return real_dir
+
+    def open_url(self, request: urllib.request.Request, follow_redirects: bool = True):
+        """Open a request with scheme checks, timeout and safe redirects."""
+        validate_url_scheme(request.full_url)
+        handler = _SafeRedirectHandler if follow_redirects else _NoRedirectProcessor
+        opener = urllib.request.build_opener(handler)
+        return opener.open(request, timeout=DOWNLOAD_TIMEOUT)
+
+    @staticmethod
+    def parse_content_length(response: Any) -> Optional[int]:
+        """Return Content-Length as int, or None if absent/invalid."""
+        value = response.getheader("Content-Length")
+        try:
+            return int(value) if value is not None else None
+        except (TypeError, ValueError):
+            return None
+
+    def save_response(
+        self,
+        response: Any,
+        output_file: str,
+        total_size: Optional[int],
+        strict_size: bool = True,
+    ) -> str:
+        """Stream response to output_file atomically via a .part file.
+
+        The .part file is removed on any failure (including interrupts).
+
+        Raises:
+            ValueError: If output_file is not a model/data file type.
+        """
+        extension = os.path.splitext(output_file)[1].lower()
+        if extension not in ALLOWED_FILE_EXTENSIONS:
+            raise ValueError(
+                f"Refusing to save file type '{extension or 'none'}': "
+                f"only model files ({', '.join(sorted(ALLOWED_FILE_EXTENSIONS))})"
+            )
+        part_file = output_file + PART_SUFFIX
+        try:
+            downloaded = 0
+            start_time = time.time()
+            with open(part_file, "wb") as f:
+                while True:
+                    chunk_start = time.time()
+                    buffer = response.read(CHUNK_SIZE)
+                    chunk_time = time.time() - chunk_start
+                    if not buffer:
+                        break
+                    downloaded += len(buffer)
+                    f.write(buffer)
+                    self.check_interrupt()
+                    speed = self.calculate_speed(len(buffer), chunk_time)
+                    self._report_chunk(downloaded, total_size, speed)
+            sys.stdout.write("\n")
+
+            actual_size = os.path.getsize(part_file)
+            if total_size and actual_size != total_size:
+                message = (
+                    f"Download incomplete. Expected {total_size} bytes, "
+                    f"got {actual_size} bytes"
+                )
+                if strict_size:
+                    raise Exception(message)
+                logger.warning(message)
+
+            os.replace(part_file, output_file)
+            logger.info(
+                "Download completed in %.0fs: %s", time.time() - start_time, output_file
+            )
+            return output_file
+        except BaseException:
+            if os.path.exists(part_file):
+                os.remove(part_file)
+            raise
+        finally:
+            close = getattr(response, "close", None)
+            if callable(close):
+                close()
+
+    def _report_chunk(
+        self, downloaded: int, total_size: Optional[int], speed: float
+    ) -> None:
+        """Write console progress and notify the callback."""
+        if total_size:
+            progress = downloaded / total_size
+            sys.stdout.write(
+                f'\r[{"=" * int(progress * 50):<50}] {progress * 100:.2f}% - {speed:.2f} MB/s'
+            )
+            self.report_progress(downloaded, total_size, f"{speed:.2f} MB/s")
+        else:
+            sys.stdout.write(
+                f"\rDownloaded: {self.format_size(downloaded)} - {speed:.2f} MB/s"
+            )
+            self.report_progress(downloaded, 0, f"{speed:.2f} MB/s")
+        sys.stdout.flush()
+
+    def raise_for_http_status(self, code: int, reason: str, hints: dict) -> None:
+        """Raise a friendly Exception for an HTTP error status."""
+        message = hints.get(code)
+        if message is None and code == 429:
+            message = "Rate limited. Please wait a moment before trying again."
+        raise Exception(message or f"HTTP error {code}: {reason}")
+
+    def validate_output_path(self, output_path: str) -> bool:
+        """Validate and create output path if needed
+
+        Args:
+            output_path: Directory path to validate
+
+        Returns:
+            True if valid
+
+        Raises:
+            ValueError: If path exists but is not a directory
+        """
+        path = Path(output_path)
+
+        if path.exists():
+            if not path.is_dir():
+                raise ValueError(
+                    f"Output path {output_path} exists but is not a directory"
+                )
+            return True
+
+        # Create directory if it doesn't exist
+        path.mkdir(parents=True, exist_ok=True)
+        return True
+
+    def should_download(self, file_path: str, force: bool = False) -> bool:
+        """Check if file should be downloaded
+
+        Args:
+            file_path: Full path to file
+            force: Force download even if file exists
+
+        Returns:
+            True if should download, False if file exists and force=False
+        """
+        if force:
+            return True
+
+        return not Path(file_path).exists()
+
+    def format_size(self, size_bytes: int) -> str:
+        """Format file size in human-readable format
+
+        Args:
+            size_bytes: Size in bytes
+
+        Returns:
+            Formatted size string (e.g., "5.00 MB")
+        """
+        for unit in ["B", "KB", "MB", "GB"]:
+            if size_bytes < 1024.0:
+                return f"{size_bytes:.2f} {unit}"
+            size_bytes /= 1024.0
+        return f"{size_bytes:.2f} TB"
+
+    def calculate_speed(self, bytes_downloaded: int, elapsed_seconds: float) -> float:
+        """Calculate download speed in MB/s
+
+        Args:
+            bytes_downloaded: Number of bytes downloaded
+            elapsed_seconds: Time elapsed in seconds
+
+        Returns:
+            Download speed in MB/s
+        """
+        if elapsed_seconds <= 0:
+            return 0.0
+
+        mb_downloaded = bytes_downloaded / (1024 * 1024)
+        return mb_downloaded / elapsed_seconds
+
+    @abstractmethod
+    def download(
+        self,
+        url: str,
+        output_path: str,
+        filename: Optional[str] = None,
+        force: bool = False,
+    ) -> str:
+        """Download file from URL
+
+        Args:
+            url: URL to download from
+            output_path: Directory to save file
+            filename: Optional filename override
+            force: Force re-download if file exists
+
+        Returns:
+            Path to downloaded file
+
+        Raises:
+            NotImplementedError: Must be implemented by subclass
+        """
+        raise NotImplementedError("Subclasses must implement download()")

kikotools/tools/model_downloader/civitai.py

@@ -0,0 +1,238 @@
+"""CivitAI downloader implementation"""
+
+import json
+import logging
+import os
+import urllib.request
+import urllib.parse
+import urllib.error
+from typing import Optional, Dict, Any
+from urllib.parse import urlparse, parse_qs, unquote, urljoin
+
+from .base import (
+    USER_AGENT,
+    BaseDownloader,
+    safe_server_filename,
+    validate_filename,
+    validate_url_scheme,
+)
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://civitai.com/api/v1"
+REDIRECT_STATUSES = (301, 302, 303, 307, 308)
+
+HTTP_ERROR_HINTS = {
+    401: "Authentication required. Please provide a valid API token.",
+    403: "Access forbidden. The model might be restricted or require special permissions.",
+    404: "Model not found. The URL might be incorrect or the model was removed.",
+}
+
+
+class CivitAIDownloader(BaseDownloader):
+    """Downloader for CivitAI models"""
+
+    def _make_request(
+        self, url: str, headers: Optional[Dict[str, str]] = None
+    ) -> urllib.request.Request:
+        """Create HTTP request with authentication
+
+        Args:
+            url: URL to request
+            headers: Optional additional headers
+
+        Returns:
+            urllib Request object
+        """
+        if headers is None:
+            headers = {}
+
+        headers["User-Agent"] = USER_AGENT
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        return urllib.request.Request(url, headers=headers)
+
+    def _parse_civitai_url(self, url: str) -> Dict[str, Optional[int]]:
+        """Extract model and version IDs from CivitAI URL
+
+        Args:
+            url: CivitAI URL to parse
+
+        Returns:
+            Dict with 'model_id' and 'version_id' keys
+        """
+        parsed = urlparse(url)
+        result = {"model_id": None, "version_id": None}
+
+        # Handle different URL patterns
+        # 1. Direct API download URL: /api/download/models/123456
+        if "/api/download/models/" in url:
+            match = url.split("/api/download/models/")[-1].split("?")[0]
+            if match.isdigit():
+                result["version_id"] = int(match)
+                return result
+
+        # 2. Model page URL: /models/123456 or /models/123456/model-name
+        if "/models/" in url:
+            parts = parsed.path.split("/")
+            if "models" in parts:
+                idx = parts.index("models")
+                if idx + 1 < len(parts) and parts[idx + 1].isdigit():
+                    result["model_id"] = int(parts[idx + 1])
+
+        # 3. Version specific URL with ?modelVersionId=789012
+        query_params = parse_qs(parsed.query)
+        if "modelVersionId" in query_params:
+            version_id = query_params["modelVersionId"][0]
+            if version_id.isdigit():
+                result["version_id"] = int(version_id)
+
+        return result
+
+    def get_model_details(self, model_id: int) -> Dict[str, Any]:
+        """Get model details from API
+
+        Args:
+            model_id: CivitAI model ID
+
+        Returns:
+            Model details dictionary
+
+        Raises:
+            Exception: If API request fails
+        """
+        url = f"{API_BASE}/models/{model_id}"
+        request = self._make_request(url)
+
+        try:
+            with self.open_url(request) as response:
+                return json.loads(response.read().decode())
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                raise Exception(f"Model {model_id} not found")
+            raise Exception(f"API request failed: {e}")
+
+    def download(
+        self,
+        url: str,
+        output_path: str,
+        filename: Optional[str] = None,
+        force: bool = False,
+    ) -> str:
+        """Download file from CivitAI
+
+        Args:
+            url: CivitAI URL to download
+            output_path: Directory to save file
+            filename: Optional filename override
+            force: Force re-download if file exists
+
+        Returns:
+            Path to downloaded file
+
+        Raises:
+            Exception: If download fails
+        """
+        validate_url_scheme(url)
+        if filename:
+            validate_filename(filename)
+        output_dir = self.resolve_output_dir(output_path)
+
+        # Validate that URL is from civitai.com domain
+        parsed_url = urlparse(url)
+        if parsed_url.netloc not in ("civitai.com", "www.civitai.com"):
+            raise ValueError(
+                f"Invalid URL: Only civitai.com URLs are supported, got {parsed_url.netloc}"
+            )
+
+        # Convert web URL to API URL if needed
+        if "/api/download/models/" not in url:
+            ids = self._parse_civitai_url(url)
+
+            # If we have a version ID, use it directly
+            if ids["version_id"]:
+                url = f"https://civitai.com/api/download/models/{ids['version_id']}"
+            # If we only have a model ID, get the latest version
+            elif ids["model_id"]:
+                try:
+                    model_details = self.get_model_details(ids["model_id"])
+                    if model_details.get("modelVersions"):
+                        version_id = model_details["modelVersions"][0]["id"]
+                        url = f"https://civitai.com/api/download/models/{version_id}"
+                    else:
+                        raise Exception(
+                            f"No versions found for model {ids['model_id']}"
+                        )
+                except Exception as e:
+                    raise Exception(f"Failed to get model details: {e}")
+            else:
+                raise Exception("Could not parse model or version ID from URL")
+
+        headers = {"User-Agent": USER_AGENT}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        request = urllib.request.Request(url, headers=headers)
+
+        try:
+            response = self.open_url(request, follow_redirects=False)
+        except urllib.error.HTTPError as e:
+            self.raise_for_http_status(e.code, e.reason, HTTP_ERROR_HINTS)
+        except urllib.error.URLError as e:
+            raise Exception(f"Network error: {e.reason}")
+
+        if response.status in REDIRECT_STATUSES:
+            redirect_url = response.getheader("Location")
+            response.close()
+            if not redirect_url:
+                raise Exception("Redirect response did not include a Location header")
+            redirect_url = urljoin(url, redirect_url)
+            validate_url_scheme(redirect_url)
+
+            if not filename:
+                filename = self._filename_from_redirect(redirect_url)
+
+            # The signed redirect target gets no credentials
+            try:
+                response = self.open_url(
+                    urllib.request.Request(
+                        redirect_url, headers={"User-Agent": USER_AGENT}
+                    )
+                )
+            except urllib.error.HTTPError as e:
+                self.raise_for_http_status(e.code, e.reason, HTTP_ERROR_HINTS)
+            except urllib.error.URLError as e:
+                raise Exception(f"Network error: {e.reason}")
+        elif response.status != 200:
+            code = response.status
+            response.close()
+            self.raise_for_http_status(
+                code, "Download failed", {**HTTP_ERROR_HINTS, 404: "File not found"}
+            )
+
+        if not filename:
+            filename = safe_server_filename(
+                self.extract_filename(url, default="model.safetensors"),
+                "model.safetensors",
+            )
+
+        output_file = os.path.join(output_dir, filename)
+        if not self.should_download(output_file, force):
+            response.close()
+            logger.info("File already exists: %s", output_file)
+            return output_file
+
+        total_size = self.parse_content_length(response)
+        logger.info("Downloading %s to %s", filename, output_file)
+        return self.save_response(response, output_file, total_size)
+
+    def _filename_from_redirect(self, redirect_url: str) -> str:
+        """Derive a safe filename from a CivitAI redirect URL."""
+        parsed = urlparse(redirect_url)
+        disposition = parse_qs(parsed.query).get("response-content-disposition", [""])[
+            0
+        ]
+        name = self.extract_filename_from_header(unquote(disposition))
+        if not name:
+            name = parsed.path.rsplit("/", 1)[-1]
+        return safe_server_filename(name, "downloaded_file.safetensors")

kikotools/tools/model_downloader/custom.py

@@ -0,0 +1,98 @@
+"""Custom URL downloader - best effort for direct download links"""
+
+import logging
+import os
+import urllib.error
+import urllib.request
+from typing import Optional
+
+from .base import (
+    USER_AGENT,
+    BaseDownloader,
+    safe_server_filename,
+    validate_filename,
+    validate_url_scheme,
+)
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_FILENAME = "downloaded_model.safetensors"
+
+HTTP_ERROR_HINTS = {
+    401: "Authentication required. Please provide a valid token if needed.",
+    403: "Access forbidden. The URL might require authentication or special permissions.",
+    404: "File not found. Please check the URL.",
+}
+
+
+class CustomDownloader(BaseDownloader):
+    """Best-effort downloader for custom/direct URLs
+
+    The optional token is sent as a Bearer token and is dropped automatically
+    if the server redirects to a different host.
+    """
+
+    def download(
+        self,
+        url: str,
+        output_path: str,
+        filename: Optional[str] = None,
+        force: bool = False,
+    ) -> str:
+        """Download file from custom URL
+
+        Args:
+            url: Direct download URL (http or https)
+            output_path: Directory to save file (must be inside models dir)
+            filename: Optional filename override (plain name, no path parts)
+            force: Force re-download if file exists
+
+        Returns:
+            Path to downloaded file
+
+        Raises:
+            ValueError: For bad scheme, filename or save path
+            Exception: If download fails
+        """
+        validate_url_scheme(url)
+        if filename:
+            validate_filename(filename)
+        output_dir = self.resolve_output_dir(output_path)
+
+        # Fast path: a known filename lets us skip the request entirely
+        if filename:
+            output_file = os.path.join(output_dir, filename)
+            if not self.should_download(output_file, force):
+                logger.info("File already exists: %s", output_file)
+                return output_file
+
+        headers = {"User-Agent": USER_AGENT}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        request = urllib.request.Request(url, headers=headers)
+
+        try:
+            response = self.open_url(request)
+        except urllib.error.HTTPError as e:
+            self.raise_for_http_status(e.code, e.reason, HTTP_ERROR_HINTS)
+        except urllib.error.URLError as e:
+            raise Exception(f"Network error: {e.reason}")
+
+        if not filename:
+            header_name = self.extract_filename_from_header(
+                response.getheader("Content-Disposition") or ""
+            )
+            filename = safe_server_filename(
+                header_name, self.extract_filename(url, default=DEFAULT_FILENAME)
+            )
+            output_file = os.path.join(output_dir, filename)
+            if not self.should_download(output_file, force):
+                response.close()
+                logger.info("File already exists: %s", output_file)
+                return output_file
+
+        total_size = self.parse_content_length(response)
+        logger.info("Downloading %s to %s", filename, output_file)
+
+        # Size mismatch is only a warning for arbitrary URLs
+        return self.save_response(response, output_file, total_size, strict_size=False)

kikotools/tools/model_downloader/detector.py

@@ -0,0 +1,137 @@
+"""URL detection and downloader selection logic"""
+
+from __future__ import annotations
+from enum import Enum
+from typing import TYPE_CHECKING, Optional
+from urllib.parse import urlparse
+
+if TYPE_CHECKING:
+    from .base import BaseDownloader
+
+
+class DownloaderType(Enum):
+    """Types of supported downloaders"""
+
+    CIVITAI = "civitai"
+    HUGGINGFACE = "huggingface"
+    CUSTOM = "custom"
+
+
+class URLDetector:
+    """Detects URL type and returns appropriate downloader"""
+
+    def detect(self, url: Optional[str]) -> DownloaderType:
+        """Detect which downloader to use based on URL
+
+        Args:
+            url: URL to analyze
+
+        Returns:
+            DownloaderType enum value
+
+        Raises:
+            ValueError: If URL is invalid or empty
+        """
+        if not url:
+            raise ValueError("URL cannot be empty")
+
+        url = url.strip()
+        if not url:
+            raise ValueError("URL cannot be empty")
+
+        try:
+            parsed = urlparse(url)
+            if not parsed.scheme or not parsed.netloc:
+                raise ValueError("Invalid URL format")
+        except Exception:
+            raise ValueError("Invalid URL")
+
+        # Check for CivitAI
+        if self._is_civitai_url(url, parsed):
+            return DownloaderType.CIVITAI
+
+        # Check for HuggingFace
+        if self._is_huggingface_url(url, parsed):
+            return DownloaderType.HUGGINGFACE
+
+        # Default to custom downloader
+        return DownloaderType.CUSTOM
+
+    def _is_civitai_url(self, url: str, parsed) -> bool:
+        """Check if URL is from CivitAI
+
+        Args:
+            url: Full URL string
+            parsed: Parsed URL object
+
+        Returns:
+            True if CivitAI URL
+        """
+        # Validate exact domain match to prevent subdomain attacks
+        if parsed.netloc not in ("civitai.com", "www.civitai.com"):
+            return False
+
+        # Check for API download endpoint
+        if "/api/download/models/" in url:
+            return True
+
+        # Check for model page
+        if "/models/" in url:
+            return True
+
+        return False
+
+    def _is_huggingface_url(self, url: str, parsed) -> bool:
+        """Check if URL is from HuggingFace
+
+        Args:
+            url: Full URL string
+            parsed: Parsed URL object
+
+        Returns:
+            True if HuggingFace URL
+        """
+        # Validate exact domain match to prevent subdomain attacks
+        # Support both main domain and CDN domains
+        allowed_domains = (
+            "huggingface.co",
+            "www.huggingface.co",
+            "cdn.huggingface.co",
+            "cdn-lfs.huggingface.co",
+        )
+        if parsed.netloc in allowed_domains:
+            return True
+
+        return False
+
+    def get_downloader(
+        self, url: str, api_token: Optional[str] = None
+    ) -> "BaseDownloader":
+        """Get appropriate downloader instance for URL
+
+        Args:
+            url: URL to download from
+            api_token: Optional API token for authentication
+
+        Returns:
+            Appropriate downloader instance
+
+        Raises:
+            ValueError: If URL is invalid
+        """
+        downloader_type = self.detect(url)
+
+        if downloader_type == DownloaderType.CIVITAI:
+            from .civitai import CivitAIDownloader
+
+            return CivitAIDownloader(token=api_token)
+
+        elif downloader_type == DownloaderType.HUGGINGFACE:
+            from .huggingface import HuggingFaceDownloader
+
+            return HuggingFaceDownloader(token=api_token)
+
+        else:  # CUSTOM
+            from .custom import CustomDownloader
+
+            return CustomDownloader(token=api_token)

kikotools/tools/model_downloader/huggingface.py

@@ -0,0 +1,161 @@
+"""HuggingFace downloader implementation"""
+
+import logging
+import os
+import urllib.request
+import urllib.error
+from typing import Optional
+from urllib.parse import urlparse, quote
+
+from .base import (
+    USER_AGENT,
+    BaseDownloader,
+    safe_server_filename,
+    validate_filename,
+    validate_url_scheme,
+)
+
+logger = logging.getLogger(__name__)
+
+HTTP_ERROR_HINTS = {
+    401: "Authentication required. Please provide a valid HuggingFace token.",
+    403: "Access forbidden. The model might be gated or require special permissions.",
+    404: "File not found. The URL might be incorrect or the file was removed.",
+}
+
+
+class HuggingFaceDownloader(BaseDownloader):
+    """Downloader for HuggingFace models"""
+
+    def _parse_huggingface_url(self, url: str) -> dict:
+        """Parse HuggingFace URL to extract repo and file information
+
+        Args:
+            url: HuggingFace URL
+
+        Returns:
+            Dict with 'repo_id', 'filename', 'revision' keys
+        """
+        parsed = urlparse(url)
+        parts = parsed.path.strip("/").split("/")
+
+        result = {"repo_id": None, "filename": None, "revision": "main"}
+
+        # Handle blob URLs (web UI format) - convert to resolve format
+        # /{username}/{repo}/blob/{revision}/{file_path}
+        if len(parts) >= 5 and "blob" in parts:
+            blob_idx = parts.index("blob")
+            if blob_idx >= 2:
+                # Extract repo_id (username/repo)
+                result["repo_id"] = "/".join(parts[:blob_idx])
+                # Extract revision
+                if blob_idx + 1 < len(parts):
+                    result["revision"] = parts[blob_idx + 1]
+                # Extract filename (everything after revision)
+                if blob_idx + 2 < len(parts):
+                    result["filename"] = "/".join(parts[blob_idx + 2 :])
+
+        # Standard HF URL format: /{username}/{repo}/resolve/{revision}/{file_path}
+        elif len(parts) >= 5 and "resolve" in parts:
+            resolve_idx = parts.index("resolve")
+            if resolve_idx >= 2:
+                # Extract repo_id (username/repo)
+                result["repo_id"] = "/".join(parts[:resolve_idx])
+                # Extract revision
+                if resolve_idx + 1 < len(parts):
+                    result["revision"] = parts[resolve_idx + 1]
+                # Extract filename (everything after revision)
+                if resolve_idx + 2 < len(parts):
+                    result["filename"] = "/".join(parts[resolve_idx + 2 :])
+
+        # Alternative CDN format: Extract what we can
+        elif "cdn" in parsed.netloc:
+            # CDN URLs might have different structure
+            # Try to extract filename from path
+            if len(parts) > 0:
+                result["filename"] = parts[-1]
+
+        return result
+
+    def _construct_download_url(
+        self, repo_id: str, filename: str, revision: str = "main"
+    ) -> str:
+        """Construct HuggingFace download URL
+
+        Args:
+            repo_id: Repository ID (username/repo)
+            filename: File path within repo
+            revision: Branch/tag/commit (default: main)
+
+        Returns:
+            Download URL
+        """
+        # URL encode the filename to handle special characters
+        encoded_filename = quote(filename, safe="/")
+        return f"https://huggingface.co/{repo_id}/resolve/{revision}/{encoded_filename}"
+
+    def download(
+        self,
+        url: str,
+        output_path: str,
+        filename: Optional[str] = None,
+        force: bool = False,
+    ) -> str:
+        """Download file from HuggingFace
+
+        Args:
+            url: HuggingFace URL to download (http or https)
+            output_path: Directory to save file (must be inside models dir)
+            filename: Optional filename override (plain name, no path parts)
+            force: Force re-download if file exists
+
+        Returns:
+            Path to downloaded file
+
+        Raises:
+            ValueError: For bad scheme, filename or save path
+            Exception: If download fails
+        """
+        validate_url_scheme(url)
+        if filename:
+            validate_filename(filename)
+        output_dir = self.resolve_output_dir(output_path)
+
+        url_info = self._parse_huggingface_url(url)
+
+        # Convert blob URL to resolve URL if needed
+        if url_info["repo_id"] and url_info["filename"]:
+            download_url = self._construct_download_url(
+                url_info["repo_id"], url_info["filename"], url_info["revision"]
+            )
+            logger.info("Converted URL to: %s", download_url)
+        else:
+            download_url = url
+
+        if not filename:
+            if url_info["filename"]:
+                name = os.path.basename(url_info["filename"])
+            else:
+                name = self.extract_filename(url, default="model.safetensors")
+            filename = safe_server_filename(name, "model.safetensors")
+
+        output_file = os.path.join(output_dir, filename)
+        if not self.should_download(output_file, force):
+            logger.info("File already exists: %s", output_file)
+            return output_file
+
+        headers = {"User-Agent": USER_AGENT}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        request = urllib.request.Request(download_url, headers=headers)
+
+        try:
+            response = self.open_url(request)
+        except urllib.error.HTTPError as e:
+            self.raise_for_http_status(e.code, e.reason, HTTP_ERROR_HINTS)
+        except urllib.error.URLError as e:
+            raise Exception(f"Network error: {e.reason}")
+
+        total_size = self.parse_content_length(response)
+        logger.info("Downloading %s to %s", filename, output_file)
+        return self.save_response(response, output_file, total_size)

kikotools/tools/model_downloader/node.py

@@ -0,0 +1,157 @@
+"""ComfyUI Model Downloader Node"""
+
+import logging
+
+from ...base import ComfyAssetsBaseNode
+from .detector import URLDetector
+
+logger = logging.getLogger(__name__)
+
+
+class ModelDownloaderNode(ComfyAssetsBaseNode):
+    """ComfyUI node for downloading models from CivitAI, HuggingFace, and custom URLs"""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        """Define input types for the node"""
+        return {
+            "required": {
+                "url": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "placeholder": "https://civitai.com/... or https://huggingface.co/...",
+                    },
+                ),
+                "save_path": (
+                    "STRING",
+                    {
+                        "default": "models/checkpoints",
+                        "multiline": False,
+                        "placeholder": "Path to save downloaded models",
+                    },
+                ),
+            },
+            "optional": {
+                "filename": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "placeholder": "Leave empty for auto-detection",
+                    },
+                ),
+                "api_token": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "placeholder": "API token (CivitAI or HuggingFace)",
+                    },
+                ),
+                "force_download": (
+                    "BOOLEAN",
+                    {
+                        "default": False,
+                        "label_on": "Force Redownload",
+                        "label_off": "Skip if Exists",
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ()
+    FUNCTION = "download_model"
+    CATEGORY = "🫶 ComfyAssets/🛠️ Utils"
+    OUTPUT_NODE = True
+
+    def download_model(
+        self,
+        url: str,
+        save_path: str,
+        filename: str = "",
+        api_token: str = "",
+        force_download: bool = False,
+    ):
+        """Download model from URL
+
+        Args:
+            url: URL to download from
+            save_path: Directory to save file
+            filename: Optional filename override
+            api_token: Optional API token
+            force_download: Force re-download if file exists
+
+        Returns:
+            Dictionary with 'ui' key for ComfyUI display
+        """
+        # Validate inputs
+        if not url or not url.strip():
+            error_msg = "URL cannot be empty"
+            return {"ui": {"text": [error_msg]}}
+
+        if not save_path or not save_path.strip():
+            error_msg = "Save path cannot be empty"
+            return {"ui": {"text": [error_msg]}}
+
+        url = url.strip()
+        save_path = save_path.strip()
+        filename = filename.strip() if filename else None
+        api_token = api_token.strip() if api_token else None
+
+        try:
+            # Detect downloader type and get appropriate downloader
+            detector = URLDetector()
+            downloader_type = detector.detect(url)
+
+            logger.info("Detected downloader type: %s", downloader_type.value)
+            logger.info("URL: %s", url)
+            logger.info("Save path: %s", save_path)
+            if filename:
+                logger.info("Filename: %s", filename)
+            if force_download:
+                logger.info("Force download: enabled")
+
+            # Get downloader instance
+            downloader = detector.get_downloader(url, api_token=api_token)
+
+            # Download file
+            file_path = downloader.download(
+                url=url, output_path=save_path, filename=filename, force=force_download
+            )
+
+            message = f"Successfully downloaded to {file_path}"
+            logger.info(message)
+
+            return {"ui": {"text": [message]}}
+
+        except ValueError as e:
+            error_msg = f"Invalid URL: {str(e)}"
+            logger.error(error_msg)
+            return {"ui": {"text": [error_msg]}}
+
+        except Exception as e:
+            error_msg = f"Download failed: {str(e)}"
+            logger.error(error_msg)
+            return {"ui": {"text": [error_msg]}}
+
+    @classmethod
+    def IS_CHANGED(
+        cls, url, save_path, filename="", api_token="", force_download=False
+    ):
+        """Force re-evaluation on every execution or when inputs change"""
+        # Include hash of inputs plus timestamp to force execution
+        # This ensures the node re-runs even if the download failed previously
+        import time
+        import hashlib
+
+        # Create a unique hash based on non-sensitive inputs and current time
+        # Note: api_token is excluded to avoid sensitive data in hash
+        # The token doesn't affect cache invalidation - URL changes are sufficient
+        input_str = f"{url}|{save_path}|{filename}|{force_download}|{time.time()}"
+        return hashlib.sha256(input_str.encode()).hexdigest()
+
+
+# Node display name
+NODE_DISPLAY_NAME = "Model Downloader 🌐"

kikotools/tools/resolution_calculator/logic.py

@@ -6,6 +6,8 @@ Pure functions for dimension extraction and scaling calculations
 import torch
 from typing import Tuple, Optional, Dict
 
+MIN_DIMENSION = 8
+
 
 def extract_dimensions(
     image: Optional[torch.Tensor] = None,
@@ -100,8 +102,9 @@ def calculate_scaled_dimensions(
     new_width = int(width * scale_factor)
     new_height = int(height * scale_factor)
 
-    # Ensure divisible by 8
-    return ensure_divisible_by_8(new_width, new_height)
+    # Ensure divisible by 8, never collapsing to zero for tiny inputs
+    new_width, new_height = ensure_divisible_by_8(new_width, new_height)
+    return max(new_width, MIN_DIMENSION), max(new_height, MIN_DIMENSION)
 
 
 def validate_scale_factor(

kikotools/tools/resolution_calculator/node.py

@@ -60,7 +60,7 @@ class ResolutionCalculatorNode(ComfyAssetsBaseNode):
         }
 
     RETURN_TYPES = ("INT", "INT")
-    CATEGORY = "ComfyAssets/🖼️ Resolution"
+    CATEGORY = "🫶 ComfyAssets/🖼️ Resolution"
     RETURN_NAMES = ("width", "height")
     FUNCTION = "calculate_resolution"
 

kikotools/tools/sampler_combo/compact_node.py

@@ -53,17 +53,16 @@ class SamplerComboCompactNode(ComfyAssetsBaseNode):
                         "min": 1.0,
                         "max": 15.0,
                         "step": 0.5,
-                        "display": "slider",
                         "tooltip": "CFG",
                     },
                 ),
             }
         }
 
-    RETURN_TYPES = ("SAMPLER", SCHEDULERS, "INT", "FLOAT")
+    RETURN_TYPES = (SAMPLERS, SCHEDULERS, "INT", "FLOAT")
     RETURN_NAMES = ("sampler", "scheduler", "steps", "cfg")
     FUNCTION = "get_combo"
-    CATEGORY = "ComfyAssets/🌀 Samplers"
+    CATEGORY = "🫶 ComfyAssets/🌀 Samplers"
 
     def get_combo(
         self, sampler: str, sched: str, steps: int, cfg: float
@@ -83,27 +82,13 @@ class SamplerComboCompactNode(ComfyAssetsBaseNode):
         try:
             # Use the same validation logic but with compact interface
             result = get_sampler_combo(sampler, sched, steps, cfg)
-            # Create the sampler object
-            try:
-                import comfy.samplers
-
-                sampler_obj = comfy.samplers.sampler_object(result[0])
-            except ImportError:
-                # Return sampler name for testing
-                sampler_obj = result[0]
-            return (sampler_obj, result[1], result[2], result[3])
+            # Return the sampler name as string, not object
+            return result
 
         except Exception as e:
             # Graceful fallback
             self.handle_error(f"Error in compact combo: {str(e)}")
-            try:
-                import comfy.samplers
-
-                sampler_obj = comfy.samplers.sampler_object("euler")
-            except ImportError:
-                # Return sampler name for testing
-                sampler_obj = "euler"
-            return (sampler_obj, "normal", 20, 7.0)
+            return ("euler", "normal", 20, 7.0)
 
     def __str__(self) -> str:
         """String representation of the compact node."""

kikotools/tools/sampler_combo/node.py

@@ -58,17 +58,16 @@ class SamplerComboNode(ComfyAssetsBaseNode):
                         "min": 0.0,
                         "max": 20.0,
                         "step": 0.5,
-                        "display": "slider",
                         "tooltip": "CFG scale (0-20)",
                     },
                 ),
             }
         }
 
-    RETURN_TYPES = ("SAMPLER", SCHEDULERS, "INT", "FLOAT")
+    RETURN_TYPES = (SAMPLERS, SCHEDULERS, "INT", "FLOAT")
     RETURN_NAMES = ("sampler_name", "scheduler", "steps", "cfg")
     FUNCTION = "get_sampler_combo"
-    CATEGORY = "ComfyAssets/🌀 Samplers"
+    CATEGORY = "🫶 ComfyAssets/🌀 Samplers"
 
     def get_sampler_combo(
         self, sampler_name: str, scheduler: str, steps: int, cfg: float
@@ -98,33 +97,18 @@ class SamplerComboNode(ComfyAssetsBaseNode):
                     f"steps={steps}, cfg={cfg}. "
                     f"Using safe defaults: euler, normal, 20 steps, CFG 7.0"
                 )
-                try:
-                    import comfy.samplers
-
-                    sampler = comfy.samplers.sampler_object("euler")
-                except ImportError:
-                    # Return mock object for testing
-                    sampler = "euler"
-                return (sampler, "normal", 20, 7.0)
+                return ("euler", "normal", 20, 7.0)
 
             # Process and return the combo
             result = get_sampler_combo(sampler_name, scheduler, steps, cfg)
 
-            # Create the sampler object
-            try:
-                import comfy.samplers
-
-                sampler = comfy.samplers.sampler_object(result[0])
-            except ImportError:
-                # Return sampler name for testing
-                sampler = result[0]
-
             self.log_info(
                 f"Configured sampler combo: {result[0]}, {result[1]}, "
                 f"{result[2]} steps, CFG {result[3]}"
             )
 
-            return (sampler, result[1], result[2], result[3])
+            # Return the sampler name as string, not object
+            return result
 
         except Exception as e:
             # Handle any unexpected errors gracefully
@@ -135,14 +119,7 @@ class SamplerComboNode(ComfyAssetsBaseNode):
                 f"{self.__class__.__name__}: Error processing sampler combo: {str(e)}. "
                 f"Using safe defaults: euler, normal, 20 steps, CFG 7.0"
             )
-            try:
-                import comfy.samplers
-
-                sampler = comfy.samplers.sampler_object("euler")
-            except ImportError:
-                # Return mock object for testing
-                sampler = "euler"
-            return (sampler, "normal", 20, 7.0)
+            return ("euler", "normal", 20, 7.0)
 
     def validate_inputs(
         self, sampler_name: str, scheduler: str, steps: int, cfg: float

kikotools/tools/seed_history/logic.py

@@ -10,14 +10,14 @@ def generate_random_seed() -> int:
     Generate a cryptographically strong random seed value.
 
     Returns:
-        Random integer in the valid ComfyUI seed range
+        Random integer in the valid ComfyUI seed range (0 to 2**32 - 1)
     """
-    return random.randint(0, 0xFFFFFFFFFFFFFFFF)
+    return random.randint(0, 0xFFFFFFFF)  # 2**32 - 1
 
 
 def validate_seed_value(seed: Any) -> bool:
     """
-    Validate that a seed value is within acceptable range.
+    Validate that a seed value is within acceptable range (0 to 2**32 - 1).
 
     Args:
         seed: Seed value to validate
@@ -30,7 +30,7 @@ def validate_seed_value(seed: Any) -> bool:
 
     try:
         seed_int = int(seed)
-        return 0 <= seed_int <= 0xFFFFFFFFFFFFFFFF
+        return 0 <= seed_int <= 0xFFFFFFFF  # 2**32 - 1
     except (ValueError, TypeError):
         return False
 
@@ -54,11 +54,11 @@ def sanitize_seed_value(seed: Any) -> int:
     try:
         seed_int = int(seed)
 
-        # Clamp to valid range
+        # Clamp to valid range (0 to 2**32 - 1)
         if seed_int < 0:
             seed_int = 0
-        elif seed_int > 0xFFFFFFFFFFFFFFFF:
-            seed_int = 0xFFFFFFFFFFFFFFFF
+        elif seed_int > 0xFFFFFFFF:
+            seed_int = 0xFFFFFFFF
 
         return seed_int
 

kikotools/tools/seed_history/node.py

@@ -27,25 +27,27 @@ class SeedHistoryNode(ComfyAssetsBaseNode):
                     {
                         "default": 12345,
                         "min": 0,
-                        "max": 0xFFFFFFFFFFFFFFFF,
+                        "max": 0xFFFFFFFF,  # 2**32 - 1
+                        "control_after_generate": True,
                         "tooltip": "Seed value for generation processes. "
-                        "History UI tracks all changes automatically.",
+                        "Use 'control after generate' to set behavior after each run.",
                     },
                 ),
-            }
+            },
         }
 
     RETURN_TYPES = ("INT",)
     RETURN_NAMES = ("seed",)
     FUNCTION = "output_seed"
-    CATEGORY = "ComfyAssets/🌱 Seeds"
+    CATEGORY = "🫶 ComfyAssets/🌱 Seeds"
 
-    def output_seed(self, seed: int) -> Tuple[int]:
+    def output_seed(self, seed: int, **kwargs) -> Tuple[int]:
         """
         Output the seed value for use in other nodes.
 
         Args:
             seed: Input seed value
+            **kwargs: Accepts legacy parameters (e.g. mode) for backward compatibility
 
         Returns:
             Tuple containing the seed value
@@ -53,7 +55,6 @@ class SeedHistoryNode(ComfyAssetsBaseNode):
         try:
             # Validate and sanitize the seed
             if not validate_seed_value(seed):
-                # Log the validation error but don't raise
                 import logging
 
                 logger = logging.getLogger(__name__)
@@ -64,11 +65,9 @@ class SeedHistoryNode(ComfyAssetsBaseNode):
                 return (12345,)
 
             clean_seed = sanitize_seed_value(seed)
-
             return (clean_seed,)
 
         except Exception as e:
-            # Handle any unexpected errors gracefully
             import logging
 
             logger = logging.getLogger(__name__)
@@ -142,7 +141,7 @@ class SeedHistoryNode(ComfyAssetsBaseNode):
         Returns:
             Range information string
         """
-        max_seed = 0xFFFFFFFFFFFFFFFF
+        max_seed = 0xFFFFFFFF  # 2**32 - 1
         return f"Valid range: 0 to {max_seed:,} ({hex(max_seed)})"
 
     @classmethod
@@ -166,7 +165,7 @@ class SeedHistoryNode(ComfyAssetsBaseNode):
         Returns:
             True if seed is in valid range
         """
-        return 0 <= seed <= 0xFFFFFFFFFFFFFFFF
+        return 0 <= seed <= 0xFFFFFFFF  # 2**32 - 1
 
     def __str__(self) -> str:
         """String representation of the node."""
@@ -178,6 +177,6 @@ class SeedHistoryNode(ComfyAssetsBaseNode):
             f"SeedHistoryNode("
             f"category='{self.CATEGORY}', "
             f"function='{self.FUNCTION}', "
-            f"max_seed={hex(0xFFFFFFFFFFFFFFFF)}"
+            f"max_seed={hex(0xFFFFFFFF)}"  # 2**32 - 1
             f")"
         )

kikotools/tools/text_input/__init__.py

@@ -0,0 +1,5 @@
+"""Text Input tool for ComfyUI."""
+
+from .node import TextInputNode, NODE_DISPLAY_NAME
+
+__all__ = ["TextInputNode", "NODE_DISPLAY_NAME"]

kikotools/tools/text_input/node.py

@@ -0,0 +1,59 @@
+"""Text Input node implementation."""
+
+from ...base import ComfyAssetsBaseNode
+
+
+class TextInputNode(ComfyAssetsBaseNode):
+    """Provides a text input field for manual text entry in ComfyUI workflows."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        """Define input types for the node."""
+        return {
+            "required": {
+                "text": (
+                    "STRING",
+                    {
+                        "multiline": True,
+                        "default": "",
+                        "dynamicPrompts": True,
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("text",)
+    FUNCTION = "execute"
+    CATEGORY = "🫶 ComfyAssets/📝 Text"
+
+    DESCRIPTION = """
+Simple text input field for entering text manually.
+
+Features:
+- Multiline text editing
+- Supports wildcards and dynamic prompts
+- Direct connection to CLIP text encoders
+- Unicode and special character support
+
+Use Cases:
+- Positive/negative prompts
+- Custom text for workflows
+- Manual text editing
+- Prompt templates
+"""
+
+    def execute(self, text):
+        """Process the input text and return it.
+
+        Args:
+            text: Input text from the widget
+
+        Returns:
+            Tuple containing the text
+        """
+        return (text,)
+
+
+# Node display name
+NODE_DISPLAY_NAME = "Text Input"

kikotools/tools/width_height_selector/node.py

@@ -85,7 +85,7 @@ class WidthHeightSelectorNode(ComfyAssetsBaseNode):
     RETURN_TYPES = ("INT", "INT")
     RETURN_NAMES = ("width", "height")
     FUNCTION = "get_dimensions"
-    CATEGORY = "ComfyAssets/🖼️ Resolution"
+    CATEGORY = "🫶 ComfyAssets/🖼️ Resolution"
 
     def get_dimensions(self, preset: str, width: int, height: int) -> Tuple[int, int]:
         """

kikotools/tools/width_height_selector/presets.py

@@ -78,7 +78,47 @@ PRESET_METADATA: Dict[str, PresetMetadata] = {
         "Portrait",
         "SDXL portrait 5:12 - very tall portrait",
     ),
+    "704×1408": PresetMetadata(
+        704,
+        1408,
+        "1:2",
+        0.5,
+        0.99,
+        "SDXL",
+        "Portrait",
+        "SDXL portrait 1:2 - extreme tall portrait",
+    ),
+    "960×1024": PresetMetadata(
+        960,
+        1024,
+        "15:16",
+        0.938,
+        0.98,
+        "SDXL",
+        "Portrait",
+        "SDXL near-square portrait - subtle portrait",
+    ),
+    "720×1280": PresetMetadata(
+        720,
+        1280,
+        "9:16",
+        0.5625,
+        0.92,
+        "SDXL",
+        "Portrait",
+        "SDXL portrait 9:16 - vertical video/mobile",
+    ),
     # SDXL Presets - Landscape
+    "1024×960": PresetMetadata(
+        1024,
+        960,
+        "16:15",
+        1.067,
+        0.98,
+        "SDXL",
+        "Landscape",
+        "SDXL near-square landscape - subtle landscape",
+    ),
     "1152×896": PresetMetadata(
         1152,
         896,
@@ -119,6 +159,26 @@ PRESET_METADATA: Dict[str, PresetMetadata] = {
         "Landscape",
         "SDXL landscape 12:5 - very wide landscape",
     ),
+    "1728×576": PresetMetadata(
+        1728,
+        576,
+        "3:1",
+        3.0,
+        1.0,
+        "SDXL",
+        "Landscape",
+        "SDXL landscape 3:1 - extreme wide panoramic",
+    ),
+    "1280×720": PresetMetadata(
+        1280,
+        720,
+        "16:9",
+        1.778,
+        0.92,
+        "SDXL",
+        "Landscape",
+        "SDXL landscape 16:9 - HD widescreen video",
+    ),
     # FLUX Presets - High Quality
     "1920×1080": PresetMetadata(
         1920,
@@ -283,6 +343,97 @@ PRESET_METADATA: Dict[str, PresetMetadata] = {
         "Banner",
         "Vertical banner 1:3 - extreme tall banner",
     ),
+    # Qwen Presets
+    "1328×1328": PresetMetadata(
+        1328,
+        1328,
+        "1:1",
+        1.0,
+        1.76,
+        "Qwen",
+        "Square",
+        "Qwen square 1:1 - optimized square",
+    ),
+    "1664×928": PresetMetadata(
+        1664,
+        928,
+        "16:9",
+        1.793,
+        1.54,
+        "Qwen",
+        "Landscape",
+        "Qwen landscape 16:9 - widescreen format",
+    ),
+    "928×1664": PresetMetadata(
+        928,
+        1664,
+        "9:16",
+        0.558,
+        1.54,
+        "Qwen",
+        "Portrait",
+        "Qwen portrait 9:16 - vertical format",
+    ),
+    "1472×1104": PresetMetadata(
+        1472,
+        1104,
+        "4:3",
+        1.333,
+        1.62,
+        "Qwen",
+        "Landscape",
+        "Qwen landscape 4:3 - classic landscape",
+    ),
+    "1104×1472": PresetMetadata(
+        1104,
+        1472,
+        "3:4",
+        0.750,
+        1.62,
+        "Qwen",
+        "Portrait",
+        "Qwen portrait 3:4 - classic portrait",
+    ),
+    "1584×1056": PresetMetadata(
+        1584,
+        1056,
+        "3:2",
+        1.500,
+        1.67,
+        "Qwen",
+        "Landscape",
+        "Qwen landscape 3:2 - photography standard",
+    ),
+    "1056×1584": PresetMetadata(
+        1056,
+        1584,
+        "2:3",
+        0.667,
+        1.67,
+        "Qwen",
+        "Portrait",
+        "Qwen portrait 2:3 - portrait photography",
+    ),
+    "2080×688": PresetMetadata(
+        2080,
+        688,
+        "3:1",
+        3.023,
+        1.43,
+        "Qwen",
+        "Landscape",
+        "Qwen experimental landscape 3:1 - ultra-wide",
+    ),
+    "688×2080": PresetMetadata(
+        688,
+        2080,
+        "1:3",
+        0.331,
+        1.43,
+        "Qwen",
+        "Portrait",
+        "Qwen experimental portrait 1:3 - ultra-tall",
+    ),
 }
 
 # Legacy compatibility - maintain old preset dictionaries
@@ -304,6 +455,12 @@ ULTRA_WIDE_PRESETS: Dict[str, Tuple[int, int]] = {
     if v.model_group == "Ultra-Wide"
 }
 
+QWEN_PRESETS: Dict[str, Tuple[int, int]] = {
+    k: (v.width, v.height)
+    for k, v in PRESET_METADATA.items()
+    if v.model_group == "Qwen"
+}
+
 # Combined preset options for ComfyUI dropdown
 PRESET_OPTIONS: Dict[str, Tuple[int, int]] = {
     "custom": (0, 0),  # Special case for custom dimensions
@@ -386,6 +543,22 @@ PRESET_CATEGORIES = {
         for k, v in PRESET_METADATA.items()
         if v.model_group == "Ultra-Wide" and v.category == "Banner"
     ],
+    # Qwen Categories
+    "Qwen Square": [
+        k
+        for k, v in PRESET_METADATA.items()
+        if v.model_group == "Qwen" and v.category == "Square"
+    ],
+    "Qwen Portrait": [
+        k
+        for k, v in PRESET_METADATA.items()
+        if v.model_group == "Qwen" and v.category == "Portrait"
+    ],
+    "Qwen Landscape": [
+        k
+        for k, v in PRESET_METADATA.items()
+        if v.model_group == "Qwen" and v.category == "Landscape"
+    ],
 }
 
 # Legacy compatibility - preset descriptions
@@ -398,6 +571,7 @@ MODEL_RECOMMENDATIONS = {
     "Ultra-Wide": [
         k for k, v in PRESET_METADATA.items() if v.model_group == "Ultra-Wide"
     ],
+    "Qwen": [k for k, v in PRESET_METADATA.items() if v.model_group == "Qwen"],
 }
 
 
@@ -444,21 +618,27 @@ def get_model_recommendation(preset_name: str) -> str:
     return "Custom dimensions"
 
 
+def _console_safe(text: str) -> str:
+    """ASCII for console output: Windows legacy code pages can't print "×"."""
+    return text.replace("×", "x").encode("ascii", "replace").decode()
+
+
 def validate_preset_dimensions() -> bool:
     """Validate that all presets meet ComfyUI requirements."""
-    for preset_name, metadata in PRESET_METADATA.items():
+    for name, metadata in PRESET_METADATA.items():
+        preset_name = _console_safe(name)
         width, height = metadata.width, metadata.height
 
         # Check divisible by 8
         if width % 8 != 0 or height % 8 != 0:
             print(
-                f"ERROR: {preset_name} dimensions not divisible by 8: {width}×{height}"
+                f"ERROR: {preset_name} dimensions not divisible by 8: {width}x{height}"
             )
             return False
 
         # Check reasonable bounds
         if not (64 <= width <= 8192) or not (64 <= height <= 8192):
-            print(f"ERROR: {preset_name} dimensions out of bounds: {width}×{height}")
+            print(f"ERROR: {preset_name} dimensions out of bounds: {width}x{height}")
             return False
 
     return True

kikotools/tools/width_height_to_vec2/__init__.py

@@ -0,0 +1,8 @@
+"""
+Width Height to VEC2 converter node
+Converts width and height inputs to VEC2 tuple for jovi_glsl and similar nodes
+"""
+
+from .node import WidthHeightToVec2Node
+
+__all__ = ["WidthHeightToVec2Node"]

kikotools/tools/width_height_to_vec2/node.py

@@ -0,0 +1,128 @@
+"""
+Width Height to VEC2 Node
+
+Converts width and height inputs to a VEC2 tuple for use with
+nodes like jovi_glsl that expect vector inputs.
+"""
+
+from typing import Any, Dict, Tuple, Union
+
+from ...base import ComfyAssetsBaseNode
+
+
+class WidthHeightToVec2Node(ComfyAssetsBaseNode):
+    """
+    Convert width and height values to VEC2 format.
+
+    Accepts INT, FLOAT, STRING, or ANY types and outputs a VEC2 tuple
+    suitable for nodes expecting vector inputs.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls) -> Dict[str, Any]:
+        """Define ComfyUI input interface."""
+        return {
+            "required": {
+                "width": (
+                    "INT",
+                    {
+                        "default": 1024,
+                        "min": 1,
+                        "max": 8192,
+                        "step": 1,
+                        "tooltip": "Width value (x component of VEC2)",
+                    },
+                ),
+                "height": (
+                    "INT",
+                    {
+                        "default": 1024,
+                        "min": 1,
+                        "max": 8192,
+                        "step": 1,
+                        "tooltip": "Height value (y component of VEC2)",
+                    },
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("VEC2",)
+    RETURN_NAMES = ("vec2",)
+    FUNCTION = "convert_to_vec2"
+    CATEGORY = "🫶 ComfyAssets/🖼️ Resolution"
+
+    def convert_to_vec2(
+        self,
+        width: Union[int, float, str, Any],
+        height: Union[int, float, str, Any],
+    ) -> Tuple[Tuple[int, int]]:
+        """
+        Convert width and height to VEC2 tuple.
+
+        Args:
+            width: Width value (will be converted to int)
+            height: Height value (will be converted to int)
+
+        Returns:
+            Tuple containing the VEC2 tuple (width, height)
+        """
+        try:
+            # Convert to integers, handling various input types
+            w = self._to_int(width, "width")
+            h = self._to_int(height, "height")
+
+            # Clamp values to valid range
+            w = max(1, min(8192, w))
+            h = max(1, min(8192, h))
+
+            self.log_info(f"Converted to VEC2: ({w}, {h})")
+
+            # Return as tuple wrapped in tuple (ComfyUI return format)
+            return ((w, h),)
+
+        except Exception as e:
+            error_msg = f"Failed to convert to VEC2: {str(e)}"
+            self.handle_error(error_msg, e)
+
+    def _to_int(self, value: Any, name: str) -> int:
+        """
+        Convert a value to integer.
+
+        Args:
+            value: Value to convert (int, float, str, or any)
+            name: Parameter name for error messages
+
+        Returns:
+            Integer value
+
+        Raises:
+            ValueError: If conversion fails
+        """
+        if isinstance(value, int):
+            return value
+        elif isinstance(value, float):
+            return int(value)
+        elif isinstance(value, str):
+            try:
+                # Try parsing as float first (handles "1024.0")
+                return int(float(value.strip()))
+            except ValueError:
+                raise ValueError(f"Cannot convert {name} string '{value}' to integer")
+        else:
+            # Try generic conversion for ANY type
+            try:
+                return int(value)
+            except (ValueError, TypeError):
+                raise ValueError(
+                    f"Cannot convert {name} of type {type(value).__name__} to integer"
+                )
+
+
+# Node registration
+NODE_CLASS_MAPPINGS = {
+    "WidthHeightToVec2": WidthHeightToVec2Node,
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "WidthHeightToVec2": "Width Height to VEC2",
+}

kikotools/tools/xyz_helpers/flux_sampler_params/logic.py

@@ -1,78 +1,124 @@
 """Logic module for Flux Sampler Params node."""
 
 from typing import List, Dict, Any, Tuple, Optional
+import math
 import random
-import time
 import logging
 
 logger = logging.getLogger(__name__)
 
 
-def parse_string_to_list(value: str) -> List[float]:
+RANDOM_SEED_TOKEN = "?"
+MAX_RANDOM_SEED = 999999
+
+
+def parse_string_to_list(value: str, field: str = "value") -> List[float]:
     """
     Parse a string containing comma-separated values to a list of floats.
 
     Args:
         value: String with comma-separated values
+        field: Name of the input, used in error messages
 
     Returns:
-        List of float values
+        List of float values (empty when the string is blank)
+
+    Raises:
+        ValueError: If any token is not a finite number
     """
     if not value or not value.strip():
         return []
 
-    try:
-        values = []
-        for item in value.split(","):
-            item = item.strip()
-            if item:
-                try:
-                    values.append(float(item))
-                except ValueError:
-                    logger.warning(f"Could not parse '{item}' as float")
-        return values
-    except Exception as e:
-        logger.error(f"Error parsing string to list: {e}")
-        return []
+    values = []
+    for item in value.split(","):
+        item = item.strip()
+        if not item:
+            continue
+        try:
+            number = float(item)
+        except ValueError:
+            raise ValueError(f"Invalid {field} value '{item}': expected a number")
+        if not math.isfinite(number):
+            raise ValueError(f"Invalid {field} value '{item}': must be finite")
+        values.append(number)
+    return values
+
+
+def parse_steps_list(value: str, field: str = "steps") -> List[int]:
+    """
+    Parse comma-separated step counts into positive integers.
+
+    Raises:
+        ValueError: If a token is not a positive whole number
+    """
+    steps = []
+    for number in parse_string_to_list(value, field):
+        if number != int(number) or number < 1:
+            raise ValueError(
+                f"Invalid {field} value '{number:g}': expected a positive integer"
+            )
+        steps.append(int(number))
+    return steps
 
 
 def parse_seed_string(seed_string: str) -> List[int]:
     """
-    Parse seed string which can contain numbers, '?', or ranges.
+    Parse a seed string of comma or newline separated tokens.
 
-    Args:
-        seed_string: String with seeds (e.g., "123,?,456")
+    Each token is either a non-negative integer or the exact token '?',
+    which draws a random seed. A blank string yields one random seed.
+    Ranges are not supported.
 
-    Returns:
-        List of integer seeds
+    Raises:
+        ValueError: If a token is neither an integer nor '?'
     """
     seeds = []
+    for item in seed_string.replace("\n", ",").split(","):
+        item = item.strip()
+        if not item:
+            continue
+        if item == RANDOM_SEED_TOKEN:
+            seeds.append(random.randint(0, MAX_RANDOM_SEED))
+            continue
+        try:
+            seed = int(item)
+        except ValueError:
+            raise ValueError(
+                f"Invalid seed '{item}': use whole numbers or '?' for a random seed"
+            )
+        if seed < 0:
+            raise ValueError(f"Invalid seed '{item}': seeds cannot be negative")
+        seeds.append(seed)
 
-    try:
-        for item in seed_string.replace("\n", ",").split(","):
-            item = item.strip()
-            if not item:
-                continue
-
-            if "?" in item:
-                seeds.append(random.randint(0, 999999))
-            else:
-                try:
-                    seeds.append(int(item))
-                except ValueError:
-                    logger.warning(f"Could not parse seed '{item}'")
-                    seeds.append(random.randint(0, 999999))
-
-        if not seeds:
-            seeds = [random.randint(0, 999999)]
-
-    except Exception as e:
-        logger.error(f"Error parsing seeds: {e}")
-        seeds = [random.randint(0, 999999)]
-
+    if not seeds:
+        seeds = [random.randint(0, MAX_RANDOM_SEED)]
     return seeds
 
 
+def seed_string_is_random(seed_string: str) -> bool:
+    """Return True if the seed string produces a different result each run."""
+    tokens = [t.strip() for t in seed_string.replace("\n", ",").split(",")]
+    tokens = [t for t in tokens if t]
+    return not tokens or RANDOM_SEED_TOKEN in tokens
+
+
+def is_schnell_model(model: Any) -> bool:
+    """
+    Detect Flux Schnell from the unet config.
+
+    Schnell is not guidance distilled (guidance_embed is False) while dev is
+    (guidance_embed is True). Anything unrecognised is treated as dev.
+    """
+    config = getattr(
+        getattr(getattr(model, "model", None), "model_config", None),
+        "unet_config",
+        None,
+    )
+    if not isinstance(config, dict):
+        return False
+    return config.get("guidance_embed") is False
+
+
 def parse_sampler_string(
     sampler_string: str, available_samplers: List[str]
 ) -> List[str]:
@@ -241,14 +287,13 @@ def validate_flux_params(
 
     Returns:
         True if all parameters are valid
+
+    Raises:
+        ValueError: Naming the offending field and token
     """
-    try:
-        parse_string_to_list(steps)
-        parse_string_to_list(guidance)
-        parse_string_to_list(max_shift)
-        parse_string_to_list(base_shift)
-        parse_string_to_list(denoise)
-        return True
-    except Exception as e:
-        logger.error(f"Invalid parameters: {e}")
-        return False
+    parse_steps_list(steps, "steps")
+    parse_string_to_list(guidance, "guidance")
+    parse_string_to_list(max_shift, "max_shift")
+    parse_string_to_list(base_shift, "base_shift")
+    parse_string_to_list(denoise, "denoise")
+    return True

kikotools/tools/xyz_helpers/flux_sampler_params/node.py

@@ -1,12 +1,17 @@
 """Flux Sampler Params node for ComfyUI."""
 
 from typing import Tuple, Any, Dict, List, Optional
+import hashlib
+import json
 import time
 import logging
 from ....base.base_node import ComfyAssetsBaseNode
 from .logic import (
     parse_string_to_list,
+    parse_steps_list,
     parse_seed_string,
+    seed_string_is_random,
+    is_schnell_model,
     parse_sampler_string,
     parse_scheduler_string,
     get_default_flux_params,
@@ -122,10 +127,25 @@ class FluxSamplerParamsNode(ComfyAssetsBaseNode):
             },
         }
 
+    @classmethod
+    def IS_CHANGED(cls, **kwargs):
+        """
+        Re-run every time when seeds are random, otherwise use a stable hash.
+
+        NaN never compares equal to itself, so ComfyUI re-executes the node.
+        """
+        if seed_string_is_random(str(kwargs.get("seed", ""))):
+            return float("nan")
+        widgets = {
+            key: value for key, value in kwargs.items() if isinstance(value, str)
+        }
+        payload = json.dumps(widgets, sort_keys=True)
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
     RETURN_TYPES = ("LATENT", "SAMPLER_PARAMS")
     RETURN_NAMES = ("latent", "params")
     FUNCTION = "process_batch"
-    CATEGORY = "ComfyAssets/🧰 xyz-helpers"
+    CATEGORY = "🫶 ComfyAssets/🧰 xyz-helpers"
 
     def process_batch(
         self,
@@ -150,15 +170,15 @@ class FluxSamplerParamsNode(ComfyAssetsBaseNode):
         """
         try:
             import comfy.samplers
-            import comfy.model_base
             import comfy.model_management
+            import comfy.utils
+            import torch
             from comfy_extras.nodes_custom_sampler import (
                 Noise_RandomNoise,
                 BasicScheduler,
                 BasicGuider,
                 SamplerCustomAdvanced,
             )
-            from comfy_extras.nodes_latent import LatentBatch
             from comfy_extras.nodes_model_advanced import (
                 ModelSamplingFlux,
                 ModelSamplingAuraFlow,
@@ -170,13 +190,43 @@ class FluxSamplerParamsNode(ComfyAssetsBaseNode):
             self.handle_error(f"Required ComfyUI modules not available: {e}")
             return (latent_image, [])
 
-        try:
-            if not validate_flux_params(
-                steps, guidance, max_shift, base_shift, denoise
-            ):
-                self.handle_error("Invalid parameter format")
+        # Local implementation of LatentBatch functionality
+        # Copied from nodes_latent.py to avoid V3 schema breaking changes
+        def reshape_latent_to(target_shape, latent, repeat_batch=True):
+            """Reshape latent tensor to match target shape."""
+            if latent.shape[1:] != target_shape[1:]:
+                latent = comfy.utils.common_upscale(
+                    latent, target_shape[-1], target_shape[-2], "bilinear", "center"
+                )
+            if repeat_batch:
+                return comfy.utils.repeat_to_batch_size(latent, target_shape[0])
+            else:
+                return latent
 
-            is_schnell = model.model.model_type == comfy.model_base.ModelType.FLOW
+        def batch_latents(samples1, samples2):
+            """Batch two latent samples together."""
+            samples_out = samples1.copy()
+            s1 = samples1["samples"]
+            s2 = samples2["samples"]
+
+            s2 = reshape_latent_to(s1.shape, s2, repeat_batch=False)
+            s = torch.cat((s1, s2), dim=0)
+            samples_out["samples"] = s
+            samples_out["batch_index"] = samples1.get(
+                "batch_index", [x for x in range(0, s1.shape[0])]
+            ) + samples2.get("batch_index", [x for x in range(0, s2.shape[0])])
+            return samples_out
+
+        try:
+            validate_flux_params(steps, guidance, max_shift, base_shift, denoise)
+
+            if loras is not None and not loras.get("loras"):
+                raise ValueError(
+                    "LoRA input contains no LoRAs (is the LoRA folder empty "
+                    "or fully filtered?)"
+                )
+
+            is_schnell = is_schnell_model(model)
             defaults = get_default_flux_params(is_schnell)
 
             seeds = parse_seed_string(seed)
@@ -186,13 +236,13 @@ class FluxSamplerParamsNode(ComfyAssetsBaseNode):
             )
 
             steps = steps if steps else str(defaults["steps"])
-            steps_list = [int(s) for s in parse_string_to_list(steps)]
+            steps_list = parse_steps_list(steps)
 
             guidance = guidance if guidance else str(defaults["guidance"])
-            guidance_list = parse_string_to_list(guidance)
+            guidance_list = parse_string_to_list(guidance, "guidance")
 
             denoise = denoise if denoise else "1.0"
-            denoise_list = parse_string_to_list(denoise)
+            denoise_list = parse_string_to_list(denoise, "denoise")
 
             if not is_schnell:
                 max_shift = max_shift if max_shift else str(defaults["max_shift"])
@@ -201,8 +251,8 @@ class FluxSamplerParamsNode(ComfyAssetsBaseNode):
                 max_shift = "0"
                 base_shift = base_shift if base_shift else str(defaults["base_shift"])
 
-            max_shift_list = parse_string_to_list(max_shift)
-            base_shift_list = parse_string_to_list(base_shift)
+            max_shift_list = parse_string_to_list(max_shift, "max_shift")
+            base_shift_list = parse_string_to_list(base_shift, "base_shift")
 
             cond_text, cond_encoded = process_conditioning_input(conditioning)
 
@@ -231,12 +281,17 @@ class FluxSamplerParamsNode(ComfyAssetsBaseNode):
                 lora_strength_count,
             )
 
+            if total_samples < 1:
+                raise ValueError(
+                    "No parameter combinations to run: check that seed, sampler, "
+                    "scheduler, steps, guidance and denoise each yield a value"
+                )
+
             self.log_info(f"Processing {total_samples} parameter combinations")
 
             basicscheduler = BasicScheduler()
             basicguider = BasicGuider()
             samplercustomadvanced = SamplerCustomAdvanced()
-            latentbatch = LatentBatch()
             modelsampling = (
                 ModelSamplingFlux() if not is_schnell else ModelSamplingAuraFlow()
             )
@@ -352,13 +407,19 @@ class FluxSamplerParamsNode(ComfyAssetsBaseNode):
                                 < len(lora_strength[lora_file_idx])
                                 else 0
                             )
+                            # Add batch info if available
+                            if "batch_info" in loras:
+                                param_record["lora_batch"] = (
+                                    f"Batch {loras['batch_info']['index'] + 1}/"
+                                    f"{loras['batch_info']['total']}"
+                                )
 
                         out_params.append(param_record)
 
                         if out_latent is None:
                             out_latent = latent
                         else:
-                            out_latent = latentbatch.batch(out_latent, latent)[0]
+                            out_latent = batch_latents(out_latent, latent)
 
                         if total_samples > 1:
                             pbar.update(1)

kikotools/tools/xyz_helpers/lora_folder_batch/logic.py

@@ -1,13 +1,17 @@
 """Logic module for LoRA Folder Batch node."""
 
+import math
 import os
 import re
-from typing import List, Dict, Any, Tuple, Optional
-from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
 import logging
 
 logger = logging.getLogger(__name__)
 
+MAX_STRENGTH_VALUES = 1000
+DEFAULT_RANGE_STEP = 0.1
+_RANGE_EPSILON = 1e-4
+
 
 def get_lora_folders() -> List[str]:
     """
@@ -36,92 +40,129 @@ def get_lora_folders() -> List[str]:
         return [".", "flux", "sdxl", "sd15"]
 
 
+def _get_lora_roots() -> List[str]:
+    """Return every configured loras root directory (empty if unavailable)."""
+    try:
+        import folder_paths
+
+        entry = folder_paths.folder_names_and_paths.get("loras")
+        return list(entry[0]) if entry else []
+    except (ImportError, AttributeError, IndexError, TypeError):
+        return []
+
+
+def _is_within(path: str, root: str) -> bool:
+    """True if realpath `path` equals or is inside realpath `root`."""
+    try:
+        real_path, real_root = os.path.realpath(path), os.path.realpath(root)
+        return os.path.commonpath([real_path, real_root]) == real_root
+    except ValueError:  # different drives or mixed absolute/relative
+        return False
+
+
+def _resolve_scan_targets(folder_path: str) -> List[Tuple[str, Optional[str]]]:
+    """
+    Resolve a folder setting to (directory, base_root) pairs to scan.
+
+    base_root is the loras root the directory lives in, or None when the
+    directory is an absolute path outside every known root.
+    """
+    roots = _get_lora_roots()
+
+    if os.path.isabs(folder_path):
+        base = next((r for r in roots if _is_within(folder_path, r)), None)
+        return [(folder_path, base)]
+
+    targets = []
+    for root in roots:
+        candidate = os.path.join(root, folder_path)
+        if not _is_within(candidate, root):
+            logger.warning(f"Folder escapes the loras directory: {folder_path}")
+            continue
+        targets.append((candidate, root))
+    return targets
+
+
+def _scan_entries(folder_path: str) -> List[Tuple[str, str]]:
+    """Return (relative_name, absolute_path) for every .safetensors found."""
+    entries: Dict[str, str] = {}
+    for directory, base in _resolve_scan_targets(folder_path):
+        if not os.path.isdir(directory):
+            continue
+        for root, _, files in os.walk(directory):
+            for file in files:
+                if not file.endswith(".safetensors"):
+                    continue
+                full = os.path.join(root, file)
+                try:
+                    rel = os.path.relpath(full, base or directory)
+                except ValueError:
+                    rel = os.path.relpath(full, directory)
+                entries.setdefault(rel.replace("\\", "/"), full)
+    return [(name, entries[name]) for name in natural_sort(list(entries))]
+
+
 def scan_folder_for_loras(folder_path: str) -> List[str]:
     """
     Scan a folder for LoRA files (.safetensors).
 
+    Relative folders are searched in every configured loras root. Absolute
+    folders are matched to a root by real-path containment (so a sibling like
+    ``loras_backup`` is not mistaken for ``loras``).
+
     Args:
-        folder_path: Path to folder to scan (absolute or relative to models/loras)
+        folder_path: Folder to scan (absolute or relative to the loras roots)
 
     Returns:
-        List of LoRA filenames relative to models/loras directory
+        Naturally sorted LoRA names relative to their loras root (or to the
+        scanned folder when it lies outside every root)
     """
-    try:
-        import folder_paths
+    names = [name for name, _ in _scan_entries(folder_path)]
+    if not names:
+        logger.warning(f"No LoRA files found in {folder_path}")
+    else:
+        logger.info(f"Found {len(names)} LoRA files in {folder_path}")
+    return names
 
-        # Get all LoRA paths from ComfyUI (includes extra_model_paths)
-        lora_paths = folder_paths.folder_names_and_paths.get("loras", [[]])[0]
 
-        # Check if this is an absolute path
-        if os.path.isabs(folder_path):
-            full_path = folder_path
+def get_lora_file_mtimes(folder_path: str) -> List[Tuple[str, float]]:
+    """Return sorted (name, mtime) pairs for LoRAs in a folder."""
+    result = []
+    for name, full in _scan_entries(folder_path):
+        try:
+            result.append((name, os.path.getmtime(full)))
+        except OSError:
+            result.append((name, -1.0))
+    return result
 
-            # Try to find which lora base path this belongs to
-            rel_folder = None
-            for lora_base in lora_paths:
-                try:
-                    potential_rel = os.path.relpath(full_path, lora_base)
-                    if not potential_rel.startswith(".."):
-                        # This path is inside this lora base
-                        rel_folder = potential_rel
-                        break
-                except ValueError:
-                    # Different drives on Windows
-                    continue
 
-            if rel_folder is None:
-                # Path is outside all known lora directories
-                # Try to extract a relative path that might work
-                # Check if path contains common lora folder structures
-                path_parts = full_path.replace("\\", "/").split("/")
-                if "lora" in path_parts or "loras" in path_parts:
-                    # Find index after lora/loras
-                    for i, part in enumerate(path_parts):
-                        if part in ["lora", "loras"]:
-                            # Use everything after lora/loras as relative path
-                            rel_folder = "/".join(path_parts[i + 1 :])
-                            break
+def sort_lora_files(lora_files: List[str], sort_order: str) -> List[str]:
+    """
+    Sort LoRA files based on the specified order.
 
-                if rel_folder is None:
-                    # Last resort: use last two directories as relative path
-                    rel_folder = (
-                        "/".join(path_parts[-2:])
-                        if len(path_parts) >= 2
-                        else path_parts[-1]
-                    )
-        else:
-            # Relative path provided
-            full_path = (
-                os.path.join(lora_paths[0], folder_path) if lora_paths else folder_path
-            )
-            rel_folder = folder_path if folder_path != "." else ""
+    Args:
+        lora_files: List of LoRA file paths
+        sort_order: Type of sorting ("natural", "alphabetical", "newest", "oldest")
 
-        if not os.path.exists(full_path):
-            logger.warning(f"Folder does not exist: {full_path}")
-            return []
-
-        # Scan for .safetensors files
-        lora_files = []
-        for file in os.listdir(full_path):
-            if file.endswith(".safetensors"):
-                # Store relative path from lora base
-                if rel_folder and rel_folder != ".":
-                    lora_files.append(os.path.join(rel_folder, file).replace("\\", "/"))
-                else:
-                    lora_files.append(file)
-
-        # Sort naturally (handles epoch numbers properly)
-        lora_files = natural_sort(lora_files)
-
-        logger.info(
-            f"Found {len(lora_files)} LoRA files in {folder_path}, returning paths relative to lora base"
-        )
+    Returns:
+        Sorted list of LoRA files
+    """
+    if sort_order == "natural":
+        return natural_sort(lora_files)
+    elif sort_order == "alphabetical":
+        return sorted(lora_files)
+    elif sort_order in ["newest", "oldest"]:
+        # For time-based sorting, we need the actual file stats
+        # Since we only have relative paths, we'll sort by name for now
+        # This could be enhanced if we have access to file stats
+        sorted_files = natural_sort(lora_files)
+        if sort_order == "oldest":
+            return sorted_files
+        else:  # newest
+            return sorted_files[::-1]
+    else:
         return lora_files
 
-    except Exception as e:
-        logger.error(f"Error scanning folder {folder_path}: {e}")
-        return []
-
 
 def natural_sort(items: List[str]) -> List[str]:
     """
@@ -140,10 +181,17 @@ def natural_sort(items: List[str]) -> List[str]:
 
         # Split on digits and filter out empty strings
         parts = [atoi(c) for c in re.split(r"(\d+)", text) if c]
-        # Put files without numbers first
-        if not any(isinstance(p, int) for p in parts):
-            return [0] + parts
-        return parts
+
+        # Convert to tuple of (type_order, value) to ensure consistent comparison
+        # Integers get type_order 0, strings get type_order 1
+        typed_parts = []
+        for part in parts:
+            if isinstance(part, int):
+                typed_parts.append((0, part))
+            else:
+                typed_parts.append((1, part))
+
+        return typed_parts
 
     return sorted(items, key=natural_key)
 
@@ -183,66 +231,82 @@ def filter_loras_by_pattern(
     return filtered
 
 
+def _parse_finite(token: str, what: str, original: str) -> float:
+    try:
+        value = float(token.strip())
+    except ValueError:
+        raise ValueError(f"Invalid strength {what} '{token.strip()}' in '{original}'")
+    if not math.isfinite(value):
+        raise ValueError(f"Invalid strength {what} '{token.strip()}' in '{original}'")
+    return value
+
+
+def _parse_strength_range(text: str) -> List[float]:
+    """Parse 'start...end' or 'start...end+step'."""
+    parts = text.split("...")
+    if len(parts) != 2:
+        raise ValueError(f"Invalid strength range '{text}': use start...end[+step]")
+    start = _parse_finite(parts[0], "start", text)
+
+    end_part = parts[1]
+    if "+" in end_part:
+        pieces = end_part.split("+")
+        if len(pieces) != 2:
+            raise ValueError(f"Invalid strength range '{text}': use start...end[+step]")
+        end = _parse_finite(pieces[0], "end", text)
+        step = _parse_finite(pieces[1], "step", text)
+    else:
+        end = _parse_finite(end_part, "end", text)
+        step = DEFAULT_RANGE_STEP
+
+    if step <= 0:
+        raise ValueError(
+            f"Invalid strength range '{text}': step must be greater than 0"
+        )
+    if end < start:
+        raise ValueError(
+            f"Invalid strength range '{text}': reversed range "
+            f"(start {start:g} is greater than end {end:g})"
+        )
+
+    count = int(math.floor((end - start) / step + _RANGE_EPSILON)) + 1
+    if count > MAX_STRENGTH_VALUES:
+        raise ValueError(
+            f"Strength range '{text}' would generate {count} values; "
+            f"the maximum is {MAX_STRENGTH_VALUES}"
+        )
+    return [round(start + i * step, 4) for i in range(count)]
+
+
 def parse_strength_string(strength_str: str) -> List[float]:
     """
     Parse strength string into list of values.
 
     Supports:
+    - Blank: defaults to [1.0]
     - Single value: "1.0"
     - Multiple values: "0.5, 0.75, 1.0"
-    - Range: "0.5...1.0" (with optional step)
+    - Range: "0.5...1.0" (default step 0.1) or "0.5...1.0+0.25"
 
-    Args:
-        strength_str: String representation of strengths
-
-    Returns:
-        List of strength values
+    Raises:
+        ValueError: On malformed input, non-positive step, reversed range, or
+            more than MAX_STRENGTH_VALUES generated values.
     """
     strength_str = strength_str.strip()
-
     if not strength_str:
         return [1.0]
 
-    # Check for range notation
     if "..." in strength_str:
-        parts = strength_str.split("...")
-        if len(parts) == 2:
-            try:
-                start = float(parts[0].strip())
-                end_part = parts[1].strip()
+        return _parse_strength_range(strength_str)
 
-                # Check for step
-                if "+" in end_part:
-                    end_str, step_str = end_part.split("+")
-                    end = float(end_str.strip())
-                    step = float(step_str.strip())
-                else:
-                    end = float(end_part)
-                    step = 0.1  # Default step
-
-                # Generate range
-                values = []
-                current = start
-                while current <= end + 0.0001:  # Small epsilon for float comparison
-                    values.append(round(current, 4))
-                    current += step
-
-                return values
-            except ValueError as e:
-                logger.error(f"Invalid range format: {e}")
-                return [1.0]
-
-    # Parse comma-separated values
-    try:
-        values = []
-        for item in strength_str.split(","):
-            item = item.strip()
-            if item:
-                values.append(float(item))
-        return values if values else [1.0]
-    except ValueError as e:
-        logger.error(f"Invalid strength values: {e}")
-        return [1.0]
+    values = [
+        _parse_finite(item, "value", strength_str)
+        for item in strength_str.split(",")
+        if item.strip()
+    ]
+    if not values:
+        raise ValueError(f"No strength values found in '{strength_str}'")
+    return values
 
 
 def create_lora_params(
@@ -263,6 +327,9 @@ def create_lora_params(
         logger.warning("No LoRA files provided")
         return {"loras": [], "strengths": []}
 
+    if not strengths:
+        raise ValueError("At least one strength value is required")
+
     if batch_mode == "combinatorial":
         # Each LoRA gets tested with each strength
         # This creates len(loras) * len(strengths) combinations
@@ -278,6 +345,57 @@ def create_lora_params(
         return {"loras": lora_files, "strengths": strength_lists}
 
 
+def create_lora_params_batched(
+    lora_files: List[str],
+    strengths: List[float],
+    batch_mode: str = "sequential",
+    batch_size: int = 25,
+) -> List[Dict[str, Any]]:
+    """
+    Create multiple LORA_PARAMS structures for FluxSamplerParams, batched for stability.
+
+    Args:
+        lora_files: List of LoRA file paths
+        strengths: List of strength values to test
+        batch_mode: How to batch ("sequential" or "combinatorial")
+        batch_size: Maximum number of LoRAs per batch
+
+    Returns:
+        List of LORA_PARAMS dictionaries, each with batch info
+    """
+    if not lora_files:
+        logger.warning("No LoRA files provided")
+        return [{"loras": [], "strengths": [], "batch_info": {"index": 0, "total": 0}}]
+
+    # Split lora_files into batches
+    batches = []
+    total_batches = (len(lora_files) + batch_size - 1) // batch_size
+
+    for i in range(0, len(lora_files), batch_size):
+        batch_loras = lora_files[i : i + batch_size]
+        batch_index = i // batch_size
+
+        # Create params for this batch
+        params = create_lora_params(batch_loras, strengths, batch_mode)
+
+        # Add batch tracking info
+        params["batch_info"] = {
+            "index": batch_index,
+            "total": total_batches,
+            "start_idx": i,
+            "end_idx": min(i + batch_size, len(lora_files)),
+            "size": len(batch_loras),
+        }
+
+        batches.append(params)
+
+    logger.info(f"Created {total_batches} batches of LoRAs (batch size: {batch_size})")
+    for i, batch in enumerate(batches):
+        logger.info(f"  Batch {i}: {batch['batch_info']['size']} LoRAs")
+
+    return batches
+
+
 def get_lora_info(lora_file: str) -> Dict[str, Any]:
     """
     Extract information from LoRA filename.
@@ -312,23 +430,15 @@ def validate_folder_path(folder_path: str) -> bool:
     """
     Validate that the folder path exists and is accessible.
 
-    Args:
-        folder_path: Folder path to validate
-
-    Returns:
-        True if valid
+    Relative paths are accepted if they exist inside any loras root.
     """
     try:
-        import folder_paths
-
-        lora_base_path = folder_paths.folder_names_and_paths["loras"][0][0]
-
-        if folder_path == ".":
-            full_path = lora_base_path
-        else:
-            full_path = os.path.join(lora_base_path, folder_path)
-
-        return os.path.exists(full_path) and os.path.isdir(full_path)
+        if os.path.isabs(folder_path):
+            return os.path.isdir(folder_path)
 
+        return any(
+            os.path.isdir(directory)
+            for directory, _ in _resolve_scan_targets(folder_path)
+        )
     except Exception:
         return False

kikotools/tools/xyz_helpers/lora_folder_batch/node.py

@@ -1,15 +1,17 @@
 """LoRA Folder Batch node for ComfyUI."""
 
-from typing import Tuple, Any, Dict, List
-import os
+from typing import Tuple, Any, Dict
+import hashlib
+import json
 import logging
 from ....base.base_node import ComfyAssetsBaseNode
 from .logic import (
-    get_lora_folders,
     scan_folder_for_loras,
+    get_lora_file_mtimes,
     filter_loras_by_pattern,
     parse_strength_string,
     create_lora_params,
+    create_lora_params_batched,
     get_lora_info,
     validate_folder_path,
 )
@@ -74,21 +76,67 @@ class LoRAFolderBatchNode(ComfyAssetsBaseNode):
                         "tooltip": "Regex pattern to exclude files (e.g., 'test|backup')",
                     },
                 ),
+                "max_loras": (
+                    "INT",
+                    {
+                        "default": 50,
+                        "min": 1,
+                        "max": 500,
+                        "tooltip": "Maximum number of LoRAs to process (to prevent UI disconnection)",
+                    },
+                ),
+                "auto_batch": (
+                    ["disabled", "enabled"],
+                    {
+                        "default": "disabled",
+                        "tooltip": "Auto-batch large sets into chunks of 25 LoRAs",
+                    },
+                ),
+                "batch_size": (
+                    "INT",
+                    {
+                        "default": 25,
+                        "min": 5,
+                        "max": 100,
+                        "tooltip": "Number of LoRAs per batch when auto-batching",
+                    },
+                ),
+                "batch_index": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 100,
+                        "tooltip": "Which batch to output (0-based index)",
+                    },
+                ),
+                "sort_order": (
+                    ["natural", "alphabetical", "newest", "oldest"],
+                    {
+                        "default": "natural",
+                        "tooltip": "How to sort the LoRA files",
+                    },
+                ),
             },
         }
 
     RETURN_TYPES = ("LORA_PARAMS", "STRING", "INT")
     RETURN_NAMES = ("lora_params", "lora_list", "lora_count")
     FUNCTION = "batch_loras"
-    CATEGORY = "ComfyAssets/🧰 xyz-helpers"
+    CATEGORY = "🫶 ComfyAssets/🧰 xyz-helpers"
 
-    def batch_loras(
+    def batch_loras(  # noqa: C901
         self,
         folder_path: str,
         strength: str,
         batch_mode: str,
         include_pattern: str = "",
         exclude_pattern: str = "",
+        max_loras: int = 50,
+        sort_order: str = "natural",
+        auto_batch: str = "disabled",
+        batch_size: int = 25,
+        batch_index: int = 0,
     ) -> Tuple[Dict[str, Any], str, int]:
         """
         Batch process LoRAs from a folder.
@@ -137,37 +185,98 @@ class LoRAFolderBatchNode(ComfyAssetsBaseNode):
                 self.log_info("No LoRAs left after filtering")
                 return ({"loras": [], "strengths": []}, "", 0)
 
+            # Apply sorting based on sort_order
+            if sort_order != "natural":
+                from .logic import sort_lora_files
+
+                lora_files = sort_lora_files(lora_files, sort_order)
+
+            # Only limit if NOT auto-batching
+            if auto_batch == "disabled" and len(lora_files) > max_loras:
+                self.log_info(
+                    f"⚠️ Limiting to {max_loras} LoRAs (found {len(lora_files)}). "
+                    f"Enable auto_batch or increase max_loras to process more."
+                )
+                lora_files = lora_files[:max_loras]
+
             # Parse strength values
             strengths = parse_strength_string(strength)
             self.log_info(f"Using strength values: {strengths}")
 
-            # Create LORA_PARAMS
-            lora_params = create_lora_params(lora_files, strengths, batch_mode)
+            # Create LORA_PARAMS with auto-batching if enabled
+            if auto_batch == "enabled" and len(lora_files) > batch_size:
+                all_batches = create_lora_params_batched(
+                    lora_files, strengths, batch_mode, batch_size
+                )
 
-            # Create info string
+                # Check if batch_index is valid
+                if batch_index >= len(all_batches):
+                    self.log_info(
+                        f"⚠️ Batch index {batch_index} out of range. "
+                        f"Only {len(all_batches)} batches available. Using batch 0."
+                    )
+                    batch_index = 0
+
+                lora_params = all_batches[batch_index]
+
+                # Update lora_files to only include current batch for list display
+                batch_start = lora_params["batch_info"]["start_idx"]
+                batch_end = lora_params["batch_info"]["end_idx"]
+                lora_files_for_display = lora_files[batch_start:batch_end]
+            else:
+                # Regular single batch mode
+                lora_params = create_lora_params(lora_files, strengths, batch_mode)
+                lora_files_for_display = lora_files
+
+            # Create info string for current batch only
             lora_list = []
-            for lora_file in lora_files:
+            for lora_file in lora_files_for_display:
                 info = get_lora_info(lora_file)
                 if info["epoch"] is not None:
                     lora_list.append(f"{info['name']} (epoch {info['epoch']})")
                 else:
                     lora_list.append(info["name"])
 
-            lora_list_str = "\n".join(lora_list)
-
-            # Calculate total combinations
-            if batch_mode == "combinatorial":
-                total_combos = len(lora_files) * len(strengths)
+            # Add batch info to the list string if auto-batching
+            if auto_batch == "enabled" and "batch_info" in lora_params:
+                batch_header = (
+                    f"=== Batch {batch_index + 1}/{lora_params['batch_info']['total']} "
+                    f"(LoRAs {lora_params['batch_info']['start_idx'] + 1}-"
+                    f"{lora_params['batch_info']['end_idx']}) ===\n\n"
+                )
+                lora_list_str = batch_header + "\n".join(lora_list)
             else:
-                total_combos = len(lora_files)
+                lora_list_str = "\n".join(lora_list)
 
-            self.log_info(
-                f"Created batch with {len(lora_files)} LoRAs, "
-                f"{len(strengths)} strength values, "
-                f"{total_combos} total combinations"
-            )
+            # Calculate total combinations for current batch
+            current_batch_loras = len(lora_files_for_display)
+            if batch_mode == "combinatorial":
+                total_combos = current_batch_loras * len(strengths)
+            else:
+                total_combos = current_batch_loras
 
-            return (lora_params, lora_list_str, len(lora_files))
+            # Warn if generating many combinations
+            if total_combos > 100:
+                self.log_info(
+                    f"⚠️ WARNING: Generating {total_combos} combinations! "
+                    f"This may cause UI disconnection. Consider reducing max_loras or strength values."
+                )
+
+            if auto_batch == "enabled" and "batch_info" in lora_params:
+                self.log_info(
+                    f"Output batch {batch_index + 1}/{lora_params['batch_info']['total']} "
+                    f"with {current_batch_loras} LoRAs, "
+                    f"{len(strengths)} strength values, "
+                    f"{total_combos} total combinations"
+                )
+            else:
+                self.log_info(
+                    f"Created batch with {current_batch_loras} LoRAs, "
+                    f"{len(strengths)} strength values, "
+                    f"{total_combos} total combinations"
+                )
+
+            return (lora_params, lora_list_str, current_batch_loras)
 
         except Exception as e:
             self.handle_error(f"Error creating LoRA batch: {str(e)}", e)
@@ -176,10 +285,28 @@ class LoRAFolderBatchNode(ComfyAssetsBaseNode):
     @classmethod
     def IS_CHANGED(cls, **kwargs):
         """
-        Force re-execution when folder contents might have changed.
+        Re-execute only when the folder listing or the inputs change.
 
-        This ensures we always scan for the latest LoRAs.
+        Returns a hash of the matching files with their mtimes plus the
+        relevant inputs, so downstream nodes stay cached otherwise.
         """
-        import time
+        folder_path = str(kwargs.get("folder_path", "."))
+        files = get_lora_file_mtimes(folder_path)
+        if kwargs.get("include_pattern") or kwargs.get("exclude_pattern"):
+            keep = set(
+                filter_loras_by_pattern(
+                    [name for name, _ in files],
+                    kwargs.get("include_pattern", "") or "",
+                    kwargs.get("exclude_pattern", "") or "",
+                )
+            )
+            files = [(name, mtime) for name, mtime in files if name in keep]
 
-        return str(time.time())
+        payload = json.dumps(
+            {
+                "files": files,
+                "inputs": {k: repr(v) for k, v in sorted(kwargs.items())},
+            },
+            sort_keys=True,
+        )
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()

kikotools/tools/xyz_helpers/plot_sampler_params/logic.py

@@ -1,10 +1,9 @@
 """Logic module for Plot Parameters node."""
 
-from typing import List, Dict, Any, Tuple, Optional
+from typing import List, Dict, Tuple
 import math
 import textwrap
 import logging
-import torch
 
 logger = logging.getLogger(__name__)
 
@@ -202,8 +201,27 @@ def format_parameter_text(param: Dict, mode: str = "full") -> str:
 
         # Optional LoRA line
         if "lora" in param and param["lora"]:
-            lora_name = param["lora"][:32] if len(param["lora"]) > 32 else param["lora"]
-            lines.append(f"LoRA: {lora_name}, str: {param.get('lora_strength', 'N/A')}")
+            lora_path = param["lora"]
+            # Extract just the filename and immediate parent directory for better readability
+            path_parts = lora_path.replace("\\", "/").split("/")
+            if len(path_parts) > 2:
+                # Show parent directory and filename
+                lora_display = f"{path_parts[-2]}/{path_parts[-1]}"
+            else:
+                # Use full path if it's short
+                lora_display = lora_path
+
+            # Remove file extension for cleaner display
+            if lora_display.endswith(".safetensors"):
+                lora_display = lora_display[:-12]
+
+            lora_line = (
+                f"LoRA: {lora_display}, str: {param.get('lora_strength', 'N/A')}"
+            )
+            # Add batch info if available
+            if "lora_batch" in param:
+                lora_line += f" [{param['lora_batch']}]"
+            lines.append(lora_line)
 
         return "\n".join(lines)
 

kikotools/tools/xyz_helpers/plot_sampler_params/node.py

@@ -38,7 +38,6 @@ from .logic import (
     filter_changing_params,
     format_parameter_text,
     wrap_prompt_text,
-    calculate_text_dimensions,
     calculate_grid_dimensions,
     validate_plot_parameters,
 )
@@ -113,7 +112,7 @@ class PlotParametersNode(ComfyAssetsBaseNode):
     RETURN_TYPES = ("IMAGE",)
     RETURN_NAMES = ("image",)
     FUNCTION = "plot_parameters"
-    CATEGORY = "ComfyAssets/🧰 xyz-helpers"
+    CATEGORY = "🫶 ComfyAssets/🧰 xyz-helpers"
 
     def plot_parameters(
         self,
@@ -174,11 +173,11 @@ class PlotParametersNode(ComfyAssetsBaseNode):
             # Get font
             font_path = self._get_font_path()
             width = images.shape[2]
-            font_size = min(48, int(32 * (width / 1024)))
+            font_size = max(1, min(48, int(32 * (width / 1024))))
 
             try:
                 font = ImageFont.truetype(font_path, font_size)
-            except:
+            except (IOError, OSError):
                 logger.warning(f"Could not load font from {font_path}, using default")
                 font = ImageFont.load_default()
 

kikotools/tools/xyz_helpers/sampler_select_helper/logic.py

@@ -1,6 +1,6 @@
 """Logic module for Sampler Select Helper node."""
 
-from typing import List, Dict, Any
+from typing import List, Dict
 import logging
 
 logger = logging.getLogger(__name__)

kikotools/tools/xyz_helpers/sampler_select_helper/node.py

@@ -30,7 +30,7 @@ class SamplerSelectHelperNode(ComfyAssetsBaseNode):
     RETURN_TYPES = ("STRING",)
     RETURN_NAMES = ("selected_samplers",)
     FUNCTION = "select_samplers"
-    CATEGORY = "ComfyAssets/🧰 xyz-helpers"
+    CATEGORY = "🫶 ComfyAssets/🧰 xyz-helpers"
 
     def select_samplers(self, **sampler_flags) -> Tuple[str]:
         """

kikotools/tools/xyz_helpers/scheduler_select_helper/logic.py

@@ -1,6 +1,6 @@
 """Logic module for Scheduler Select Helper node."""
 
-from typing import List, Dict, Any
+from typing import List, Dict
 import logging
 
 logger = logging.getLogger(__name__)