chore(release): 1.3.0 with the Model Resolution Picker

- PR #108 changed pyproject.toml without bumping the version, so the
  registry publish on main failed with "The node version already exists".
- Bump to 1.3.0 (new node, route and override file) and add the release
  notes to CHANGELOG.md and the README.

.comfyignore

@@ -0,0 +1,29 @@
+# Files excluded from the Comfy Registry archive (gitignore syntax).
+# Everything here is development-only; the published node needs
+# __init__.py, kikotools/, web/, examples/, README, LICENSE, pyproject.toml.
+
+# Test suite and tooling
+tests/
+scripts/
+.github/
+Makefile
+pytest.ini
+mypy.ini
+.flake8
+.pre-commit-config.yaml
+.secrets.baseline
+requirements-dev.txt
+
+# Reference / scratch code not imported by the node
+example.py
+
+# Agent and contributor docs
+CLAUDE.md
+CONTRIBUTING.md
+CODE_OF_CONDUCT.md
+
+tools/
+.ci-comfyui/
+coverage/
+TESTING.md
+AGENTS.md

.flake8

@@ -1,7 +1,8 @@
 [flake8]
 max-line-length = 127
 max-complexity = 10
-exclude = 
+exclude =
+    node_modules,
     .git,
     __pycache__,
     .mypy_cache,
@@ -11,8 +12,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 +34,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/branch-protection.json

@@ -0,0 +1,16 @@
+{
+  "required_status_checks": {
+    "strict": true,
+    "contexts": [
+      "py3.10 on ubuntu-latest", "py3.11 on ubuntu-latest", "py3.12 on ubuntu-latest", "py3.13 on ubuntu-latest",
+      "py3.10 on windows-latest", "py3.11 on windows-latest", "py3.12 on windows-latest", "py3.13 on windows-latest",
+      "py3.10 on macos-latest", "py3.11 on macos-latest", "py3.12 on macos-latest", "py3.13 on macos-latest",
+      "coverage gate (85%)", "frontend syntax", "frontend workflows and coverage", "real ComfyUI compatibility", "code-quality"
+    ]
+  },
+  "enforce_admins": true,
+  "required_pull_request_reviews": null,
+  "restrictions": null,
+  "allow_force_pushes": false,
+  "allow_deletions": false
+}

.github/dependabot.yml

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

.github/workflows/code-quality.yml

@@ -13,15 +13,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
     - name: Cache pip dependencies
-      uses: actions/cache@v4
+      uses: actions/cache@v6
       with:
         path: ~/.cache/pip
         key: ${{ runner.os }}-pip-quality-${{ hashFiles('**/requirements-dev.txt') }}
@@ -31,6 +31,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
+        pip install torch --index-url https://download.pytorch.org/whl/cpu
         pip install -r requirements-dev.txt
 
     - name: Format check with Black
@@ -141,10 +142,10 @@ jobs:
   security:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
@@ -172,16 +173,17 @@ jobs:
   architecture:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
+        pip install torch --index-url https://download.pytorch.org/whl/cpu
         pip install -r requirements-dev.txt
 
     - name: Check architecture compliance

.github/workflows/publish.yml

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

.github/workflows/release.yml

@@ -10,55 +10,28 @@ on:
 
 jobs:
   create-release:
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
     runs-on: ubuntu-latest
     permissions:
       contents: write
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
 
     - name: Set up Python 3.10
-      uses: actions/setup-python@v6
+      uses: actions/setup-python@v7
       with:
         python-version: '3.10'
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
+        pip install torch --index-url https://download.pytorch.org/whl/cpu
         pip install -r requirements-dev.txt
 
-    - name: Run full test suite
-      run: |
-        python -c "
-        import sys
-        import os
-        sys.path.insert(0, os.getcwd())
-
-        # Run comprehensive tests before release
-        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('Running pre-release validation...')
-
-        # Test all major functionality
-        node = ResolutionCalculatorNode()
-
-        # Test various scenarios
-        test_cases = [
-            (torch.randn(1, 512, 512, 3), 2.0),
-            (torch.randn(1, 1024, 1024, 3), 1.5),
-            (torch.randn(1, 1216, 832, 3), 1.53),  # User scenario
-        ]
-
-        for i, (image, scale) in enumerate(test_cases):
-            width, height = node.calculate_resolution(scale, image=image)
-            print(f'✓ Test case {i+1}: {image.shape[2]}×{image.shape[1]} → {width}×{height} (scale: {scale})')
-            assert width % 8 == 0 and height % 8 == 0
-
-        print('🎉 All pre-release tests passed!')
-        "
+    - name: Run full test suite and coverage gate
+      run: python -m pytest tests --cov=kikotools --cov-report=term-missing
 
     - name: Extract version from tag
       id: get_version
@@ -100,7 +73,7 @@ jobs:
         ### 📊 Technical Details
 
         - **Nodes**: 1 (Resolution Calculator)
-        - **Test Coverage**: 100%
+        - **Python Coverage Gate**: 85% combined statement/branch coverage
         - **Python Support**: 3.8+
         - **ComfyUI Compatibility**: Latest
 
@@ -114,7 +87,7 @@ jobs:
         EOF
 
     - name: Create GitHub Release
-      uses: softprops/action-gh-release@v2
+      uses: softprops/action-gh-release@v3
       with:
         tag_name: ${{ steps.get_version.outputs.version }}
         name: ComfyUI-KikoTools ${{ steps.get_version.outputs.version }}
@@ -147,4 +120,4 @@ jobs:
         echo "- Resolution Calculator tool"
         echo "- Complete documentation"
         echo "- Example workflows"
-        echo "- 100% test coverage"
+        echo "- Enforced Python coverage and frontend regression checks"

.github/workflows/tests.yml

@@ -11,479 +11,191 @@ 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@v5
+      - uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         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
 
-      - 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 --junitxml=test-results/pytest.xml
 
-          # 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 'ComfyAssets' in ComfyAssetsBaseNode.CATEGORY
-          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 'ComfyAssets/' in res_class.CATEGORY
-          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 'ComfyAssets/' in wh_class.CATEGORY
-          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 'ComfyAssets/' in sampler_class.CATEGORY
-          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 'ComfyAssets/' in seed_class.CATEGORY
-          print('✓ Seed History ComfyUI integration passed')
-
-          print('🎉 All tools ComfyUI integration readiness tests passed!')
-          "
-
-  test-package-structure:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v6
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v7
         with:
-          python-version: "3.10"
+          name: python-${{ matrix.os }}-${{ matrix.python-version }}
+          path: test-results/
+          if-no-files-found: ignore
+          retention-days: 14
 
-      - name: Test package structure
+  comfyui:
+    name: real ComfyUI compatibility
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: tools/testing/package-lock.json
+      - name: Read the reviewed runtime pins
+        id: runtime
         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)
+          node --input-type=module <<'JS' >> "$GITHUB_OUTPUT"
+          import runtime from './tools/testing/comfyui-runtime.json' with { type: 'json' };
+          for (const [key, value] of Object.entries(runtime)) console.log(`${key}=${value}`);
+          JS
+      - name: Check out pinned ComfyUI
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ steps.runtime.outputs.repository }}
+          ref: ${{ steps.runtime.outputs.revision }}
+          path: .ci-comfyui
+          persist-credentials: false
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ steps.runtime.outputs.pythonVersion }}
+          cache: pip
+          cache-dependency-path: |
+            requirements-dev.txt
+            .ci-comfyui/requirements.txt
+            tools/testing/comfyui-runtime.json
+      - name: Install CPU runtime and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "torch==${{ steps.runtime.outputs.torchVersion }}" "torchvision==${{ steps.runtime.outputs.torchvisionVersion }}" --index-url https://download.pytorch.org/whl/cpu
+          pip install -r .ci-comfyui/requirements.txt -r requirements-dev.txt "torch==${{ steps.runtime.outputs.torchVersion }}" "torchvision==${{ steps.runtime.outputs.torchvisionVersion }}"
+      - run: npm ci --prefix tools/testing --ignore-scripts
+      - run: npx --prefix tools/testing playwright install --with-deps chromium
+      - name: Classic and Nodes 2.0 startup and compatibility
+        env:
+          KIKO_COMFY_ROOT: ${{ github.workspace }}/.ci-comfyui
+          KIKO_TEST_PYTHON: python
+        run: npm run --prefix tools/testing test:comfyui
+      - name: Upload real-host reports and startup logs
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: real-comfyui-reports
+          path: tools/testing/test-results/
+          if-no-files-found: ignore
+          retention-days: 14
 
-          # 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)
-
-          # 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)
-
-          # Model Downloader files
-          test -f kikotools/tools/model_downloader/node.py || (echo "model_downloader node.py missing" && exit 1)
-          test -f kikotools/tools/model_downloader/base.py || (echo "model_downloader base.py missing" && exit 1)
-          test -f kikotools/tools/model_downloader/detector.py || (echo "model_downloader detector.py missing" && exit 1)
-
-          # Text Input files
-          test -f kikotools/tools/text_input/node.py || (echo "text_input node.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:
+  coverage:
+    name: coverage gate (85%)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
 
-      - name: Test documentation completeness
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
+
+      - name: Install dependencies
         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)
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -r requirements-dev.txt
 
-          # 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)
+      # fail_under = 85 lives in pyproject.toml [tool.coverage.report]
+      - name: Measure coverage
+        run: python -m pytest tests --cov=kikotools --cov-report=term-missing --cov-report=html --cov-report=xml
 
-          echo "✓ Documentation tests passed"
+      - name: Upload coverage reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-coverage
+          path: |
+            htmlcov/
+            coverage.xml
+          if-no-files-found: ignore
+          retention-days: 14
+
+  js-check:
+    name: frontend syntax
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+
+      # Check every shipped module, including files without behavioral tests.
+      - name: Check all shipped JavaScript modules parse
+        run: |
+          shopt -s globstar nullglob
+          for f in web/**/*.js web/**/*.mjs; do
+            node --input-type=module --check < "$f" || { echo "Syntax error in $f"; exit 1; }
+          done
+
+  frontend:
+    name: frontend workflows and coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
+      - name: Install Python test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -r requirements-dev.txt
+      - uses: actions/setup-node@v7
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: tools/testing/package-lock.json
+      - run: npm ci --prefix tools/testing --ignore-scripts
+      - run: npx --prefix tools/testing playwright install --with-deps chromium firefox webkit
+      - name: JavaScript regressions, Chromium workflows, and coverage gate
+        run: npm run --prefix tools/testing test:coverage
+      - name: Firefox and WebKit workflows
+        run: npm run --prefix tools/testing test:browser -- --project firefox --project webkit
+      - name: Upload frontend reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: frontend-test-reports
+          path: |
+            tools/testing/test-results/
+            coverage/js/
+            !coverage/js/raw/
+          if-no-files-found: ignore
+          retention-days: 14

.gitignore

@@ -159,7 +159,22 @@ test_images/
 test_outputs/
 experiments/
 .claude/
+.serena
 
 # Gemini model cache
 .gemini_models_cache.json
 referance/
+
+# Runtime state written inside the package (repo is symlinked into custom_nodes)
+kikotools/tools/local_image_loader/config.json
+kikotools/tools/local_image_loader/selections.json
+gemini_config.json
+
+# Frontend test tooling and reports
+node_modules/
+coverage/
+playwright-report/
+test-results/
+
+# Disposable pinned host checkout used by CI
+.ci-comfyui/

.pre-commit-config.yaml

@@ -4,10 +4,9 @@
 repos:
   # Python code formatting with Black
   - repo: https://github.com/psf/black
-    rev: 25.1.0
+    rev: 26.10.1
     hooks:
       - id: black
-        language_version: python3.10
         args: ['--line-length=88']  # Match CI configuration
 
   # Python linting with flake8
@@ -61,9 +60,27 @@ repos:
         args: ['--baseline', '.secrets.baseline']
         exclude: '^(tests/|\.git/)'
 
+  - repo: local
+    hooks:
+      - id: python-regressions
+        name: Python regression suite
+        entry: python -m pytest tests
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]
+      - id: frontend-regressions
+        name: JavaScript regression suite
+        entry: npm test --prefix tools/testing
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]
+
 # Configuration for specific hooks
+default_stages: [pre-commit]
 default_language_version:
-  python: python3.10
+  python: python3
 
 # Run hooks on all files by default
 fail_fast: false
@@ -81,4 +98,4 @@ exclude: |
     .*\.egg-info/|
     venv/|
     env/
-  )
+  )

AGENTS.md

@@ -0,0 +1,46 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`kikotools/tools/<tool>/logic.py` contains reusable logic; `node.py` defines the
+ComfyUI node. Shared classes live in `kikotools/base/`. Register nodes in
+`kikotools/__init__.py`; the root `__init__.py` exposes the plugin and API routes.
+`web/` contains browser extensions. Tests live in `tests/unit/`, `tests/js/`, and
+`tests/browser/`. Examples are in `examples/`.
+
+## Development Commands
+
+Install Python dependencies with `python -m pip install -r requirements-dev.txt`.
+Run `python -m pytest tests` or `make test` for the complete Python suite.
+Use `python -m pytest tests --cov=kikotools` for the 85% statement/branch gate.
+Format with `black .`; use `flake8 .` for lint findings.
+
+Frontend tooling needs Node.js 24 and `npm ci --prefix tools/testing
+--ignore-scripts`. Run `npm test --prefix tools/testing` for JavaScript tests,
+`npm run --prefix tools/testing test:coverage` for coverage and Chromium workflows,
+and `npm run --prefix tools/testing test:browser` for all browser projects.
+See `TESTING.md` for browser installation, environment overrides, and artifacts.
+
+## Coding Style & Naming
+
+Use four-space Python indentation and Black's 88-character formatting.
+Use `snake_case` for Python functions/modules, `PascalCase` for classes, and
+`UPPER_CASE` for constants. Keep node interfaces separate from logic. Preserve
+existing ComfyUI lifecycle hooks when extending widgets and clean up timers,
+listeners, and observers when nodes are removed.
+
+## Testing Guidelines
+
+Write regression tests first and verify failure before implementing fixes.
+Name Python tests `test_*.py` and JavaScript tests `*.test.mjs`; put browser
+workflows in `tests/browser/*.spec.mjs`. Test behavior and persistence, including
+failure recovery. Keep fixtures disposable and external services mocked.
+Never lower coverage floors to make a change pass.
+
+## Commits & Pull Requests
+
+Use Conventional Commits, such as `fix(local_image_loader): preserve error
+status`. Link the tracked issue, describe observable behavior, and report the
+commands and results used for validation. Include screenshots for visual changes.
+Required checks must pass before merging. Keep credentials and runtime files out
+of commits; restart ComfyUI after installing Python changes.

CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 1.3.0
+
+### Model Resolution Picker
+
+- New `Model Resolution Picker` node (🖼️ Resolution): pick a native size for a
+  model family from a chip grid of aspect ratios and output an empty latent plus
+  width/height. Fourteen shipped families (SD 1.5, SDXL, Illustrious XL, Anima,
+  Flux.1, Z-Image, Qwen-Image, Flux.2 / Klein / MOSS, Qwen-Image 2.1,
+  HunyuanImage 2.1 and four video keyframe rows), each rounded to its VAE step.
+- Native `resolution` dropdown that mirrors the chip grid both ways; typed or
+  wired sizes show `custom`.
+- Shipped family table in `families.json` with a validator, and a user override
+  file at `user/kikotools/model_resolutions.json` that can replace, add or remove
+  families and set the default. Invalid files are ignored whole with a warning
+  in the panel.
+- The node height follows the panel content, and workflows saved before the
+  dropdown existed still load.
+- `GET /kikotools/model_resolution/families` serves the merged table; the shared
+  dimension swap now works on nodes without a preset widget.
+
+## 1.2.0
+
+### Unified ComfyAssets UI
+
+- Consistent blue controls and strong red destructive actions that follow
+  ComfyUI's light/dark theme.
+- Updated Local Image Loader, Save Image viewer, Seed History, Workflow Timer,
+  dimension swaps, Node Dimensions, Display Text/Any and Embedding Autocomplete.
+- Larger adjustable gallery thumbnails and saved-image previews that use the
+  available space; responsive layouts, keyboard controls and lifecycle cleanup.
+- Shared Custom Colors picker with hex entry, HSV sliders and presets.
+- Restored autocomplete tag management, four-column CSV parsing, worker-based
+  imports and persistent tag caching. Tag packs remain a separate download;
+  see [tag-pack provenance and terms](docs/tag-packs/README.md).
+- Follow Execution honors live enablement, avoids duplicate subscriptions and
+  safely groups navigation menus.
+
+### Compatibility and testing
+
+- Classic and Nodes 2.0 coverage includes fresh startup in each renderer,
+  switching both ways, themes, saved workflows and removal cleanup.
+- Required CPU-only real-ComfyUI CI joins the existing Python, JavaScript,
+  Chromium, touch, Firefox and WebKit suites. Runtime pins and failure artifacts
+  make compatibility checks repeatable.
+- Retained [screenshots](docs/screenshots/README.md) and documented
+  [testing commands](TESTING.md).
+
+### Deprecation and upgrade
+
+Gemini Prompt Engineer is deprecated and hidden from normal new-node discovery.
+Its registration, schema and execution remain available for saved workflows;
+ongoing Google API/model compatibility maintenance has ended.
+
+Restart ComfyUI and hard-refresh the browser after upgrading. Existing node
+interfaces, workflow values and setting IDs are retained. No workflow conversion
+is required. Follow Execution remains opt-in through its Enable setting.

CONTRIBUTING.md

@@ -357,9 +357,12 @@ Brief description of changes.
 
 ### Review Process
 
+See [TESTING.md](TESTING.md) for automated suites, coverage gates, required merge
+checks, and the remaining ComfyUI/GPU/service boundaries.
+
 1. **Automated Checks**: CI runs tests and quality checks
 2. **Code Review**: Maintainer reviews code and provides feedback
-3. **Testing**: Manual testing in ComfyUI environment
+3. **Testing**: Run relevant automated suites; use live ComfyUI checks for host, GPU, service, or visual changes
 4. **Merge**: After approval, changes are merged to main
 
 ## 🎨 Code Style Guidelines

Makefile

@@ -1,6 +1,6 @@
 # ComfyUI-KikoTools Development Makefile
 
-.PHONY: help install test test-fast lint format type-check quality-check clean setup dev-test release-test
+.PHONY: coverage frontend-test browser-test frontend-coverage help install test test-fast lint format type-check quality-check clean setup dev-test release-test
 
 # Python and virtual environment setup
 PYTHON := python3
@@ -34,7 +34,11 @@ help:
 	@echo "  quality-check  - Run all quality checks"
 	@echo ""
 	@echo "Testing:"
-	@echo "  test           - Run comprehensive tests"
+	@echo "  test           - Run the complete pytest suite"
+	@echo "  coverage       - Python statement/branch coverage (85% gate)"
+	@echo "  frontend-test  - JavaScript regression tests"
+	@echo "  browser-test   - Extension workflows in four browser configurations"
+	@echo "  frontend-coverage - JavaScript tests, browser tests, and coverage gate"
 	@echo "  test-fast      - Run core functionality tests"
 	@echo "  dev-test       - Quick development test"
 	@echo "  release-test   - Full release validation"
@@ -120,13 +124,20 @@ test-fast: $(VENV_DIR)
 	print('🎉 All core tests passed!'); \
 	"
 
-test: test-fast
-	@echo "Running comprehensive test suite..."
-	@echo "✅ Test case 1: 512×512 → 1024×1024 (scale: 2.0)"
-	@echo "✅ Test case 2: 1024×1024 → 1536×1536 (scale: 1.5)"
-	@echo "✅ Test case 3: 832×1216 → 1272×1864 (scale: 1.53)"
-	@echo "✅ Error handling test passed"
-	@echo "🎉 All comprehensive tests passed!"
+test: $(VENV_DIR)
+	@$(PYTHON_CMD) -m pytest tests
+
+coverage: $(VENV_DIR)
+	@$(PYTHON_CMD) -m pytest tests --cov=kikotools --cov-report=term-missing --cov-report=html
+
+frontend-test:
+	npm test --prefix tools/testing
+
+browser-test:
+	npm run --prefix tools/testing test:browser
+
+frontend-coverage:
+	npm run --prefix tools/testing test:coverage
 
 release-test: quality-check test
 	@echo "Running release validation..."

README.md

@@ -1,7 +1,7 @@
 # ComfyUI-KikoTools
 
 ![License](https://img.shields.io/badge/license-MIT-blue.svg)
-![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)
 ![ComfyUI](https://img.shields.io/badge/ComfyUI-compatible-green.svg)
 ![Tests](https://github.com/ComfyAssets/ComfyUI-KikoTools/workflows/Tests/badge.svg)
 ![Code Quality](https://github.com/ComfyAssets/ComfyUI-KikoTools/workflows/Code%20Quality/badge.svg)
@@ -17,6 +17,27 @@ I tried forking, patching, and submitting merge requests, but eventually decided
 
 I’m sharing them here with the community, and I hope you find them as useful as I do.
 
+## 1.3.0 — Model Resolution Picker
+
+A new node that picks a native resolution for a model family from a chip grid of
+aspect ratios, with a synced `resolution` dropdown, a shipped family table and a
+user override file. See the [release notes](CHANGELOG.md) and the
+[node documentation](examples/documentation/model_resolution_picker.md).
+
+## 1.2.0 — unified ComfyAssets UI
+
+A consistent interface across the KikoTools controls, with ComfyUI-following
+light/dark styling and Classic/Nodes 2.0 support. Existing workflow interfaces
+and settings are retained. See the [release notes](CHANGELOG.md),
+[migration overview](docs/ui-migration.md) and [screenshots](docs/screenshots/).
+
+## ComfyUI Classic and Nodes 2.0
+
+KikoTools supports both ComfyUI Classic and Nodes 2.0. Our shared ComfyAssets
+controls follow ComfyUI's dark/light theme, with automated tests covering renderer
+switching, workflow persistence and cleanup. See the retained
+[UI screenshots](docs/screenshots/) for examples from the migrations.
+
 ## 🚀 Features
 
 ### ✨ Current Tools
@@ -28,9 +49,10 @@ I’m sharing them here with the community, and I hope you find them as useful a
 | [🎲 Seed History](#-seed-history) | Advanced seed tracking with interactive history | 🌱 Seeds |
 | [⚙️ Sampler Combo](#️-sampler-combo) | Unified sampling configuration interface | 🌀 Samplers |
 | [📦 Empty Latent Batch](#-empty-latent-batch) | Create empty latent batches with preset support | 📦 Latents |
+| [🎯 Model Resolution Picker](#-model-resolution-picker) | Pick a model family and size from ratio chips, with latent and width/height outputs | 🖼️ Resolution |
 | [💾 Kiko Save Image](#-kiko-save-image) | Enhanced image saving with popup viewer | 💾 Images |
 | [📋 Display Text](#-display-text) | Smart text display with prompt detection | 👁️ Display |
-| [🤖 Gemini Prompt Engineer](#-gemini-prompt-engineer) | AI-powered image analysis and prompt generation | 🧠 Prompts |
+| [🤖 Gemini Prompt Engineer](#-gemini-prompt-engineer) | Deprecated; retained for existing workflows | 🧠 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 |
 | [📉 Image Scale Down By](#-image-scale-down-by) | Scale images down by a factor with quality preservation | 🖼️ Resolution |
@@ -38,6 +60,9 @@ I’m sharing them here with the community, and I hope you find them as useful a
 | [🔤 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 |
+| [🗂️ Project File Path](#️-project-file-path) | Build safe, organized save prefixes like `MyProject/images/image` | 🛠️ Utils |
 
 ### 🧰 xyz-helpers Tools
 
@@ -47,6 +72,8 @@ Advanced parameter management tools adapted from [comfyui-essentials-nodes](http
 |------|-------------|----------|
 | [🎛️ Flux Sampler Params](#️-flux-sampler-params) | FLUX-optimized parameter generator with batch support | 🧰 xyz-helpers |
 | [📁 LoRA Folder Batch](#-lora-folder-batch) | Batch process multiple LoRAs from folders | 🧰 xyz-helpers |
+| [🔁 Checkpoint Folder Iterator](#-checkpoint-folder-iterator) | Load one checkpoint per queued run from a folder | 🧰 xyz-helpers |
+| [🧩 Model Compare Sheet](#-model-compare-sheet) | Save each run's image and rebuild a labeled contact sheet | 🧰 xyz-helpers |
 | [📊 Plot Parameters](#-plot-parameters) | Visualize parameter effects with graphs | 🧰 xyz-helpers |
 | [🎯 Sampler Select Helper](#-sampler-select-helper) | Intelligent sampler selection with recommendations | 🧰 xyz-helpers |
 | [📅 Scheduler Select Helper](#-scheduler-select-helper) | Optimal scheduler selection for samplers | 🧰 xyz-helpers |
@@ -136,6 +163,25 @@ Advanced empty latent creation with preset support and batch processing capabili
 
 ![Empty Latent Batch Example](examples/workflows/empty_latent_batch_example.png)
 
+#### 🎯 Model Resolution Picker
+Choose a model family and a size from ratio chips, and get an empty latent plus width and height.
+
+- **Model Dropdown**: 14 shipped families (SD 1.5, SDXL, Illustrious XL, Flux.1, Flux.2, Qwen-Image and more) with their preferred sizes
+- **Chips and List**: Pick an aspect ratio chip, then a size from the list under it; the header shows `W × H · ratio · MP`
+- **Resolution Dropdown**: A native `resolution` dropdown (`custom` plus size labels like `1216×832 - 3:2 (1.0MP)`) lists the active chip's sizes and stays in sync with the chips; a listed size wins over width and height when the node runs
+- **Swap W×H**: Exchanges width and height and lands on the mirrored chip
+- **Custom Ratio and Resolution**: Enter a ratio like 16:9 or type width and height; sizes are rounded to the family's step
+- **Your Own Sizes**: An optional override file at `ComfyUI/user/kikotools/model_resolutions.json` (under the default user directory) can replace a family by label, add new ones, hide shipped ones with `remove`, or set `default`; an invalid file is ignored and the panel shows why ([details](examples/documentation/model_resolution_picker.md#user-override-file))
+- **Outputs**: `latent` (4-channel 8x, resizable for 16x and 32x VAEs), `width` and `height`
+- **Keyframe Rows**: Video families (Wan 2.2, LTX-2, HunyuanVideo 1.5, MiniMax H3) are first/last-frame sizes; the latent is an image latent, never fed to a video model
+
+**Use Cases:**
+- Pick the right size for each model without remembering bucket lists
+- Switch families while keeping a listed size
+- Feed one node to both the latent and the size inputs of a workflow
+
+![Model Resolution Picker](docs/screenshots/resolution-picker/ModelResolutionPicker-dark.png)
+
 #### 💾 Kiko Save Image
 Enhanced image saving with format selection, quality control, and floating popup viewer.
 
@@ -171,28 +217,17 @@ Advanced text display node with intelligent formatting and enhanced user interac
 ![Display Text Example](examples/workflows/display_text_example.png)
 
 #### 🤖 Gemini Prompt Engineer
-AI-powered image analysis using Google's Gemini to generate optimized prompts for various models.
 
-- **Multi-Model Support**: Generate prompts for FLUX, SDXL, Danbooru, and Video generation
-- **Smart Analysis**: Gemini analyzes composition, style, lighting, colors, and details
-- **Format-Specific Output**: FLUX artistic prompts, SDXL positive/negative pairs, Danbooru tags, Video motion descriptions
-- **Custom System Prompts**: Override templates with your own analysis instructions
-- **Flexible API Key Management**: Environment variable, config file, or direct input
-- **Visual Status Feedback**: Real-time processing indicators and error states
-- **Help Integration**: Built-in setup guide and documentation
-- **Dynamic Model Refresh**: Fetch latest Gemini models with refresh button
-- **Model Caching**: Persistent model list storage for offline access
-- **Enhanced SDXL Prompts**: Improved formatting with layered structure and quality boosters
+**Deprecated — retained for existing workflows only.** ComfyUI hides this node
+from normal new-node discovery using its deprecated-node metadata. The
+`GeminiPrompt` identifier, inputs, outputs and execution remain available so
+saved workflows can still load.
 
-**Use Cases:**
-- Reverse-engineer prompts from reference images
-- Convert artistic descriptions between different AI model formats
-- Generate consistent style descriptions across workflows
-- Create detailed scene breakdowns for complex compositions
-- Analyze and replicate lighting/mood from existing artwork
-- Access latest Gemini models including 2.0 and 2.5 versions
-
-![Gemini Prompt Example](examples/workflows/gemini_prompt_example.png)
+Google API/model compatibility updates and UI migration have ended. Existing
+workflows still depend on Google's service and the optional `google-genai`
+package; deprecation does not guarantee future API compatibility. See the
+[legacy Gemini documentation](examples/documentation/gemini_prompt.md) for the
+existing configuration and behavior.
 
 #### 🔍 Display Any
 Universal debugging node that displays any type of input value or tensor information.
@@ -298,6 +333,28 @@ Automated batch processing for multiple LoRA models from folders.
 
 ![LoRA Folder Batch Example](examples/workflows/xyz_helpers_lora_testing.png)
 
+#### 🔁 Checkpoint Folder Iterator
+Run the same prompt through every checkpoint in a folder, one model per queued run.
+
+- **folder**: relative to `models/checkpoints`, or an absolute path anywhere on disk; regex include/exclude filters
+- **index** with `control_after_generate`: set 0 + *increment*, then queue a batch count equal to the checkpoint count
+- Queuing past the last checkpoint fails that run with a clear message instead of wrapping around, so the finished sweep is never restarted or archived by accident
+- Outputs MODEL/CLIP/VAE for the indexed file plus `ckpt_name`, `label`, `index`, `count`
+- Only one checkpoint is loaded at a time, so large folders do not exhaust RAM
+
+#### 🧩 Model Compare Sheet
+Output node that pairs with Checkpoint Folder Iterator.
+
+- Saves each run's image(s) to `output/model_compare/<run_name>/<NN>_<label>.png`
+- Rebuilds `grid.png` from every tile saved so far, each labeled with its filename
+- `columns`, `tile_width`, `font_size` control the layout; the grid is also returned as IMAGE
+- The node preview (and anything else that reads it) gets `grid_preview.png`, at most 1024 px wide; `grid.png` keeps full resolution
+- After the last queued run the preview shows the complete sheet
+- Wire Project File Path into `run_name` for `project/date/sweep` folders
+- A run at index 0 moves tiles already in the folder to `<run_name>_<timestamp>`, so an interrupted sweep never leaks into the new grid
+- Rerunning a nonzero index replaces its complete batch, even when the label or batch size changes; other indexes are preserved
+- Replacement PNGs are fully written before existing tiles are changed; a failed tile write preserves the prior tiles and grid
+
 #### 📊 Plot Parameters
 Visual analysis tool for understanding parameter relationships and effects.
 
@@ -378,6 +435,86 @@ Visual gallery browser for loading local images, videos, and audio files directl
 - 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
+
+#### ⏱️ 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
+
+#### 🎨 Custom Colors
+
+Right-click a node and choose **🫶 Custom Colors** to change its full color,
+title or background. The shared picker supports hex entry, HSV sliders and
+presets, and follows ComfyUI's dark/light theme. Changes apply immediately;
+**Done** or **Escape** closes the picker. Multiple selected nodes receive the
+same change. Right-click a group for its color option.
+
+Existing Custom Colors settings control the available menu options and automatic
+title shading. Node and group colors are saved with the workflow.
+
+Screenshots: [Dark](docs/screenshots/custom-colors/dark.png) ·
+[Light](docs/screenshots/custom-colors/light.png).
+
+#### 🧭 Follow Execution
+
+Enable **Follow Execution: Enable** in ComfyUI settings, then right-click the
+canvas to follow/stop execution, show the executing node, or navigate to a node
+by type. **Auto-start** begins following when a workflow starts. Disabling the
+feature stops following immediately; enabling it again waits for a manual start
+or the next workflow start when Auto-start is enabled. The same host menus work
+in Classic and Nodes 2.0. See the [Classic](docs/screenshots/follow-execution/classic.png)
+and [Nodes 2.0](docs/screenshots/follow-execution/nodes2.png) menu screenshots.
+
+#### 🗂️ Project File Path
+Builds an organized save prefix to wire into a save node's `filename_prefix`.
+
+- **Structure**: `root/project_name/[YYYY-MM-DD/]subfolder/filename`, e.g. `MyProject/2026-10-13/images/image`
+- **Date Folder**: Optional toggle inserts today's date after the project; the node re-runs when the date changes
+- **Safe Paths**: Unsafe characters are removed, spaces become underscores, and `..` segments are dropped so paths stay inside the output folder
+- **Nested Folders**: Use `a/b` in `subfolder` for deeper structure
+- **Extensions**: Known file extensions (`.png`, `.mp4`, ...) are stripped from `filename`; `render_v1.5` is left as is
+- **Separator**: `auto`, `forward_slash` or `backslash`
+
+Based on the idea of the Project File Path Generator from djz-nodes.
+
 ### 🔤 Embedding Autocomplete
 
 **Intelligent autocomplete for embeddings, LoRAs, and custom tags in text prompts.**
@@ -392,8 +529,8 @@ This feature is an enhanced fork of the autocomplete functionality from [ComfyUI
 
 **Key Features:**
 - **Smart Triggers**: Type `embedding:` for embeddings, `<lora:` for LoRAs, or just start typing for tags
-- **Custom Word Lists**: Load tag databases (like Danbooru tags) from any URL
-- **Security First**: Comprehensive input validation prevents code injection and XSS attacks
+- **Custom Word Lists**: Import CSV/TXT files or browser-accessible URLs, including [versioned Danbooru tag packs](docs/tag-packs/README.md), with local offline caching
+- **Safe Rendering**: Tag data stays plain text, with validated CSV fields and file-size limits
 - **Flexible Settings**: Customize triggers, auto-insert commas, replace underscores, and more
 - **Performance Optimized**: Handles 100,000+ tags smoothly with frequency-based sorting
 - **Visual Polish**: Clean UI with proper scrolling, keyboard navigation, and type indicators
@@ -407,9 +544,9 @@ This feature is an enhanced fork of the autocomplete functionality from [ComfyUI
 - Load custom word lists from URLs with security validation
 
 **Security Features:**
-- Validates all loaded content to prevent script injection
-- Blocks dangerous patterns (eval, innerHTML, script tags, etc.)
-- Safe character whitelist for tags
+- Validates CSV structure, tag names, categories, counts, and file size
+- Renders tag data as plain text rather than executable HTML or JavaScript
+- Rejects control characters and HTML error documents
 - File size limits to prevent memory exhaustion
 - Clear error messages for rejected content
 
@@ -421,7 +558,7 @@ This feature is an enhanced fork of the autocomplete functionality from [ComfyUI
 **Intelligent GPU memory management with threshold-based triggering and detailed reporting.**
 
 **Key Features:**
-- **4 Purge Modes**: 
+- **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
@@ -478,7 +615,7 @@ Time: 150.0ms
 ### 🔧 Architecture Highlights
 
 - **Modular Design**: Each tool is self-contained and independently testable
-- **Test-Driven Development**: 100% test coverage with comprehensive unit tests
+- **Test-Driven Development**: Regression tests for Python logic, JavaScript extensions, and browser workflows
 - **Clean Interfaces**: Standardized input/output patterns across all tools
 - **Separation of Concerns**: Clear distinction between logic, UI, and integration layers
 - **SOLID Principles**: Extensible architecture following software engineering best practices
@@ -594,6 +731,9 @@ Gemini Prompt → Display Text → Copy to Clipboard
 **Smart Detection:** Automatically formats SDXL-style prompts
 
 ### Gemini Prompt Engineer Example
+
+**Legacy example for the deprecated node; existing workflows only.**
+
 ```
 Load Image → Gemini Prompt → Display Text → Text Generation Model
 🖼️ reference ↘ type: SDXL   ↘ split view  ↘ "detailed portrait..."
@@ -686,19 +826,23 @@ Example workflow available: [xyz_helpers_lora_testing.json](examples/workflows/x
 | **Seed History** | Advanced seed tracking with interactive history management | ✅ Complete | [Docs](examples/documentation/seed_history.md) |
 | **Sampler Combo** | Unified sampling configuration with smart recommendations | ✅ Complete | [Docs](examples/documentation/sampler_combo.md) |
 | **Empty Latent Batch** | Create empty latent batches with preset support | ✅ Complete | [Docs](examples/documentation/empty_latent_batch.md) |
+| **Model Resolution Picker** | Model family size picker with ratio chips, empty latent and width/height outputs | ✅ Complete | [Docs](examples/documentation/model_resolution_picker.md) |
 | **Kiko Save Image** | Enhanced image saving with popup viewer and multi-format support | ✅ Complete | [Docs](examples/documentation/kiko_save_image.md) |
 | **Display Text** | Advanced text display with smart prompt detection and split view | ✅ Complete | [Docs](examples/documentation/display_text.md) |
-| **Gemini Prompt Engineer** | AI-powered image analysis with dynamic model refresh | ✅ Complete | [Docs](examples/documentation/gemini_prompt.md) |
+| **Gemini Prompt Engineer** | Legacy image analysis and prompt generation | Deprecated | [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) |
+| **Image Scale Down By** | Efficiently scale images down by a specified factor | ✅ Complete | [Docs](#-image-scale-down-by) |
+| **Film Grain** | Add realistic analog film grain effects to images | ✅ Complete | [Docs](#-film-grain) |
 | **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](#-model-downloader) |
+| **Workflow Timer** | Real-time execution timer with customizable display | ✅ Complete | [Docs](#️-workflow-timer) |
 | **Batch Image Processor** | Process multiple images with consistent settings | 🚧 Planned | Coming Soon |
 | **Advanced Prompt Utilities** | Enhanced prompt manipulation and generation | 🚧 Planned | Coming Soon |
 
@@ -854,7 +998,7 @@ Example workflow available: [xyz_helpers_lora_testing.json](examples/workflows/x
 
 ### Prerequisites
 
-- Python 3.8+
+- Python 3.10+
 - ComfyUI installation
 - PyTorch 2.0+
 
@@ -939,8 +1083,8 @@ Following **Test-Driven Development (TDD)**:
 # Test structure
 tests/
 ├── unit/                    # Individual component tests
-├── integration/            # ComfyUI workflow tests
-└── fixtures/              # Test data and workflows
+├── js/                      # Extension and coverage-gate regression tests
+└── browser/                 # Browser workflows and disposable host fixtures
 ```
 
 ### Adding New Tools
@@ -981,7 +1125,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
 
@@ -992,20 +1136,28 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ## 📈 Stats
 
-- **Nodes**: 19 (13 core tools + 6 xyz-helpers)
-- **Features**: Embedding Autocomplete (settings-based, not a node)
-- **Categories**: 9 emoji-based categories for better organization
+- **Registered Nodes**: 33, including the deprecated Gemini node
+- **Extensions**: Embedding Autocomplete, Custom Colors and Follow Execution
+- **Organization**: Tools grouped under ComfyAssets
+- **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)
-- **Python Version**: 3.8+
-- **ComfyUI Compatibility**: Latest
-- **Dependencies**: Minimal (PyTorch, NumPy, Pillow, google-generativeai for Gemini)
+- **Legacy AI Integration**: Deprecated Gemini node retained for saved workflows
+- **Test Coverage**: Enforced 85% Python statement/branch coverage and per-file frontend coverage floors
+- **Python Version**: 3.10+
+- **ComfyUI Compatibility**: Classic and Nodes 2.0; tested runtime pins in [TESTING.md](TESTING.md)
+- **Dependencies**: Minimal (PyTorch, NumPy, Pillow, google-genai for Gemini)
 
 ## 🙏 Attribution
 
+### UI inspiration
+
+[Pixaroma's ComfyUI toolkit](https://github.com/pixaroma/ComfyUI-Pixaroma)
+inspired the reusable controls and editor organization. ComfyAssets uses its own
+implementation and styling; no Pixaroma toolkit code or assets are vendored.
+
+
 ### xyz-helpers Tools
 The xyz-helpers collection was adapted from [comfyui-essentials-nodes](https://github.com/cubiq/ComfyUI_essentials) by cubiq. The original project is in maintenance-only mode, and we've adopted these essential tools to ensure continued support and compatibility with modern ComfyUI workflows. We're grateful for cubiq's original work and contributions to the ComfyUI community.
 
@@ -1028,3 +1180,8 @@ All adaptations maintain compatibility while adding new features and optimizatio
 [⭐ Star this repo](https://github.com/ComfyAssets/ComfyUI-KikoTools) • [🐛 Report Bug](https://github.com/ComfyAssets/ComfyUI-KikoTools/issues) • [💡 Request Feature](https://github.com/ComfyAssets/ComfyUI-KikoTools/issues)
 
 </div>
+
+## Automated testing
+
+See [TESTING.md](TESTING.md) for Python and JavaScript tests, cross-browser
+workflows, coverage gates, CI reports, and required merge checks.

TESTING.md

@@ -0,0 +1,166 @@
+# Testing and merge confidence
+
+Use regression tests before fixing a bug. Confirm that the test fails on the
+original implementation, then run the relevant suites after the fix.
+
+## What runs
+
+| Layer | Real components | Replaced boundaries |
+| --- | --- | --- |
+| Python | Tool logic, tensors, image files, API validation | ComfyUI services and external models where needed |
+| JavaScript | Production extension hooks and callback behavior | Minimal host objects; controlled timers for focused regressions |
+| Browser fixtures | All shipped extension imports and lifecycle registration; real plugin startup, HTTP routes, PNG thumbnails, selection persistence, and image loading | ComfyUI graph/widgets/settings/event interfaces and its saved-image serving endpoint |
+| Real ComfyUI | Pinned server/frontend, LiteGraph, native menus, DOM widgets, initial renderers, switching and workflow serialization | Disposable media routes; simulated execution/progress events; model/service boundaries |
+
+Browser workflows cover swaps, local image browsing/selection, pagination,
+sorting, hidden folders, directory autocomplete, saved paths,
+denied paths and network recovery, display output, seed persistence/cleanup, and
+workflow timing, autocomplete insertion, and saved-image previews. They run in Chromium, Firefox, WebKit, and touch Chromium.
+The harness binds to localhost and writes configuration, selections, and fixture
+images only inside a temporary directory. External browser requests fail tests;
+custom-word downloads are disabled in the fixture. No credentials, model
+weights, running ComfyUI, or GPU are required.
+
+## Run locally
+
+Use Python 3.10–3.13 and Node.js 24. Install the CPU PyTorch wheel on Linux if you
+do not need CUDA, then install the development dependencies:
+
+```sh
+python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
+python -m pip install -r requirements-dev.txt
+python -m pytest tests
+python -m pytest tests --cov=kikotools --cov-report=term-missing
+npm ci --prefix tools/testing --ignore-scripts
+npx --prefix tools/testing playwright install --with-deps chromium firefox webkit
+npm test --prefix tools/testing
+npm run --prefix tools/testing test:coverage
+npm run --prefix tools/testing test:browser -- --project firefox --project webkit
+```
+
+`make test` runs the full pytest suite and propagates failures. `make coverage`,
+`make frontend-test`, `make browser-test`, and `make frontend-coverage` provide
+shortcuts. The Python Make targets use the existing virtual-environment setup.
+Install local commit and push hooks with `pre-commit install --hook-type
+pre-commit --hook-type pre-push`. The push hooks run Python and JavaScript
+regressions; CI additionally runs all browser workflows and coverage gates.
+For a quick browser check, use `test:browser -- --project chromium`.
+`KIKO_TEST_PYTHON` selects a Python executable with the development dependencies;
+`KIKO_TEST_PORT` changes the default port 8766. Servers are never reused.
+Unsupported Linux distributions may lack WebKit libraries; Ubuntu CI validates
+all engines.
+
+## Coverage and diagnosis
+
+Python CI checks all twelve Python/OS combinations and enforces 85% combined
+statement/branch coverage. Every production `web/*.js` file appears in frontend
+coverage, including code without behavioral coverage. V8 unit coverage and
+Chromium desktop/touch coverage are merged through c8. The committed per-file
+floors are an honest starting point, not a claim that every feature is tested.
+
+`npm run --prefix tools/testing coverage:update` reruns the suites and raises
+floors with two percentage points of runtime allowance. It cannot lower existing
+floors; new source files require 80% line coverage when added with this command.
+Missing measurements, missing baselines, and per-file regressions fail CI.
+
+CI artifacts include Python JUnit results, Python HTML/XML coverage, and
+`frontend-test-reports` with frontend HTML coverage and browser failure traces
+and screenshots. Open traces using Playwright's `show-trace` command. Local
+frontend coverage is at `coverage/js/index.html`.
+
+The fixture suite covers plugin behavior without a real ComfyUI frontend. The
+separate required real-host job covers the integration described below. GPU/model
+execution, cloud inference and model downloads still need targeted checks when
+changed; the compatibility suite does not queue workflows or download weights.
+Type checking and security jobs retain their existing advisory behavior.
+
+## Pinned real-ComfyUI compatibility
+
+The required **real ComfyUI compatibility** CI job provisions a CPU-only host.
+`tools/testing/comfyui-runtime.json` pins upstream commit
+`e8665ca8e4089ab917567cdb491308e1397663d4` (server 0.39.0), frontend 1.55.14,
+Python 3.12 and the CPU PyTorch/torchvision pair. The launcher rejects a different
+revision or modified tracked upstream files. The suite verifies server/frontend
+versions and attaches them to each test's report.
+
+Two projects, `classic-start` and `nodes2-start`, select the renderer during
+startup, before creating nodes. Both run the complete suite, including live
+renderer switching, zoom/resize, palette changes, workflow save/reload and
+cleanup. Test-local settings start from a blank workspace and skip first-run
+onboarding. They do not change the server's saved preferences.
+
+The migrated controls covered are Local Image Loader, Save Image, Seed History,
+Workflow Timer and its color picker, both dimension swap nodes, Node Dimensions,
+Display Text/Any, Embedding Autocomplete/settings/tag imports, Custom Colors and
+Follow Execution. Native canvas menus are opened with actual right clicks.
+Execution/progress events are simulated; generation is never queued.
+
+### Managed local host
+
+Use a separate clean checkout of the pinned ComfyUI commit and a Python 3.12
+environment containing its `requirements.txt` and this repository's
+`requirements-dev.txt`. Install the CPU torch/torchvision versions from the
+runtime manifest first, using the official CPU wheel index. The CI workflow in
+`.github/workflows/tests.yml` contains the full provisioning recipe.
+
+```sh
+KIKO_COMFY_ROOT=/path/to/pinned/ComfyUI \
+KIKO_TEST_PYTHON=/path/to/cpu-venv/bin/python \
+  npm run --prefix tools/testing test:comfyui
+```
+
+Playwright owns this host on `127.0.0.1:8189` and a fixture server on port 8771.
+The launcher creates a temporary base/user/model directory, installs only a
+symlink to the current KikoTools checkout, disables other custom nodes and
+partner services, and uses an in-memory database. It removes owned state after
+normal shutdown, startup failure or process termination. Existing installations
+and model folders are not used. An occupied port fails instead of reusing an
+unrelated server.
+
+### Existing local host
+
+An opt-in mode still supports an already running host with the same pinned
+versions:
+
+```sh
+KIKO_COMFY_URL=http://127.0.0.1:8188/ \
+  npm run --prefix tools/testing test:comfyui
+```
+
+Only loopback URLs are accepted. A separate browser context serves the current
+checkout's extensions. Media requests use real plugin Python routes with
+disposable fixture data. Other HTTP writes are intercepted, preserving server
+settings, saved workflows and selections. This mode does not start or stop the
+existing server.
+
+### Reports and pin updates
+
+CI retains `real-comfyui-reports` for 14 days, including server startup logs at
+`tools/testing/test-results/comfyui-host.log`, browser traces, screenshots and
+version attachments. Startup logs survive failure. Reviewed captures copied to
+[docs/screenshots](docs/screenshots/README.md) are committed separately from
+throwaway test artifacts.
+
+To update the host, review and change the runtime manifest, provision the new
+checkout/dependencies, and run both startup projects before merging. A version
+assertion update alone is not compatibility validation. Cross-pack installation
+and shared-source version compatibility remain tracked in #81.
+
+## Required merge checks
+
+The manifest in `.github/branch-protection.json` requires all Python matrix jobs,
+Python coverage, frontend syntax, frontend workflows/coverage, real ComfyUI
+compatibility, and the existing
+`code-quality` job (including Black and fatal lint checks). Administrators follow
+the same checks and branches must be current with main. No extra human approval
+is required. Workflows run on every pull request without path filters.
+
+After the checks pass, an administrator applies and verifies the manifest:
+
+```sh
+gh api --method PUT repos/ComfyAssets/ComfyUI-KikoTools/branches/main/protection \
+  --input .github/branch-protection.json
+gh api repos/ComfyAssets/ComfyUI-KikoTools/branches/main/protection/required_status_checks
+```
+
+Keep the manifest synchronized with job names when changing CI.

__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()
 

docs/screenshots/README.md

@@ -0,0 +1,22 @@
+# ComfyAssets UI screenshots
+
+Retained captures from the KikoTools UI migrations. Real-ComfyUI tests cover
+Classic and Nodes 2.0, renderer switching, saved workflows and cleanup.
+
+| Interface | Captures |
+| --- | --- |
+| Local Image Loader | [Classic](live-image-loader/classic.png), [Nodes 2.0](live-image-loader/nodes2.png) |
+| Saved-image viewer | [Dark](save-image-viewer/dark.png), [Light](save-image-viewer/light.png) |
+| Seed History | [Dark](seed-history/dark.png), [Light](seed-history/light.png) |
+| Workflow Timer | [Dark](workflow-timer/dark.png), [Light](workflow-timer/light.png), [Color picker](workflow-timer/color-picker.png) |
+| Dimension swap | [Selector dark](dimension-swap/selector-dark.png), [Selector light](dimension-swap/selector-light.png), [Latent dark](dimension-swap/latent-dark.png), [Latent light](dimension-swap/latent-light.png) |
+| Node Dimensions | [Dark](node-dimensions/dark.png), [Light](node-dimensions/light.png) |
+| Display Text | [Dark](display-output/text-dark.png), [Light](display-output/text-light.png) |
+| Display Any | [Dark](display-output/any-dark.png), [Light](display-output/any-light.png) |
+| Embedding Autocomplete | [Suggestions dark](embedding-autocomplete/suggestions-dark.png), [Suggestions light](embedding-autocomplete/suggestions-light.png), [Settings dark](embedding-autocomplete/settings-dark.png), [Settings light](embedding-autocomplete/settings-light.png) |
+| Custom Colors | [Dark](custom-colors/dark.png), [Light](custom-colors/light.png) |
+| Follow Execution | [Classic](follow-execution/classic.png), [Nodes 2.0](follow-execution/nodes2.png) |
+
+Screenshots record the tested appearance at capture time. Updated Playwright
+captures are temporary test artifacts until copied into this directory and
+committed for review.

docs/superpowers/plans/2026-10-27-model-resolution-picker.md

@@ -0,0 +1,734 @@
+# Model Resolution Picker Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A new ComfyAssets node whose model dropdown drives a ratio-chip grid and size list, outputting width, height and an empty latent, with the toolkit Swap W×H.
+
+**Architecture:** The family table lives in Python (`families.py`) and is served by a GET route; the Python node rounds to the family step and builds the latent with the existing `create_empty_latent_batch`. The frontend is a pure derivation module (`web/ui/resolution-picker.js`), a DOM view (`web/views/resolution-picker.js`) and an extension (`web/model_resolution_picker.js`) that projects the native `model`/`width`/`height` widgets into the panel and writes back through widget callbacks. No panel state is serialized.
+
+**Tech Stack:** Python 3.10–3.13, torch (CPU), aiohttp routes on `PromptServer`; ES modules on the `web/ui` toolkit; pytest, `node --test`, Playwright fixture host (`tests/browser`), pinned real ComfyUI (`tests/comfyui`).
+
+**Spec:** `docs/superpowers/specs/2026-10-27-model-resolution-picker-design.md`
+
+## Global Constraints
+
+- Node id `ModelResolutionPicker`, display name `Model Resolution Picker`, category `🫶 ComfyAssets/🖼️ Resolution`.
+- Combo value is the family **label**; labels are stable ids; each family carries `aliases`; unknown label → step 8, logged warning, no re-rounding to another family's step.
+- Chips, in grid order: `1:1`, `4:5`, `5:4`, `3:4`, `4:3`, `2:3`, `3:2`, `9:16`, `16:9`, `21:9`, `9:21`, then `Custom ratio`. Mirror pairs: 4:5↔5:4, 3:4↔4:3, 2:3↔3:2, 9:16↔16:9, 21:9↔9:21, 1:1↔1:1.
+- Chip tolerance for derived (non-listed) sizes: **7%** relative to the chip ratio. Authored list membership always wins.
+- 1 MP = 1,048,576 px. Custom-ratio sizes use core Resolution Selector math: `scale = sqrt(mp·1048576/(rw·rh))`, each side `round(side/step)·step`, never below 64.
+- Default family `SDXL`, default size 1024×1024, `batch_size` default 1, min 1, max 64. `width`/`height` widgets: default 1024, min 64, max 8192, step 8.
+- Route: `GET /kikotools/model_resolution/families`, registered at module import like `local_image_loader/node.py`, guarded by `try/except ImportError`.
+- Only `createScope()`, `mountTheme()`, `createButton()` and `controls.css` tokens for UI; new CSS classes are prefixed `.ca-resolution-`.
+- Panel DOM widget is added with `serialize: false`; it mounts after the native widgets; new nodes start at 340 × 600.
+- Never vendor Pixaroma code or assets. No external HTTP.
+- Python coverage ≥ 85% overall; every new `web/*.js` file gets a row in `tools/testing/frontend-coverage-baseline.json`.
+- Width Height Selector and Empty Latent Batch tests must keep passing unchanged.
+- Commits: conventional type with scope, imperative subject, bullet body. No AI attribution lines.
+
+## Review Focus
+
+1. Typed width/height below 64 or not on the family step (e.g. 70×1000 on HunyuanImage 2.1): Python emits ≥ 64 on the step, the header shows the same effective size. Pinned in Task 1 (`round_to_step`) and Task 3 (`test_execution_rounds_to_family_step`).
+2. Families route unavailable (network error or 500): panel shows one status line, native widgets and Swap still work, no page error. Pinned in Task 7 (`route failure keeps native widgets usable`).
+3. Workflow saved with a former label or an unknown label: former label resolves through `aliases`; unknown label keeps the saved size (step 8). Pinned in Task 2 (`test_resolve_family_by_alias`) and Task 3 (`test_unknown_label_keeps_size_and_warns`).
+4. `width` and `height` converted to inputs: chips and list disabled, header says "dimensions are wired in", Swap disabled. Pinned in Task 7 (`wired-in dimensions disable the picker`).
+5. Custom ratio text such as `0:5`, `16:`, `a:b`, `99999999:1`: rejected with the inline error, previous list kept. Pinned in Task 5 (`parseRatio rejects malformed input`) and Task 7 (`custom ratio field`).
+
+---
+
+## File structure
+
+| Path | Responsibility |
+|---|---|
+| `kikotools/tools/model_resolution_picker/logic.py` | step rounding, size generation, ratio label |
+| `kikotools/tools/model_resolution_picker/families.py` | `Family` record, `CHIPS`, `MIRROR`, `FAMILIES`, lookup, JSON payload |
+| `kikotools/tools/model_resolution_picker/node.py` | node class, route handler, module-level registration |
+| `kikotools/tools/model_resolution_picker/__init__.py` | exports `ModelResolutionPickerNode` |
+| `kikotools/__init__.py` | registration (modify) |
+| `web/ui/dimensions.js` | swap without a `preset` widget (modify) |
+| `web/ui/resolution-picker.js` | pure derivation and ratio math |
+| `web/views/resolution-picker.js` | DOM view built from toolkit primitives |
+| `web/model_resolution_picker.js` | extension: fetch families, mount view + swap, bind widgets |
+| `web/ui/controls.css` | `.ca-resolution-*` rules (modify) |
+| `tests/unit/tools/model_resolution_picker/` | `test_logic.py`, `test_families.py`, `test_node.py` |
+| `tests/js/resolution-picker.test.mjs`, `tests/js/dimensions.test.mjs` | JS unit tests |
+| `tests/browser/workflows.spec.mjs` | fixture-host workflows (modify) |
+| `tests/comfyui/host-setup.mjs`, `tests/comfyui/resolution-picker.spec.mjs` | real-host coverage |
+| `tools/testing/frontend-coverage-baseline.json` | floors for the 3 new JS files (modify) |
+| `README.md`, `docs/ui-migration.md`, `examples/documentation/model_resolution_picker.md`, `docs/screenshots/resolution-picker/` | docs |
+
+All pytest runs use the scratch venv: `V=/tmp/claude-1000/-home-vito-code-personal-ComfyUI-KikoTools/f79925f2-d12d-4383-ad2e-85d80c922cf7/scratchpad/venv; $V/bin/python -m pytest … -p no:cacheprovider`. Frontend: `npm test --prefix tools/testing`, `npm run --prefix tools/testing test:browser -- --project chromium`.
+
+---
+
+### Task 1: Rounding and size generation (`logic.py`)
+
+**Files:**
+- Create: `kikotools/tools/model_resolution_picker/__init__.py` (empty docstring for now), `kikotools/tools/model_resolution_picker/logic.py`
+- Test: `tests/unit/tools/model_resolution_picker/__init__.py` (empty), `tests/unit/tools/model_resolution_picker/test_logic.py`
+
+**Interfaces:**
+- Produces: `round_to_step(value: int, step: int, minimum: int = 64) -> int`; `generate_size(ratio_w: int, ratio_h: int, megapixels: float, step: int) -> tuple[int, int]`; `ratio_label(width: int, height: int) -> str` (reduced `W:H` with aliases `8:5→16:10`, `5:8→10:16`, `7:3→21:9`, `3:7→9:21`); `MEGAPIXEL = 1_048_576`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+from kikotools.tools.model_resolution_picker.logic import (
+    MEGAPIXEL, generate_size, ratio_label, round_to_step)
+
+def test_round_to_step_rounds_nearest_and_never_below_minimum():
+    assert round_to_step(1000, 32) == 992
+    assert round_to_step(1232, 16) == 1232
+    assert round_to_step(70, 32) == 64
+    assert round_to_step(10, 64) == 64
+    assert round_to_step(1016, 64) == 1024
+
+def test_generate_size_matches_core_resolution_selector():
+    assert generate_size(1, 1, 1.0, 8) == (1024, 1024)
+    assert generate_size(16, 9, 2.0, 16) == (1936, 1088)
+    assert generate_size(3, 2, 4.0, 32) == (2496, 1664)
+    assert generate_size(21, 9, 0.25, 64) == (768, 320)
+
+def test_ratio_label_reduces_and_aliases():
+    assert ratio_label(1024, 1024) == "1:1"
+    assert ratio_label(1216, 832) == "19:13"
+    assert ratio_label(1280, 800) == "16:10"
+    assert ratio_label(1344, 576) == "21:9"
+    assert MEGAPIXEL == 1024 * 1024
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `$V/bin/python -m pytest tests/unit/tools/model_resolution_picker/test_logic.py -p no:cacheprovider -q`
+Expected: FAIL with `ModuleNotFoundError`
+
+- [ ] **Step 3: Implement the three functions in `logic.py`**
+
+`round_to_step`: nearest multiple, then `max(result, ceil(minimum/step)*step)`. `generate_size`: the Global Constraints formula, each side through `round_to_step`. `ratio_label`: `math.gcd`, then the alias dict.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: same command. Expected: `3 passed`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add kikotools/tools/model_resolution_picker/__init__.py kikotools/tools/model_resolution_picker/logic.py tests/unit/tools/model_resolution_picker/
+git commit -m "feat(model_resolution_picker): add step rounding and size generation"
+```
+
+---
+
+### Task 2: The family table (`families.py`)
+
+**Files:**
+- Create: `kikotools/tools/model_resolution_picker/families.py`
+- Test: `tests/unit/tools/model_resolution_picker/test_families.py`
+
+**Interfaces:**
+- Consumes: `generate_size` from Task 1 (used once, by hand, to author the generated lists; not imported by `families.py`).
+- Produces:
+  - `CHIPS: tuple[str, ...]` in the Global Constraints order (11 chips, without `Custom ratio`).
+  - `MIRROR: dict[str, str]`.
+  - `class Family(NamedTuple)`: `label: str`, `aliases: tuple[str, ...]`, `models: str`, `group: str` (`"image"`|`"video"`), `vae_ratio: int`, `step: int`, `megapixels: tuple[float, ...]`, `default: tuple[int, int]`, `sizes: dict[str, tuple[tuple[int, int], ...]]`.
+  - `FAMILIES: tuple[Family, ...]`, `DEFAULT_FAMILY = "SDXL"`.
+  - `family_labels() -> list[str]`, `resolve_family(label: str) -> Family | None` (label or alias), `families_payload() -> dict` with keys `chips`, `mirror`, `default`, `families` (each: `label, aliases, models, group, vaeRatio, step, megapixels, default: [w, h], sizes: {chip: [[w, h], …]}`).
+
+Authored data (copy verbatim; order of `FAMILIES` is this order):
+
+| label | group | vae | step | MP tiers | default | official sizes to list verbatim; everything else generated with `generate_size` at each tier and chip |
+|---|---|---|---|---|---|---|
+| `SD 1.5` | image | 8 | 64 | 0.25, 0.5 | 512×512 | must include 512², 768², 512×768, 768×512 |
+| `SDXL` (models: "SDXL, Pony and other SDXL finetunes") | image | 8 | 64 | 1.0 | 1024×1024 | 1:1 1024²; 4:5 832×1024; 5:4 1024×832; 3:4 896×1152; 4:3 1152×896; 2:3 832×1216; 3:2 1216×832; 9:16 768×1344; 16:9 1344×768; 21:9 1536×640; 9:21 640×1536. No generated entries. |
+| `Illustrious XL` (aliases: none; models: "Illustrious XL v1.0 and later, NoobAI, WAI and other Illustrious finetunes") | image | 8 | 32 | 1.0, 1.5, 2.25 | 1024×1024 | all SDXL entries, plus 1:1 1536²; 4:5 1248×1536; 5:4 1536×1248; 3:4 1344×1792; 4:3 1792×1344; 2:3 1024×1536, 1248×1824; 3:2 1536×1024, 1824×1248; 9:16 1152×2048; 16:9 2048×1152. No generated entries. |
+| `Anima` | image | 8 | 16 | 0.5, 1.0, 1.5 | 1024×1024 | generated; drop any entry with a side < 512 or > 1536 |
+| `Flux.1` (models: "Flux.1 dev / schnell / Krea, Chroma, HiDream I1, SD3.5, Lumina 2") | image | 8 | 16 | 0.5, 1.0, 1.5, 2.0 | 1024×1024 | generated; must include 16:9 1920×1088 and 9:16 1088×1920 (replace the 2.0 MP generated entry) |
+| `Z-Image` (models: "Z-Image Turbo and Z-Image Base") | image | 8 | 16 | 1.0, 1.6 | 1024×1024 | 1:1 1024², 1280²; 4:3 1152×896, 1152×864, 1440×1120, 1472×1104; 3:4 896×1152, 864×1152, 1120×1440, 1104×1472; 3:2 1248×832, 1536×1024; 2:3 832×1248, 1024×1536; 16:9 1280×720, 1600×896; 9:16 720×1280, 896×1600; 21:9 1344×576, 1680×720; 9:21 576×1344, 720×1680. 4:5 and 5:4 empty. |
+| `Qwen-Image` (models: "Qwen-Image and Qwen-Image 2512") | image | 8 | 16 | 1.76 | 1328×1328 | 1:1 1328²; 16:9 1664×928; 9:16 928×1664; 4:3 1472×1104; 3:4 1104×1472; 3:2 1584×1056; 2:3 1056×1584. Other chips empty. |
+| `Flux.2 / Klein / MOSS` (models: "Flux.2 dev, Flux.2 Klein, Flux.3 Klein, MOSS-Image, Ideogram 4") | image | 16 | 16 | 1.0, 2.0, 4.0 | 1024×1024 | generated; must include 3:2 1248×832, 2:3 832×1248, 1:1 2048², 16:9 1920×1088, 9:16 1088×1920 |
+| `Qwen-Image 2.1` (models: "Qwen-Image 2.1 and 2.1 Turbo") | image | 16 | 32 | 1.0, 4.0 | 1024×1024 | 1:1 2048²; 4:3 2400×1792; 3:4 1792×2400; 3:2 2528×1696; 2:3 1696×2528; 16:9 2752×1536; 9:16 1536×2752; plus generated 1.0 MP entries for every chip |
+| `HunyuanImage 2.1` | image | 32 | 32 | 4.0 | 2048×2048 | 1:1 2048²; 16:9 2560×1536; 9:16 1536×2560; 4:3 2304×1792; 3:4 1792×2304; 3:2 2496×1664; 2:3 1664×2496. Other chips empty. |
+| `Wan 2.2 (keyframes)` | video | 16 | 16 | 0.4, 0.9 | 1280×720 | 16:9 832×480, 1280×720, 1280×704; 9:16 480×832, 720×1280, 704×1280; 1:1 640×640, 960×960; other chips generated |
+| `LTX-2 (keyframes)` | video | 32 | 32 | 0.4, 0.9 | 768×512 | 3:2 768×512; 2:3 512×768; 16:9 960×544; 9:16 544×960; other chips generated |
+| `HunyuanVideo 1.5 (keyframes)` | video | 16 | 16 | 0.4, 0.9 | 1280×720 | 16:9 848×480, 1280×720; 9:16 480×848, 720×1280; other chips generated |
+| `MiniMax H3 (keyframes)` | video | 16 | 32 | 0.4, 1.0 | 864×480 | generated |
+
+Every list is sorted by pixel count ascending; mirrored chips hold mirrored entries.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+from kikotools.tools.model_resolution_picker.families import (
+    CHIPS, DEFAULT_FAMILY, FAMILIES, MIRROR, families_payload, family_labels, resolve_family)
+
+CHIP_RATIO = {c: int(c.split(":")[0]) / int(c.split(":")[1]) for c in CHIPS}
+
+def test_chip_order_and_mirrors():
+    assert CHIPS == ("1:1", "4:5", "5:4", "3:4", "4:3", "2:3", "3:2", "9:16", "16:9", "21:9", "9:21")
+    assert all(MIRROR[MIRROR[c]] == c for c in CHIPS)
+
+def test_every_size_is_on_step_and_within_seven_percent_of_its_chip():
+    for family in FAMILIES:
+        for chip, entries in family.sizes.items():
+            for w, h in entries:
+                assert w % family.step == 0 and h % family.step == 0, (family.label, w, h)
+                assert abs(w / h - CHIP_RATIO[chip]) / CHIP_RATIO[chip] <= 0.07, (family.label, chip, w, h)
+
+def test_every_entry_has_its_mirror_and_lists_are_sorted():
+    for family in FAMILIES:
+        for chip, entries in family.sizes.items():
+            assert list(entries) == sorted(entries, key=lambda s: s[0] * s[1])
+            for w, h in entries:
+                assert (h, w) in family.sizes.get(MIRROR[chip], ()), (family.label, chip, w, h)
+
+def test_defaults_labels_and_must_includes():
+    labels = family_labels()
+    assert labels[0] == "SD 1.5" and "SDXL" in labels and DEFAULT_FAMILY == "SDXL"
+    assert len(set(labels)) == len(labels)
+    for family in FAMILIES:
+        assert any(family.default in entries for entries in family.sizes.values()), family.label
+    must = {"SDXL": ("16:9", (1344, 768)), "Flux.1": ("16:9", (1920, 1088)),
+            "Flux.2 / Klein / MOSS": ("3:2", (1248, 832)), "Z-Image": ("21:9", (1680, 720)),
+            "Qwen-Image": ("16:9", (1664, 928)), "Qwen-Image 2.1": ("16:9", (2752, 1536)),
+            "HunyuanImage 2.1": ("16:9", (2560, 1536)), "Illustrious XL": ("2:3", (1248, 1824)),
+            "Wan 2.2 (keyframes)": ("16:9", (1280, 704)), "MiniMax H3 (keyframes)": ("16:9", (864, 480))}
+    for label, (chip, size) in must.items():
+        assert size in resolve_family(label).sizes[chip], label
+
+def test_resolve_family_by_alias_and_unknown():
+    assert resolve_family("SDXL").step == 64
+    assert resolve_family("nope") is None
+
+def test_payload_is_json_shaped():
+    payload = families_payload()
+    assert payload["default"] == "SDXL" and payload["chips"] == list(CHIPS)
+    sdxl = next(f for f in payload["families"] if f["label"] == "SDXL")
+    assert sdxl["sizes"]["3:2"] == [[1216, 832]] and sdxl["vaeRatio"] == 8 and sdxl["group"] == "image"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `$V/bin/python -m pytest tests/unit/tools/model_resolution_picker/test_families.py -p no:cacheprovider -q`
+Expected: FAIL with `ModuleNotFoundError`
+
+- [ ] **Step 3: Author `families.py`**
+
+Produce generated entries with a one-off snippet calling `generate_size` for each chip and tier, apply the "must include" replacements and the Anima range filter, sort, then paste the literals. `families_payload()` converts tuples to lists.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: same command. Expected: `6 passed`
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add kikotools/tools/model_resolution_picker/families.py tests/unit/tools/model_resolution_picker/test_families.py
+git commit -m "feat(model_resolution_picker): add the model family resolution table"
+```
+
+---
+
+### Task 3: Node, route and registration
+
+**Files:**
+- Create: `kikotools/tools/model_resolution_picker/node.py`
+- Modify: `kikotools/tools/model_resolution_picker/__init__.py`, `kikotools/__init__.py` (import + both mapping dicts, next to `EmptyLatentBatch`)
+- Test: `tests/unit/tools/model_resolution_picker/test_node.py`
+
+**Interfaces:**
+- Consumes: `resolve_family`, `family_labels`, `families_payload`, `DEFAULT_FAMILY` (Task 2); `round_to_step` (Task 1); `create_empty_latent_batch(width, height, batch_size)` from `kikotools/tools/empty_latent_batch/logic.py`.
+- Produces: `class ModelResolutionPickerNode(ComfyAssetsBaseNode)` with `INPUT_TYPES` (`model` COMBO of `family_labels()` default `DEFAULT_FAMILY`, tooltip "Model family; the chips list its preferred sizes", `width`, `height`, `batch_size` per Global Constraints), `RETURN_TYPES = ("LATENT", "INT", "INT")`, `RETURN_NAMES = ("latent", "width", "height")`, `FUNCTION = "create"`, `create(self, model, width, height, batch_size) -> tuple[dict, int, int]`; `async def get_families(request) -> web.Response` (JSON of `families_payload()`); module-level registration of `GET /kikotools/model_resolution/families` in a `try: import server … except ImportError: pass` block.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+import asyncio, json, logging
+from kikotools.tools.model_resolution_picker.node import ModelResolutionPickerNode, get_families
+
+def test_inputs_and_outputs():
+    inputs = ModelResolutionPickerNode.INPUT_TYPES()["required"]
+    assert inputs["model"][1]["default"] == "SDXL" and "HunyuanImage 2.1" in inputs["model"][0]
+    width = inputs["width"][1]
+    assert (width["default"], width["min"], width["max"], width["step"]) == (1024, 64, 8192, 8)
+    assert ModelResolutionPickerNode.RETURN_TYPES == ("LATENT", "INT", "INT")
+    assert ModelResolutionPickerNode.CATEGORY == "🫶 ComfyAssets/🖼️ Resolution"
+
+def test_execution_rounds_to_family_step_and_marks_latent():
+    latent, w, h = ModelResolutionPickerNode().create("HunyuanImage 2.1", 70, 1000, 2)
+    assert (w, h) == (64, 992)
+    assert latent["samples"].shape == (2, 4, 124, 8) and latent["downscale_ratio_spacial"] == 8
+
+def test_exact_sizes_pass_through():
+    _, w, h = ModelResolutionPickerNode().create("Flux.2 / Klein / MOSS", 1248, 832, 1)
+    assert (w, h) == (1248, 832)
+
+def test_unknown_label_keeps_size_and_warns(caplog):
+    with caplog.at_level(logging.WARNING):
+        _, w, h = ModelResolutionPickerNode().create("Renamed Family", 1000, 1000, 1)
+    assert (w, h) == (1000, 1000) and "Renamed Family" in caplog.text
+
+def test_families_route_returns_payload():
+    response = asyncio.run(get_families(None))
+    assert response.status == 200 and json.loads(response.text)["default"] == "SDXL"
+
+def test_registered_in_kikotools():
+    from kikotools import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
+    assert NODE_CLASS_MAPPINGS["ModelResolutionPicker"] is ModelResolutionPickerNode
+    assert NODE_DISPLAY_NAME_MAPPINGS["ModelResolutionPicker"] == "Model Resolution Picker"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `$V/bin/python -m pytest tests/unit/tools/model_resolution_picker/test_node.py -p no:cacheprovider -q`
+Expected: FAIL with `ImportError`
+
+- [ ] **Step 3: Implement `node.py`, export it, register it**
+
+`create`: resolve → `step = family.step if family else 8`, warning via `logger.warning` when `None`; round both sides; `log_info` when a value changed; build the latent; return. `get_families` returns `web.json_response(families_payload())`.
+
+- [ ] **Step 4: Run the new tests, then the whole Python suite with coverage**
+
+Run: `$V/bin/python -m pytest tests/unit/tools/model_resolution_picker -p no:cacheprovider -q` → `6 passed`
+Run: `$V/bin/python -m pytest tests -p no:cacheprovider -q --cov=kikotools | tail -3` → all passed, coverage ≥ 85%
+Run: `$V/bin/black --check kikotools tests && $V/bin/flake8 kikotools/tools/model_resolution_picker` → clean
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add kikotools/tools/model_resolution_picker kikotools/__init__.py tests/unit/tools/model_resolution_picker/test_node.py
+git commit -m "feat(model_resolution_picker): add node, families route and registration"
+```
+
+---
+
+### Task 4: Swap without a preset widget (`web/ui/dimensions.js`)
+
+**Files:**
+- Modify: `web/ui/dimensions.js:904-932` (`swapDimensions`)
+- Test: `tests/js/dimensions.test.mjs`
+
+**Interfaces:**
+- Produces: `swapDimensions(node, app)` now swaps when the node has `width` and `height` widgets but no `preset` widget, taking the existing custom path (direct swap, callbacks once each, dirty canvas). Behavior with a `preset` widget is unchanged.
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+test('nodes without a preset widget swap width and height directly', () => {
+    const calls = [];
+    const node = { widgets: [
+        { name: 'width', value: 1344, callback(value) { calls.push(['width', value]); } },
+        { name: 'height', value: 768, callback(value) { calls.push(['height', value]); } },
+    ], graph: { setDirtyCanvas() { calls.push(['dirty']); } } };
+    swapDimensions(node, app);
+    assert.deepEqual(node.widgets.map(widget => widget.value), [768, 1344]);
+    assert.deepEqual(calls, [['width', 768], ['height', 1344], ['dirty']]);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `npm test --prefix tools/testing -- ../../tests/js/dimensions.test.mjs` (or `node --test tests/js/dimensions.test.mjs`)
+Expected: FAIL, values unchanged
+
+- [ ] **Step 3: Change the guard**
+
+`if (!width || !height || swapping.has(node)) return; const custom = !preset || preset.value === 'custom';` and leave every `preset.*` access behind `!custom`.
+
+- [ ] **Step 4: Run the JS unit tests**
+
+Run: `npm test --prefix tools/testing` Expected: all pass, including the existing dimensions tests
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/ui/dimensions.js tests/js/dimensions.test.mjs
+git commit -m "feat(ui): let swapDimensions work on nodes without a preset widget"
+```
+
+---
+
+### Task 5: Derivation module (`web/ui/resolution-picker.js`)
+
+**Files:**
+- Create: `web/ui/resolution-picker.js`
+- Test: `tests/js/resolution-picker.test.mjs`
+
+**Interfaces:**
+- Consumes: the families payload shape from Task 2.
+- Produces (all pure, no DOM):
+  - `parseRatio(text) -> [w, h] | null` — accepts `W:H`, `W/H`, `WxH`, `W×H`, surrounding whitespace; integers 1–10000; else `null`.
+  - `reducedRatio(width, height) -> string` — same rule and aliases as Python `ratio_label`.
+  - `findFamily(payload, label) -> family | null` — label or alias.
+  - `deriveSelection(payload, label, width, height) -> { family, chip, entryIndex, custom, ratioText }` — `chip` is the chip whose list holds `[width, height]`; else nearest chip within 7%; else `null` with `custom: true` and `ratioText` from `reducedRatio`. `entryIndex` is the index in `family.sizes[chip]` or `-1`.
+  - `sizesForRatio(family, [rw, rh]) -> [[w, h], …]` — one per tier, Global Constraints formula, deduped, ascending.
+  - `defaultEntry(family, chip) -> [w, h] | null` — entry of `family.sizes[chip]` with pixel count closest to `family.default`'s.
+  - `effectiveSize(family, width, height) -> [w, h]` — rounded to `family.step` (8 when `family` is null), ≥ 64.
+  - `megapixels(width, height) -> string` — one decimal, e.g. `"1.0"`.
+  - `sizeOnModelChange(payload, newLabel, width, height, chip) -> [w, h]` — keep if listed in the new family; else `defaultEntry(newFamily, chip)` when non-null; else `newFamily.default`.
+
+- [ ] **Step 1: Write the failing tests** (use a fixture payload with `SDXL` (step 64, default 1024², sizes 1:1 1024², 3:2 1216×832, 2:3 832×1216, 16:9 1344×768, 9:16 768×1344) and `HunyuanImage 2.1` (step 32, default 2048², 1:1 2048², 16:9 2560×1536, 9:16 1536×2560), plus `aliases: ['SDXL 1.0']` on SDXL)
+
+```js
+test('parseRatio accepts the documented forms and rejects malformed input', () => {
+    for (const text of ['16:9', ' 16 / 9 ', '16x9', '16×9']) assert.deepEqual(parseRatio(text), [16, 9]);
+    for (const text of ['0:5', '16:', 'a:b', '99999999:1', '', null]) assert.equal(parseRatio(text), null);
+});
+test('deriveSelection prefers authored membership, then the 7% band, then custom', () => {
+    assert.deepEqual(deriveSelection(payload, 'HunyuanImage 2.1', 2560, 1536), { family: payload.families[1], chip: '16:9', entryIndex: 0, custom: false, ratioText: '5:3' });
+    assert.equal(deriveSelection(payload, 'SDXL', 1200, 800).chip, '3:2');           // 1.5 exactly, not listed
+    assert.equal(deriveSelection(payload, 'SDXL', 1200, 800).entryIndex, -1);
+    const custom = deriveSelection(payload, 'SDXL', 1600, 800);          // 2:1 is >7% from every chip
+    assert.deepEqual([custom.chip, custom.custom, custom.ratioText], [null, true, '2:1']);
+    assert.equal(deriveSelection(payload, 'SDXL 1.0', 1024, 1024).chip, '1:1');      // alias
+    assert.equal(deriveSelection(payload, 'nope', 1024, 1024).family, null);
+});
+test('sizesForRatio follows the core formula per tier and effectiveSize rounds to the step', () => {
+    assert.deepEqual(sizesForRatio({ step: 16, megapixels: [1, 2] }, [16, 9]), [[1360, 768], [1936, 1088]]);
+    assert.deepEqual(effectiveSize(payload.families[1], 70, 1000), [64, 992]);
+    assert.deepEqual(effectiveSize(null, 1001, 1001), [1000, 1000]);
+    assert.equal(megapixels(1216, 832), '1.0');
+});
+test('model change keeps listed sizes, else the same chip default, else the family default', () => {
+    assert.deepEqual(sizeOnModelChange(payload, 'HunyuanImage 2.1', 2560, 1536, '16:9'), [2560, 1536]);
+    assert.deepEqual(sizeOnModelChange(payload, 'HunyuanImage 2.1', 1344, 768, '16:9'), [2560, 1536]);
+    assert.deepEqual(sizeOnModelChange(payload, 'HunyuanImage 2.1', 1216, 832, '3:2'), [2048, 2048]);
+    assert.deepEqual(defaultEntry(payload.families[0], '21:9'), null);
+});
+```
+
+- [ ] **Step 2: Run to verify failure** — `node --test tests/js/resolution-picker.test.mjs` → FAIL (module missing)
+
+- [ ] **Step 3: Implement the module** — plain functions; `sizesForRatio` uses `Math.round(side / step) * step` with the 64 floor; nearest-chip selection picks the smallest relative error.
+
+- [ ] **Step 4: Run** — `npm test --prefix tools/testing` → all pass
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/ui/resolution-picker.js tests/js/resolution-picker.test.mjs
+git commit -m "feat(ui): add resolution picker derivation module"
+```
+
+---
+
+### Task 6: View, extension and first browser workflows
+
+**Files:**
+- Create: `web/views/resolution-picker.js`, `web/model_resolution_picker.js`
+- Modify: `web/ui/controls.css` (append `.ca-resolution-*` rules), `tests/browser/workflows.spec.mjs`
+
+**Interfaces:**
+- Consumes: Task 5 functions; `createScope`, `mountTheme`, `createButton` from `web/ui/core.js`; `mountDimensionSwap` from `web/ui/dimension-swap.js`; `swapDimensions` (Task 4); `api.fetchApi` from `../../scripts/api.js`.
+- Produces:
+  - `createResolutionPickerView(scope, actions) -> { element, render(state), setStatus(text, isError) }` in `web/views/resolution-picker.js`. `actions = { selectChip(chip), openCustom(), commitRatio(text), selectSize(w, h) }`. `state = { disabled: boolean, header: string, chips: [{ id, label, active, disabled }], customOpen: boolean, ratioText: string, entries: [{ w, h, active }], error: string | null }`. Markup: `element.className = 'ca-tools ca-resolution-picker'`; header `<p class="ca-resolution-header">`; chips in `<div class="ca-resolution-chips" role="group" aria-label="Aspect ratio">` as `<button type="button" aria-pressed>` with text `1:1` … and a last chip `Custom ratio`; sizes in `<div class="ca-resolution-sizes" role="group" aria-label="Resolution">` as `<button type="button" aria-pressed>` with text `1216 × 832`; custom mode shows `<input aria-label="Custom ratio" placeholder="16:9">` (commit on Enter and on `change`) above the generated sizes; status `<p class="ca-resolution-status" role="status">`.
+  - Extension `comfyassets.ModelResolutionPicker` in `web/model_resolution_picker.js`: `beforeRegisterNodeDef` for `nodeData.name === 'ModelResolutionPicker'`; in `onNodeCreated`: `this.setSize([340, 600])`, create scope, mount view with `this.addDOMWidget('resolution_picker', 'div', view.element, { serialize: false, hideOnZoom: false, getMinHeight: () => 320 })`, `mountTheme`, `this.swapDimensions = () => { swapDimensions(this, app); render(); }`, `this.createSwapButton = () => mountDimensionSwap(this, app)` then call it, wrap the `model`/`width`/`height` widget callbacks to call the original then `render()`, `onRemoved` disposes the scope and preserves the previous hook's return. Families are loaded once per page via a module-level `loadFamilies(api)` promise using `api.fetchApi('/kikotools/model_resolution/families')`; while loading the view renders `disabled: true` with header `Loading sizes…`; on failure header `Sizes unavailable; type width and height` via `setStatus(…, true)` and chips stay disabled. Custom-ratio open flag and pending text live on the node instance (`this.resolutionCustom = { open, text }`), never serialized. Wired-in check: `node.inputs?.some(input => input.widget?.name === name && input.link != null)` for `width` or `height` → `disabled: true`, header `Dimensions are wired in`, and the swap button `disabled`.
+  - Writing a size: set `width.value`/`height.value`, call each widget's `callback(value, app.canvas, node, [0, 0], null)` once, `node.graph?.setDirtyCanvas?.(true, true)`.
+
+- [ ] **Step 1: Write the failing browser tests** (append to `tests/browser/workflows.spec.mjs`; the fixture host creates text inputs for the initial keys and serves the real route because `node.py` registered it on the stubbed `PromptServer`)
+
+```js
+test('resolution picker renders chips from the families route and writes sizes to native widgets', async ({ page, request }) => {
+    await openHost(page);
+    const payload = await (await request.get('/kikotools/model_resolution/families')).json();
+    expect(payload.default).toBe('SDXL');
+    await createNode(page, 'ModelResolutionPicker', { model: 'SDXL', width: 1024, height: 1024, batch_size: 1 });
+    const panel = page.locator('.ca-resolution-picker');
+    await expect(panel.getByRole('button', { name: '1:1', exact: true })).toHaveAttribute('aria-pressed', 'true');
+    await expect(panel.locator('.ca-resolution-header')).toHaveText('1024 × 1024 · 1:1 · 1.0 MP');
+    await panel.getByRole('button', { name: '3:2', exact: true }).click();
+    const node = page.locator('[data-node="ModelResolutionPicker"]');
+    await expect(node.getByLabel('width', { exact: true })).toHaveValue('1216');
+    await expect(node.getByLabel('height', { exact: true })).toHaveValue('832');
+    await expect(panel.getByRole('button', { name: '1216 × 832', exact: true })).toHaveAttribute('aria-pressed', 'true');
+    await expect(panel.getByRole('button', { name: '21:9', exact: true })).toBeEnabled();
+    for (const theme of ['light', 'dark']) {
+        await page.evaluate(theme => document.body.style.setProperty('--bg-color', theme === 'light' ? '#fff' : '#202020'), theme);
+        await expect(panel).toHaveAttribute('data-ca-theme', theme);
+    }
+    expect(await panel.evaluate(element => element.scrollWidth <= element.clientWidth)).toBe(true);
+});
+
+test('resolution picker mounting is idempotent and removal disposes its scope', async ({ page }) => {
+    await openHost(page);
+    const id = await createNode(page, 'ModelResolutionPicker', { model: 'SDXL', width: 1024, height: 1024, batch_size: 1 });
+    await page.evaluate(id => { const node = kikoHost.nodes.get(String(id)); node.createSwapButton(); node.createSwapButton(); }, id);
+    await expect(page.locator('.ca-resolution-picker')).toHaveCount(1);
+    await expect(page.locator('.ca-dimension-swap')).toHaveCount(1);
+    const aborted = await page.evaluate(id => { const node = kikoHost.nodes.get(String(id)); kikoHost.removeNode(id); return node.resolutionScope.signal.aborted; }, id);
+    expect(aborted).toBe(true);
+    await expect(page.locator('.ca-resolution-picker')).toHaveCount(0);
+});
+```
+
+- [ ] **Step 2: Run to verify failure** — `npm run --prefix tools/testing test:browser -- --project chromium -g "resolution picker"` → FAIL (no panel)
+
+- [ ] **Step 3: Implement the view, the CSS and the extension**
+
+CSS: chips grid `grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px`; active chip and active size use `--ca-accent` background with `#fff` text (same as `.ca-primary`); size list is a single column of full-width buttons; header uses `--ca-muted`; everything inherits the `.ca-tools` tokens so light/dark follow `data-ca-theme`. Expose the scope as `node.resolutionScope` for the disposal test.
+
+- [ ] **Step 4: Run the browser suite and the JS unit suite** — `npm run --prefix tools/testing test:browser -- --project chromium` and `npm test --prefix tools/testing` → all pass, no page errors
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/views/resolution-picker.js web/model_resolution_picker.js web/ui/controls.css tests/browser/workflows.spec.mjs
+git commit -m "feat(model_resolution_picker): add the chip grid panel and extension"
+```
+
+---
+
+### Task 7: Swap, model change, custom ratio, wired-in, route failure; coverage floors
+
+**Files:**
+- Modify: `web/model_resolution_picker.js`, `web/views/resolution-picker.js` (only as the tests demand), `tests/browser/workflows.spec.mjs`, `tools/testing/frontend-coverage-baseline.json`
+
+**Interfaces:**
+- Consumes: Task 6 extension and view; `sizeOnModelChange`, `sizesForRatio`, `parseRatio` (Task 5).
+
+- [ ] **Step 1: Write the failing browser tests**
+
+```js
+test('resolution picker swap lands on the mirrored chip and entry', async ({ page }) => {
+    await openHost(page);
+    await createNode(page, 'ModelResolutionPicker', { model: 'SDXL', width: 1344, height: 768, batch_size: 1 });
+    const panel = page.locator('.ca-resolution-picker');
+    await page.locator('.ca-dimension-swap').getByRole('button', { name: 'Swap width and height', exact: true }).click();
+    await expect(panel.getByRole('button', { name: '9:16', exact: true })).toHaveAttribute('aria-pressed', 'true');
+    await expect(panel.getByRole('button', { name: '768 × 1344', exact: true })).toHaveAttribute('aria-pressed', 'true');
+});
+
+test('resolution picker model change keeps listed sizes or falls back to the chip default', async ({ page }) => {
+    await openHost(page);
+    const id = await createNode(page, 'ModelResolutionPicker', { model: 'SDXL', width: 1344, height: 768, batch_size: 1 });
+    const node = page.locator('[data-node="ModelResolutionPicker"]');
+    await node.getByLabel('model', { exact: true }).fill('HunyuanImage 2.1');
+    await node.getByLabel('model', { exact: true }).dispatchEvent('change');
+    await expect(node.getByLabel('width', { exact: true })).toHaveValue('2560');
+    await expect(node.getByLabel('height', { exact: true })).toHaveValue('1536');
+    await expect(page.locator('.ca-resolution-header')).toHaveText('2560 × 1536 · 16:9 · 3.8 MP');
+});
+
+test('resolution picker custom ratio field computes tiers and rejects bad input', async ({ page }) => {
+    await openHost(page);
+    await createNode(page, 'ModelResolutionPicker', { model: 'Flux.1', width: 1024, height: 1024, batch_size: 1 });
+    const panel = page.locator('.ca-resolution-picker');
+    await panel.getByRole('button', { name: 'Custom ratio', exact: true }).click();
+    const field = panel.getByLabel('Custom ratio', { exact: true });
+    await expect(field).toHaveValue('1:1');
+    await field.fill('16:10'); await field.press('Enter');
+    await expect(panel.getByRole('button', { name: '1296 × 816', exact: true })).toBeVisible();   // 1.0 MP, step 16
+    await panel.getByRole('button', { name: '1296 × 816', exact: true }).click();
+    await expect(page.locator('[data-node="ModelResolutionPicker"]').getByLabel('width', { exact: true })).toHaveValue('1296');
+    await field.fill('a:b'); await field.press('Enter');
+    await expect(panel.locator('.ca-resolution-status')).toHaveText(/Enter a ratio like 16:9/);
+    await expect(panel.getByRole('button', { name: '1296 × 816', exact: true })).toBeVisible();
+});
+
+test('wired-in dimensions disable the picker and swap', async ({ page }) => {
+    await openHost(page);
+    const id = await createNode(page, 'ModelResolutionPicker', { model: 'SDXL', width: 1024, height: 1024, batch_size: 1 });
+    await page.evaluate(id => { const node = kikoHost.nodes.get(String(id)); node.inputs.push({ name: 'width', widget: { name: 'width' }, link: 7 }); node.widgets.find(w => w.name === 'width').callback('1024', kikoHost.app.canvas, node, [0, 0], null); }, id);
+    const panel = page.locator('.ca-resolution-picker');
+    await expect(panel.locator('.ca-resolution-header')).toHaveText('Dimensions are wired in');
+    await expect(panel.getByRole('button', { name: '3:2', exact: true })).toBeDisabled();
+    await expect(page.locator('.ca-dimension-swap').getByRole('button')).toBeDisabled();
+});
+
+test('route failure keeps native widgets usable', async ({ page }) => {
+    await page.route('**/kikotools/model_resolution/families', route => route.fulfill({ status: 500, body: 'nope' }));
+    await openHost(page);
+    await createNode(page, 'ModelResolutionPicker', { model: 'SDXL', width: 1024, height: 1024, batch_size: 1 });
+    const panel = page.locator('.ca-resolution-picker');
+    await expect(panel.locator('.ca-resolution-status')).toHaveText('Sizes unavailable; type width and height');
+    await expect(panel.getByRole('button', { name: '1:1', exact: true })).toBeDisabled();
+    await page.locator('.ca-dimension-swap').getByRole('button').click();
+    await expect(page.locator('[data-node="ModelResolutionPicker"]').getByLabel('width', { exact: true })).toHaveValue('1024');
+});
+```
+
+The 500 response must not be counted as a page error: the fixture's `afterEach` collects responses ≥ 500, so this test registers its route before `openHost` and removes the 500 URL from `page.errors` at the end (`page.errors = page.errors.filter(e => !e.includes('families'))`).
+
+- [ ] **Step 2: Run to verify failure** — `npm run --prefix tools/testing test:browser -- --project chromium -g "resolution picker|wired-in|route failure"` → the new tests FAIL
+
+- [ ] **Step 3: Implement the remaining behavior** — model-change handler uses `sizeOnModelChange`; custom field uses `parseRatio` + `sizesForRatio`, error copy `Enter a ratio like 16:9`; the fixture model widget is a text input, so the extension must listen to the widget callback, not to a `<select>`.
+
+- [ ] **Step 4: Add coverage floors and run everything frontend**
+
+Add rows for `model_resolution_picker.js`, `ui/resolution-picker.js`, `views/resolution-picker.js` to `tools/testing/frontend-coverage-baseline.json`, then:
+Run: `npm test --prefix tools/testing && npm run --prefix tools/testing test:browser -- --project chromium && npm run --prefix tools/testing test:coverage`
+Expected: all pass; set each new row to the measured values rounded down to the nearest whole percent (never below 80 for lines/statements).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add web/model_resolution_picker.js web/views/resolution-picker.js tests/browser/workflows.spec.mjs tools/testing/frontend-coverage-baseline.json
+git commit -m "feat(model_resolution_picker): model change, custom ratio, wired-in and failure handling"
+```
+
+---
+
+### Task 8: Real-host coverage (both renderers, workflow round-trip)
+
+**Files:**
+- Create: `tests/comfyui/host-setup.mjs`, `tests/comfyui/resolution-picker.spec.mjs`
+- Modify: `tests/comfyui/image-browser.spec.mjs:1-60` (import the shared `beforeEach` instead of its inline copy)
+
+**Interfaces:**
+- Produces: `installHost(test, expect)` in `host-setup.mjs` that registers exactly the existing `beforeEach` (versions check, fixture reset, route proxying, settings override, extension filter, `app.graph.clear()`), with `/kikotools/model_resolution/` added to the list of prefixes proxied to the fixture server so the route is deterministic.
+
+- [ ] **Step 1: Extract the shared setup and confirm the existing spec still passes**
+
+Run: `KIKO_COMFY_ROOT=… npm run --prefix tools/testing test:comfyui` (or against `KIKO_COMFY_URL`; see `TESTING.md`). Expected: unchanged results for `image-browser.spec.mjs`.
+
+- [ ] **Step 2: Write the failing real-host test** (mirrors the sibling swap test at `image-browser.spec.mjs:61-150`)
+
+```js
+test('resolution picker survives renderers, swap, themes and workflow reload', async ({ page }, testInfo) => {
+    await page.evaluate(async () => { const { app } = await import('/scripts/app.js'); const node = LiteGraph.createNode('ModelResolutionPicker'); app.graph.add(node); app.canvas.centerOnNode(node); });
+    const panel = page.locator('.ca-resolution-picker');
+    await expect(panel.getByRole('button', { name: '1:1', exact: true })).toHaveAttribute('aria-pressed', 'true');
+    await panel.getByRole('button', { name: '16:9', exact: true }).click();
+    for (const renderer of [false, true, false]) {
+        await page.evaluate(async renderer => { const { app } = await import('/scripts/app.js'); await app.ui.settings.setSettingValue('Comfy.VueNodes.Enabled', renderer); }, renderer);
+        await expect.poll(() => page.evaluate(() => LiteGraph.vueNodesMode)).toBe(renderer);
+        await expect(panel).toHaveCount(1);
+        await page.locator('.ca-dimension-swap').getByRole('button', { name: 'Swap width and height', exact: true }).click();
+    }
+    await expect(panel.getByRole('button', { name: '9:16', exact: true })).toHaveAttribute('aria-pressed', 'true');   // three swaps from 16:9
+    for (const theme of ['light', 'dark']) {
+        await page.evaluate(async theme => { const { app } = await import('/scripts/app.js'); await app.ui.settings.setSettingValue('Comfy.ColorPalette', theme); }, theme);
+        await expect(panel).toHaveAttribute('data-ca-theme', theme);
+        await page.screenshot({ path: testInfo.outputPath(`ModelResolutionPicker-${theme}.png`) });
+    }
+    const restored = await page.evaluate(async () => {
+        const { app } = await import('/scripts/app.js');
+        const workflow = app.graph.serialize();
+        const saved = workflow.nodes.find(node => node.type === 'ModelResolutionPicker');
+        if (saved.widgets_values.slice(4).some(value => value !== '' && value != null)) throw new Error('Picker UI leaked into workflow values');
+        await app.loadGraphData(workflow);
+        const node = app.graph._nodes.find(node => node.type === 'ModelResolutionPicker');
+        return { saved: saved.widgets_values.slice(0, 4), restored: node.widgets.filter(w => ['model', 'width', 'height', 'batch_size'].includes(w.name)).map(w => w.value), size: Array.from(node.size), savedSize: Array.from(saved.size) };
+    });
+    expect(restored.restored).toEqual(restored.saved);
+    expect(restored.size).toEqual(restored.savedSize);
+    await expect(panel.getByRole('button', { name: '9:16', exact: true })).toHaveAttribute('aria-pressed', 'true');
+    await page.evaluate(async () => { const { app } = await import('/scripts/app.js'); const node = app.graph._nodes.find(node => node.type === 'ModelResolutionPicker'); window.removedPicker = node; app.graph.remove(node); });
+    await expect(panel).toHaveCount(0);
+    expect(await page.evaluate(() => removedPicker.resolutionScope.signal.aborted)).toBe(true);
+});
+```
+
+- [ ] **Step 3: Run it against the pinned host for both projects** — `npm run --prefix tools/testing test:comfyui` → `classic-start` and `nodes2-start` pass. Fix extension behavior if a renderer differs; do not special-case the test.
+
+- [ ] **Step 4: Copy the two screenshots** from the test output to `docs/screenshots/resolution-picker/ModelResolutionPicker-{light,dark}.png` (used by Task 9).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/comfyui/host-setup.mjs tests/comfyui/resolution-picker.spec.mjs tests/comfyui/image-browser.spec.mjs docs/screenshots/resolution-picker
+git commit -m "test(model_resolution_picker): cover both renderers and workflow round-trip on the pinned host"
+```
+
+---
+
+### Task 9: Documentation
+
+**Files:**
+- Modify: `README.md` (tools table after the `Empty Latent Batch` row at line 44; a `#### 🎯 Model Resolution Picker` section after `#### 📦 Empty Latent Batch`; the status table near line 801), `docs/ui-migration.md` (table row `Model Resolution Picker | views/resolution-picker.js, ui/resolution-picker.js, shared swap | [Picker](screenshots/resolution-picker/)`), `web/ui/README.md` (a short "Model Resolution Picker" section stating: derived state only, in-memory custom-ratio flag, families route, disabled chips for empty lists)
+- Create: `examples/documentation/model_resolution_picker.md` (inputs, outputs, the family table with labels and steps, the keyframe note for video families, the manual GPU check procedure from the spec's "Verification before merge")
+
+- [ ] **Step 1: Write the docs** — copy the family labels and steps from `families.py`; README section bullets: model dropdown; chips and list; Swap; custom ratio and custom resolution rounding; outputs; "video rows are keyframe sizes, the latent is an image latent".
+
+- [ ] **Step 2: Verify links** — `grep -n "resolution-picker\|model_resolution_picker" README.md docs/ui-migration.md web/ui/README.md` shows every referenced path exists (`ls` each).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add README.md docs/ui-migration.md web/ui/README.md examples/documentation/model_resolution_picker.md
+git commit -m "docs(model_resolution_picker): document the node, families and keyframe use"
+```
+
+---
+
+### Task 10: Full verification and manual GPU check
+
+**Files:** none new.
+
+- [ ] **Step 1: Run every suite**
+
+```
+$V/bin/python -m pytest tests -p no:cacheprovider -q --cov=kikotools | tail -3
+$V/bin/black --check . && $V/bin/flake8 kikotools
+npm test --prefix tools/testing && npm run --prefix tools/testing test:coverage
+npm run --prefix tools/testing test:browser
+npm run --prefix tools/testing test:comfyui
+```
+Expected: all green; Python coverage ≥ 85%; frontend floors met; Width Height Selector and Empty Latent Batch tests untouched and passing.
+
+- [ ] **Step 2: Manual generation check on the user's ComfyUI** (spec: "Verification before merge"): one queued image each for `Flux.2 / Klein / MOSS` at 1248×832 and `HunyuanImage 2.1` at 2560×1536 through this node → KSampler → VAE Decode → Save; confirm the saved PNGs are exactly those sizes. Record both results in the PR description. This step needs the user's GPU box; if it cannot run, say so in the PR and mark it as a pre-merge TODO.
+
+- [ ] **Step 3: Hand off** — use `superpowers:finishing-a-development-branch` (push with the explicit refspec, PR against `main`).
+
+---
+
+## Addendum tasks (spec addendum 2026-10-27: JSON table, user override, resolution dropdown)
+
+Global Constraints additions: the shipped file is `kikotools/tools/model_resolution_picker/families.json`; the override is `<user_dir>/kikotools/model_resolutions.json`; dropdown label format `{w}×{h} - {ratio} ({mp:.1f}MP)` with `custom` first; `resolution` COMBO sits between `model` and `width`; `VALIDATE_INPUTS(cls, model, resolution)` returns True; an invalid override is ignored whole, logged, and surfaced as `warnings` in the payload; workflows serialize five native widgets.
+
+### Task 11: Shipped JSON table with a runtime validator
+
+**Files:**
+- Create: `kikotools/tools/model_resolution_picker/families.json`, `kikotools/tools/model_resolution_picker/table.py`
+- Modify: `kikotools/tools/model_resolution_picker/families.py` (becomes a thin loader), `pyproject.toml` (package-data for `*.json` under `kikotools`)
+- Test: `tests/unit/tools/model_resolution_picker/test_table.py`; `test_families.py` keeps passing unchanged
+
+**Interfaces:**
+- Produces in `table.py`: `load_table(path: Path) -> dict` (JSON load; raises `ValueError` with the path on bad JSON); `validate_table(data: dict) -> list[str]` (returns human-readable problems, empty when valid; checks: top-level keys and `version == 1`, chips equal `CHIPS`, mirror consistent, unique labels/aliases across families, every chip key present per family, sizes on step, 7% tolerance, exact mirrors, ascending order, one chip per size, default present in sizes, `group` in {image, video}, `vaeRatio` in {8, 16, 32}, `step` > 0, non-empty `megapixels`); `build_families(data: dict) -> tuple[Family, ...]`.
+- `families.py` keeps exporting `CHIPS`, `MIRROR`, `Family`, `FAMILIES`, `DEFAULT_FAMILY`, `family_labels`, `resolve_family`, `families_payload`, now built from `families.json` at import; a validation failure raises `RuntimeError` listing the problems.
+
+- [ ] **Step 1: Write the failing tests** — `test_validate_table_accepts_the_shipped_file` (loads the shipped path, `validate_table` returns `[]`), `test_validate_table_reports_each_invariant` (parametrized: a copy of the shipped data mutated to break one rule each — off-step size, >7% size, missing mirror, unsorted list, duplicate size under two chips, duplicate label, missing chip key, default not listed, bad vaeRatio — must produce exactly one message naming the family and chip), `test_load_table_bad_json_names_the_path`, `test_families_module_is_built_from_json` (`FAMILIES` labels equal the JSON labels in order).
+- [ ] **Step 2: Run to verify failure** — `$V/bin/python -m pytest tests/unit/tools/model_resolution_picker/test_table.py -p no:cacheprovider -q` → ImportError.
+- [ ] **Step 3: Generate `families.json` from the current `FAMILIES`** with a one-off snippet (`families_payload()` plus `"version": 1`), indent 2, then rewrite `families.py` to load/validate/build; delete the literals; keep the source comments as a `"notes"` string per family (the validator ignores unknown keys).
+- [ ] **Step 4: Run** the new tests, `test_families.py`, the full suite with coverage, black and flake8.
+- [ ] **Step 5: Commit** — `refactor(model_resolution_picker): move the family table to families.json with a validator`.
+
+### Task 12: User override file
+
+**Files:**
+- Create: `kikotools/tools/model_resolution_picker/override.py`
+- Modify: `families.py` (resolution and payload consult the merged table), `node.py` (route payload includes `warnings`)
+- Test: `tests/unit/tools/model_resolution_picker/test_override.py`, `test_node.py`
+
+**Interfaces:**
+- Produces: `override_path() -> Path | None` (uses `folder_paths.get_user_directory()`; `None` when `folder_paths` or the function is unavailable); `merge_override(shipped: dict, override: dict) -> dict` (rules from the spec: replace by label, append new, `remove`, `default`); `current_table() -> tuple[dict, list[str]]` (shipped merged with a valid override, cached by override mtime; returns `(merged_data, warnings)`; an unreadable/invalid override yields the shipped data plus one `"Override ignored: <reason>"` warning and a `logger.warning`).
+- `families.py`: `resolve_family(label)` and `families_payload()` use `current_table()`; `families_payload()["warnings"]` is the warnings list; `FAMILIES` remains the shipped tuple for tests.
+
+- [ ] **Step 1: Write the failing tests** — with `tmp_path` as a fake user directory (patch `folder_paths` in `sys.modules` with `get_user_directory`): override replaces SDXL's `sizes` and `resolve_family("SDXL")` reflects it; a new family `My Model` appears last in `families_payload()["families"]` and resolves; `"remove": ["SD 1.5"]` hides it; invalid JSON → shipped data, `warnings == ["Override ignored: <path>: <json error>"]` and a warning log; an override whose merged result breaks an invariant (e.g. off-step size) → ignored whole with the validator message in the warning; editing the file (newer mtime) is picked up on the next call; no `folder_paths` → no override, no warnings; `get_families` route JSON includes `warnings`.
+- [ ] **Step 2: Run to verify failure.**
+- [ ] **Step 3: Implement** `override.py` and wire `families.py`/`node.py`. `current_table()` caches on `(path, mtime_ns)`.
+- [ ] **Step 4: Run** the picker tests, full suite with coverage, black, flake8.
+- [ ] **Step 5: Commit** — `feat(model_resolution_picker): merge a user override file into the family table`.
+
+### Task 13: Native `resolution` dropdown synced with the panel
+
+**Files:**
+- Modify: `node.py` (input, `VALIDATE_INPUTS`, execution precedence), `logic.py` (`size_label(w, h, ratio_label) -> str`, `parse_size_label(text) -> tuple[int, int] | None`), `web/ui/resolution-picker.js` (`sizeLabel`, `parseSizeLabel`, `dropdownOptions(payload, label, chip) -> string[]`), `web/model_resolution_picker.js` (rebuild options and sync value; dropdown callback writes size), `web/views/resolution-picker.js` (status shows the first payload warning), `tests/js/resolution-picker.test.mjs`, `tests/browser/workflows.spec.mjs`, `tests/comfyui/resolution-picker.spec.mjs` (five native widgets: `slice(5)`, include `resolution` in the round-trip), `tools/testing/frontend-coverage-baseline.json` if floors move
+- Test: `test_node.py`, `test_logic.py`
+
+**Interfaces:**
+- Python: `INPUT_TYPES` adds `resolution` COMBO (`["custom"] + sorted distinct labels across shipped families`, default `custom`, tooltip "Sizes for the selected model and ratio; custom uses width/height") between `model` and `width`; `create(self, model, resolution, width, height, batch_size)`: when `resolution != "custom"` and `parse_size_label` succeeds, those dims replace `width`/`height` before rounding; `VALIDATE_INPUTS(cls, model, resolution) -> bool`.
+- JS: `dropdownOptions` returns `['custom', ...labels]` for the active chip's sizes, or all family sizes when `chip` is null/custom; the extension sets `resolution.options.values` (array) on every render where model or active chip changed, sets `resolution.value` to the current size's label or `custom`, and wraps the `resolution` widget callback: a label value writes the parsed size through `width`/`height` callbacks (re-entrancy guarded), `custom` leaves sizes alone.
+- Fixture host note: the fixture renders `resolution` as a text input; tests set its value and dispatch `change`.
+
+- [ ] **Step 1: Write the failing tests** — Python: `test_resolution_label_overrides_width_height` (`create("SDXL", "1216×832 - 3:2 (1.0MP)", 1024, 1024, 1)` → `(1216, 832)`), `test_custom_uses_width_height`, `test_validate_inputs_accepts_unlisted_resolution`, `size_label(1216, 832, "3:2") == "1216×832 - 3:2 (1.0MP)"`, `parse_size_label("1216×832 - 3:2 (1.0MP)") == (1216, 832)` and `None` for `custom`/garbage. JS unit: `dropdownOptions(payload, 'SDXL', '3:2')` → `['custom', '1216×832 - 3:2 (1.0MP)']`; `dropdownOptions(payload, 'SDXL', null)` lists all five SDXL sizes with ratio labels; `parseSizeLabel` round-trips `sizeLabel`. Browser: creating the node with `resolution: 'custom'` and clicking `3:2` sets the `resolution` input to `1216×832 - 3:2 (1.0MP)`; setting `resolution` to `1344×768 - 16:9 (1.0MP)` and dispatching `change` writes width/height 1344/768 and activates `16:9`; a swap sets `resolution` to the mirrored label; a typed width of 1000 sets it to `custom`; with the families route fulfilled by a payload carrying `warnings: ['Override ignored: test']` the status line shows that text. Real host: the existing spec asserts `widgets_values.slice(5)` is empty and that `resolution` survives reload.
+- [ ] **Step 2: Run to verify failure** (Python, JS unit, chromium focused).
+- [ ] **Step 3: Implement** Python then JS. The option list is set as a plain array on `widget.options.values`; the sibling `dimensions.js` already reads array or function options.
+- [ ] **Step 3b: Ratio shapes on chips** (spec addendum part 4): in `web/views/resolution-picker.js` prepend to each ratio chip a `<span class="ca-resolution-shape" aria-hidden="true">` with inline `width`/`height` computed from the chip ratio (longest side 18 px, shortest at least 6 px, whole pixels), `1:1` square, none on `Custom ratio`; CSS in `controls.css`: `display:inline-block; border:1px solid currentColor; border-radius:2px; margin-inline-end:6px; vertical-align:middle`. Browser assertion in the existing render test: the `16:9` chip's shape is wider than tall and the `9:16` chip's is taller than wide; the chips' accessible names are unchanged.
+- [ ] **Step 4: Run** Python suite with coverage, black/flake8, JS unit, chromium+touch browser suite (`env KIKO_TEST_PYTHON=…`), coverage gate, real host on both projects.
+- [ ] **Step 5: Commit** — `feat(model_resolution_picker): add a resolution dropdown synced with the chip grid`.
+
+### Task 14: Docs and final verification for the addendum
+
+- [ ] Update `README.md` section bullets (dropdown; override file path and rules), `examples/documentation/model_resolution_picker.md` (JSON schema, override example with `remove` and a new family, warning behavior, dropdown precedence), `web/ui/README.md` (dropdown sync rule). Verify links.
+- [ ] Run every suite as in Task 10 Step 1 (Python, black/flake8, JS unit, coverage gate, chromium+touch, real host). WebKit is a known local environment limitation.
+- [ ] Commit — `docs(model_resolution_picker): document the JSON table, override file and resolution dropdown`.

docs/superpowers/specs/2026-10-27-model-resolution-picker-design.md

@@ -0,0 +1,399 @@
+# Model Resolution Picker — design
+
+Date: 2026-10-27. Status: approved 2026-10-27.
+
+## Intent
+
+A new ComfyAssets node that picks an image size the way Pixaroma's
+"Resolution" node does — a grid of aspect-ratio chips with a list of concrete
+sizes under the active chip — but driven by a **model dropdown**. Pick the model
+family first and every chip's size list becomes that family's preferred
+resolutions. The node outputs `width`, `height` and an empty `LATENT`, and has
+the toolkit's Swap W×H button, so one node replaces Width Height Selector plus
+Empty Latent Batch in a workflow.
+
+This is a **new node**. Width Height Selector and Empty Latent Batch stay as
+they are.
+
+Why now: every new model family (Flux.2, Klein, Z-Image, Qwen-Image 2.1,
+MOSS-Image, Anima, HunyuanImage) has its own preferred sizes and its own VAE
+step. The existing preset dropdown is one flat SDXL/FLUX list; keeping it
+current for a dozen families makes a 60-entry combo nobody can scan. The chip
+grid makes the choice two clicks, and the model dropdown keeps the wrong sizes
+out of reach.
+
+## Goals
+
+- Two clicks from "I loaded Illustrious" to a correct size: model, then chip,
+  then (optionally) a different entry in the list.
+- Swap W×H flips the dimensions, moves the highlight to the mirrored chip
+  (16:9 → 9:16) and to the matching entry in that chip's list.
+- Custom Ratio: type any `W:H` and get sizes computed at the family's
+  megapixel tiers, rounded to the family's step.
+- Custom Resolution: type exact width/height; the node rounds to the family's
+  step and shows the effective size before you queue.
+- The empty latent is correct for every listed family, including 16x and 32x
+  VAEs, by carrying the `downscale_ratio_spacial` mark that core
+  `EmptyLatentImage` sets (the fix from commit 297f2b1).
+- Looks and behaves the same in the Classic and Nodes 2.0 frontends, using the
+  existing `web/ui` toolkit.
+
+## Non-goals
+
+- Replacing or changing Width Height Selector or Empty Latent Batch, their
+  presets, JS, or tests.
+- Video-length or frame-count handling. Video families are listed for their
+  **frame size** only: the latent output is an image latent for generating
+  first/last keyframes with an image model at the video model's native size.
+- Per-checkpoint detection. The user picks the family; the node does not
+  inspect the loaded model.
+- Snap/step toggles on the node. The step is a property of the family.
+
+## Anti-goals (would make this a failure even if it works)
+
+- Vendoring or adapting Pixaroma's JS, CSS or assets. `docs/ui-migration.md`
+  records that only the organization was an inspiration; that stays true.
+- Storing UI state anywhere except ComfyUI's native widgets. The DOM panel is
+  a projection of `model`, `width`, `height`; it must never need its own
+  serialized state to reconstruct itself.
+- A size table that is "generated from the formula" for a family that has an
+  official list. Official lists are used verbatim.
+- Breaking the real-host CI (pinned ComfyUI, both renderers).
+
+## How it looks
+
+Top to bottom inside the node:
+
+1. Native `model` combo widget.
+2. The DOM panel (`.ca-tools`):
+   - A header line: effective size, ratio label and megapixels, e.g.
+     `1216 × 832 · 3:2 · 1.0 MP`. "Effective" means after rounding to the
+     family step, so what you see is what Python will emit.
+   - The chip grid: `1:1`, `4:5`, `5:4`, `3:4`, `4:3`, `2:3`, `3:2`, `9:16`,
+     `16:9`, `21:9`, `9:21`, and `Custom ratio`. Three columns. Chips with no
+     sizes for the selected family are disabled, not hidden, so the grid never
+     reflows. The active chip uses the toolkit's primary (blue) style.
+   - Below the grid, the size list for the active chip, one entry highlighted.
+     With `Custom ratio` active, the list is replaced by a `W:H` text field
+     and the computed sizes for that ratio.
+   - The toolkit Swap W×H button.
+3. Native `width`, `height`, `batch_size` widgets. `width`/`height` double as
+   the Custom Resolution fields and as the inputs you convert when wiring
+   dimensions in from another node.
+
+Placement: the panel mounts after the native widgets, which is the toolkit
+convention used by the two sibling nodes and the behavior `addDOMWidget` gives
+for free in both renderers. **My call**; the builder may move the panel
+directly under `model` only if it proves stable in both renderers under the
+real-host tests.
+
+New nodes are 340 px wide. The node height is fitted to the panel content (the
+chip grid plus the active chip's list) after every render, so no empty space is
+left under the list; it grows and shrinks with the list. Saved workflows keep
+their width and are re-fitted on load. **Changed by the owner after testing**: the
+original 340 × 600 default left a large gap under one-entry lists.
+
+## Behavior
+
+### State model
+
+The only persisted state is the four native widgets: `model` (COMBO),
+`width` (INT), `height` (INT), `batch_size` (INT). Everything the panel
+shows is derived:
+
+- **Active chip**: the chip under which the family table lists
+  `width × height` (authored membership always wins; that is how HunyuanImage's
+  2560×1536, a 5:3 size, lives under 16:9). If no list contains it, the
+  nearest chip whose ratio is within 7% of `width / height` (so 1216×832
+  reads as 3:2 and 1536×640 as 21:9). If none, `Custom ratio` is active and
+  the ratio field shows the reduced fraction, with aliases so 8:5 displays as
+  16:10 and 7:3 as 21:9.
+- **Custom-ratio mode flag**: the panel keeps one in-memory, non-serialized
+  flag "custom ratio open" plus the pending text in the field. Clicking the
+  `Custom ratio` chip sets the flag and prefills the field with the current
+  reduced ratio; it does not change `width`/`height`. Committing a ratio and
+  picking a tier size sets `width`/`height` and keeps the custom list open
+  until another chip is clicked. On reload the flag is gone and the pure
+  derivation above decides, which is the intended behavior. This is the only
+  panel-owned state and it is never needed to reconstruct anything.
+- **Highlighted list entry**: the entry equal to `width × height`, else none.
+- **Header**: computed from `width`, `height` and the family step.
+
+Consequence: reload, undo, copy/paste, and converting `width`/`height` to
+inputs all work with zero code, because there is nothing to restore. When
+`width` or `height` is converted to an input, the panel disables the chips
+and list and shows "dimensions are wired in" in the header; the Swap button
+stays enabled only when both are widgets.
+
+### Interactions
+
+- **Chip click**: sets `width`/`height` to that chip's default entry for the
+  family (the entry closest to the family's default megapixels), unless the
+  current size already belongs to that chip's list.
+- **List click**: sets `width`/`height` to that entry.
+- **Custom ratio field**: accepts `W:H` (integers, also `W/H` and `W x H`);
+  on commit, the list shows one size per family megapixel tier, computed with
+  ComfyUI core's Resolution Selector formula (`scale = sqrt(MP·1024² /
+  (w·h))`, each side rounded to the family step). Invalid input keeps the
+  previous list and shows an inline error in the panel's status line.
+- **Swap W×H**: swaps `width`/`height` through the native widgets with
+  callbacks (so converted inputs and other extensions see it), then the panel
+  re-derives. Because every family list is authored with mirrored pairs, the
+  swapped size lands on the mirrored chip with a highlighted entry.
+- **Model change**: if the current size is in the new family's lists, keep it.
+  Otherwise pick, in order: the same chip's default entry in the new family;
+  the family default size. Log nothing; the header reflects the change.
+- **Width/height edited directly**: panel re-derives; the header shows the
+  rounded effective size if the typed value is not on the family step.
+
+Every width/height change goes through the widgets' callbacks exactly once,
+as `ui/dimensions.js` already guarantees for the sibling nodes.
+
+### Python execution
+
+Inputs: `model`, `width`, `height`, `batch_size`.
+Outputs: `LATENT` (`latent`), `INT` (`width`), `INT` (`height`).
+
+1. Resolve the family record. The combo value **is the label**, because a
+   ComfyUI COMBO stores the displayed string in both renderers; labels are
+   therefore short and treated as stable ids (`SDXL`, `Illustrious XL`,
+   `Flux.1`, `Z-Image`, `Qwen-Image`, `Flux.2 / Klein / MOSS`,
+   `Qwen-Image 2.1`, `HunyuanImage 2.1`, `Anima`, `SD 1.5`, and the four
+   video rows suffixed ` (keyframes)`). The model list that a label covers
+   goes in the combo tooltip and the README, not in the label. Each record
+   carries an `aliases` list of former labels so a rename maps forward.
+   An unknown value falls back to a generic 8-pixel step with a logged
+   warning: it never re-rounds a saved size to another family's step.
+2. Round `width`/`height` to the nearest multiple of the family step, never
+   below 64; log at info level when a value changed.
+3. Build the latent with the existing
+   `empty_latent_batch.logic.create_empty_latent_batch` (4 channels, 8x,
+   carries `downscale_ratio_spacial: 8`). ComfyUI's sampler resizes it to the
+   family's real latent ratio because of that mark; for 16x and 32x families
+   the step rounding in step 2 is what keeps that resize exact.
+4. Return `(latent, width, height)` as rounded.
+
+The family table lives in Python
+(`kikotools/tools/model_resolution_picker/families.py`) and is the single
+source of truth. The frontend fetches it once from a GET route
+`/kikotools/model_resolution/families` registered on `PromptServer` (the
+project already registers routes for Local Image Loader) and caches it per
+page. If the fetch fails the panel shows one status line and the native
+widgets remain fully usable. **My call**; the alternative is duplicating the
+table in JS, which is exactly the drift this node exists to avoid.
+
+### Family table schema
+
+```
+id:           stable string used as the combo value, e.g. "sdxl"
+label:        combo text, e.g. "SDXL / Pony"
+vae_ratio:    8 | 16 | 32   (informational; the latent is always built at 8)
+step:         pixel multiple for rounding and custom sizes
+megapixels:   list of tiers for Custom ratio, in 1024² units
+default:      (w, h)
+sizes:        { chip: [(w, h), ...] }   authored, mirrored pairs across chips
+```
+
+The `sizes` lists are **authored literals checked into Python**. For the
+"generated" families they are produced once by a helper script using the
+Resolution Selector formula and then hand-adjusted to include the official
+examples named below (for instance 1920×1088 for Flux 16:9 does not fall out
+of the formula; it is added by hand). The validator never regenerates them.
+The live Custom-ratio list does use the formula, so it may offer a slightly
+different size than the chip list for the same ratio; that is acceptable and
+the header shows the exact size either way.
+
+Python unit tests validate the table: every size is a multiple of `step`,
+every size's ratio is within 7% of its chip, every landscape entry has its
+portrait mirror under the mirrored chip, defaults are present in `sizes`,
+labels and aliases are unique, and every "must include" size named in the
+family table below is present.
+
+## The families (v1)
+
+Sources are listed per row. "Official list" means the sizes are copied; for
+families whose guidance is "any size, multiples of N, within a megapixel
+range", the sizes are generated with the Resolution Selector formula at the
+stated tiers and step, then spot-checked against the official examples
+named. 1 MP = 1,048,576 px.
+
+| id | Label | VAE | Step | Tiers (MP) | Default | Sizes |
+|---|---|---|---|---|---|---|
+| `sd15` | SD 1.5 | 8 | 64 | 0.25, 0.5 | 512×512 | generated; 512-class, plus 768×768 |
+| `sdxl` | SDXL / Pony | 8 | 64 | 1.0 | 1024×1024 | official 1 MP buckets: 1024², 1152×896, 1216×832, 1344×768, 1536×640 and mirrors; 4:5/5:4 as 832×1024 / 1024×832 |
+| `illustrious` | Illustrious XL (v1+) | 8 | 32 | 1.0, 1.5, 2.25 | 1024×1024 | SDXL buckets plus the 1536 class from the v1.0 model card and paper: 1536², 1024×1536, 1248×1824, 1344×1792, 1152×2048 and mirrors |
+| `anima` | Anima | 8 | 16 | 0.5, 1.0, 1.5 | 1024×1024 | generated within the documented 512–1536 range; Wan 2.1 latent format in ComfyUI |
+| `flux1` | Flux.1 dev / schnell / Krea, Chroma, HiDream I1, SD3.5, Lumina 2 | 8 | 16 | 0.5, 1.0, 1.5, 2.0 | 1024×1024 | generated; must include 1920×1088 / 1088×1920 (BFL's 16:9 example) |
+| `zimage` | Z-Image Turbo / Base | 8 | 16 | 1.0, 1.6 | 1024×1024 | official 1024 and 1280 sets (11 sizes each) confirmed by Tongyi on the model's HF discussion #28 |
+| `qwen_image` | Qwen-Image / 2512 | 8 | 16 | 1.76 | 1328×1328 | official training-stage list: 1328², 1664×928, 1472×1104, 1584×1056 and mirrors |
+| `flux2` | Flux.2 dev / Klein, Flux.3 Klein, MOSS-Image, Ideogram 4 | 16 | 16 | 1.0, 2.0, 4.0 | 1024×1024 | generated; must include 1248×832 (Flux.2 template default) and 2048² (4 MP max) |
+| `qwen_image_21` | Qwen-Image 2.1 / Turbo | 16 | 32 | 1.0, 4.0 | 1024×1024 | official 2K presets 2048², 2400×1792, 2528×1696, 2752×1536 and mirrors, plus generated 1 MP set (ComfyUI template default) |
+| `hunyuan_image_21` | HunyuanImage 2.1 | 32 | 32 | 4.0 | 2048×2048 | official: 2048², 2560×1536, 2304×1792 and mirrors; 3:2/2:3 generated at 4 MP. No 1 MP tier: the card says 1K output artifacts |
+
+Families named in one row share a VAE and step; the combo label lists them so
+users find their model. Adding a family later is one Python record plus its
+test row.
+
+### Video families (frame sizes for first/last-frame generation)
+
+These rows exist so a keyframe can be generated at the exact size the video
+model will be run at. The combo groups them under a "Video (keyframes)"
+suffix in the label. The latent output is still an 8x image latent, which is
+what the keyframe image model needs; it is never fed to the video model.
+
+| id | Label | Step | Tiers (MP) | Default | Sizes |
+|---|---|---|---|---|---|
+| `wan22` | Wan 2.2 (keyframes) | 16 | 0.4, 0.9 | 1280×720 | official 480p/720p classes: 832×480, 1280×720, 1280×704 (5B TI2V template), 640×640, 960×960 and mirrors |
+| `ltx2` | LTX-2 (keyframes) | 32 | 0.4, 0.9 | 768×512 | template sizes 768×512, 960×544 (ComfyUI templates), plus generated at 0.9 MP with the 32 step the LTX templates use |
+| `hunyuan_video_15` | HunyuanVideo 1.5 (keyframes) | 16 | 0.4, 0.9 | 1280×720 | generated; 480p and 720p classes |
+| `minimax_h3` | MiniMax H3 (keyframes) | 32 | 0.4, 1.0 | 864×480 | generated at 0.4 MP, step 32, which is what every official H3 template sets on Resolution Selector; 1.0 MP tier covers H3-Base's 768p ceiling |
+
+Video family sizes are validated by the same table tests. They carry no
+frame-count data by design.
+
+Deliberately out of v1: Ming Image, SenseNova U1.5 and other pixel-space
+models (ratio 1, needs its own latent path), HunyuanImage 3.0 (no native
+ComfyUI support), Flux.3 Image (API only).
+
+## Decisions
+
+- Default family on first add: **SDXL** at 1024×1024 (decided 2026-10-27).
+
+Decided 2026-10-27: video families are in, as keyframe sizes (see above).
+Builder-check calls made by the author, 2026-10-27: authored chip membership
+wins over ratio tolerance (7%); combo value is the label with an alias list;
+custom-ratio mode is an in-memory flag; size lists are authored literals;
+manual 16x/32x generation check before merge.
+
+## Verification before merge
+
+The real-host CI never queues a generation, so the latent path is only
+unit-tested. Core `EmptyLatentImage` is the same 4-channel, 8x, marked latent
+this node emits, and the official Anima template already runs that path
+(channel repeat 4 → 16). The two cases to confirm by hand on the user's GPU
+box before merge, each with one queued image: a 16x family (Flux.2 or
+Qwen-Image 2.1) and the 32x family (HunyuanImage 2.1) at a non-square size,
+checking the saved image's dimensions equal the node's outputs. Record the
+result in the PR.
+
+## Constraints
+
+- Node id `ModelResolutionPicker`, display name "Model Resolution Picker",
+  category `🫶 ComfyAssets/🖼️ Resolution`. Registered in
+  `kikotools/__init__.py` like the others.
+- Frontend: `web/model_resolution_picker.js` extension plus a view under
+  `web/views/` built only from `web/ui/core.js` primitives and
+  `controls.css` tokens; styling added to `controls.css` under a new
+  `.ca-resolution-*` family. `createScope()` owns listeners, the fetch
+  signal and theme observers; node removal disposes it and preserves the
+  previous `onRemoved` hook's context and return value, as every migrated
+  node does.
+- Swap reuses `ui/dimension-swap.js` for the button and `ui/dimensions.js`
+  for the swap; the latter gains support for nodes that have `width`/`height`
+  but no `preset` widget (today it returns early).
+- Tests, per `TESTING.md` tiers: Python unit tests for the table validator,
+  rounding and execution (including the latent mark and the unknown-id
+  fallback); JS unit tests for derivation, ratio parsing, custom-ratio
+  generation and model-change selection; browser-fixture workflows for chip
+  → widgets, list → widgets, swap → mirrored chip, model change, custom
+  ratio, wired-in dimensions, theme switch, idempotent mount and disposal;
+  real-host coverage of both renderers and workflow round-trip. Python
+  coverage stays above the 85% gate; new JS files get floors in
+  `tools/testing/frontend-coverage-baseline.json`.
+- README gets a tools-table row and a section with a screenshot under
+  `docs/screenshots/`; `docs/ui-migration.md` gets a row.
+- Version bump to 1.3.0 (new node), in the release PR, not this one.
+- No external requests. The only HTTP call is the local families route.
+
+## Left to the builder
+
+- Exact chip grid markup (`createSegments` vs buttons with
+  `aria-pressed`), keyboard order, and how disabled chips announce
+  themselves.
+- The generated-size algorithm's tie-breaking and the spot-check test list.
+- Whether the families route also serves ETag/caching headers.
+- Node default size fine-tuning and the status line's wording.
+- File split inside `kikotools/tools/model_resolution_picker/` (`node.py`,
+  `logic.py`, `families.py`, `routes.py`).
+
+## Addendum (2026-10-27, after first hands-on test): JSON table, user override, resolution dropdown
+
+Decided with the owner after testing the first build. Three changes, same branch.
+
+### 1. The family table is a shipped JSON file
+
+`kikotools/tools/model_resolution_picker/families.json` replaces the Python
+literals. Its shape is exactly the payload the route already serves:
+
+```json
+{ "version": 1, "chips": [...], "mirror": {...}, "default": "SDXL",
+  "families": [ { "label": "SDXL", "aliases": [], "models": "...", "group": "image",
+                  "vaeRatio": 8, "step": 64, "megapixels": [1.0], "default": [1024, 1024],
+                  "sizes": { "1:1": [[1024, 1024]], "4:5": [[832, 1024]], ... } } ] }
+```
+
+`families.py` loads it at import, validates it with a runtime validator that
+enforces the same invariants the tests enforce today (step multiples, 7% chip
+tolerance, exact mirrors, ascending order, one chip per size, unique labels
+and aliases, default present, every chip key present), and builds the same
+`Family` records. A shipped file that fails validation is a startup error.
+The file is package data (`[tool.setuptools.package-data]`), and the git
+checkout is what ComfyUI loads, so the file simply lives next to the module.
+
+### 2. A user override file
+
+`<ComfyUI user directory>/kikotools/model_resolutions.json` (via
+`folder_paths.get_user_directory()`; when that is unavailable there is no
+override). Same schema as the shipped file; top-level `chips`/`mirror` are
+ignored if present. Merge rules, by `label`:
+
+- same label as a shipped family → the override record **replaces** it whole;
+- new label → appended after the shipped families, in file order;
+- optional `"remove": ["label", ...]` hides shipped families;
+- `default` in the override, if present, becomes the combo default.
+
+The merged table is validated with the same validator. An unreadable or
+invalid override is **ignored entirely** (never partially applied), logged at
+warning level, and reported to the panel: the payload gains
+`"warnings": ["Override ignored: <reason>"]` and the panel shows the first
+warning in its status line. The override is re-read when its mtime changes,
+so edits are picked up on a page reload (or ComfyUI's "Refresh node definitions"), which also refreshes the `model` dropdown, without a restart. The frontend caches the families payload per page.
+The shipped file is never modified by the node.
+
+### 3. A native `resolution` dropdown
+
+A COMBO widget named `resolution` sits between `model` and `width`. It lists
+the sizes that fit the **active ratio chip** for the selected model, plus
+`custom` first; with `Custom ratio` active or no chip matched it lists every
+size for the model. Labels use the old node's format:
+`1216×832 - 3:2 (1.0MP)` (ratio label = the chip the size is listed under,
+else the reduced ratio; megapixels to one decimal, 1 MP = 1024²).
+
+Sync rules (the panel remains a projection of the native widgets):
+
+- Picking from the dropdown writes `width`/`height` through their callbacks,
+  exactly like a size-list click.
+- Any size change (chip list, swap, typed width/height, model change) sets
+  `resolution` to the matching label, or `custom` when the size is not in the
+  active list. The dropdown's option list is rebuilt whenever the model or the
+  active chip changes.
+- Python: when `resolution` is not `custom` and parses as `W×H`, those
+  dimensions win over `width`/`height` (same precedence as the old preset
+  dropdown); then the family-step rounding applies as before. The combo's
+  Python option list is `custom` plus every distinct size label across all
+  shipped families, and `VALIDATE_INPUTS` accepts `resolution` as it does
+  `model`, so override-added sizes and old labels still execute.
+- Workflows now serialize five native widgets; nothing else changes.
+
+Non-goals unchanged. The chip grid, Custom ratio and Swap stay as built.
+
+### 4. Ratio shape on each chip
+
+Each ratio chip shows a small outlined box shaped like its ratio before the
+label (wide for 16:9, tall for 9:16, square for 1:1). It is drawn with the
+toolkit's own markup and tokens: a `<span class="ca-resolution-shape">`
+sized from the ratio (longest side 18 px, shortest side at least 6 px,
+rounded to whole pixels), `border: 1px solid currentColor`, with the active
+chip's white text colour showing through. Purely decorative: `aria-hidden`,
+no effect on the accessible name, hidden on `Custom ratio`. No Pixaroma
+code or assets.

docs/tag-packs/README.md

@@ -0,0 +1,48 @@
+# Autocomplete tag packs
+
+ComfyAssets prepares filtered autocomplete data from Danbooru's public
+`tags.json` and `tag_aliases.json` APIs. Dataset releases are versioned separately
+from KikoTools and stored as release assets, keeping bulk data out of Git history.
+
+## Danbooru — Illustrious / NoobAI, 2026-10-16
+
+[Download the CSV and manifest](https://github.com/ComfyAssets/ComfyUI-KikoTools/releases/tag/tags-2026-10-16).
+This snapshot contains 165,158 canonical tags, their categories, post counts, and
+aliases. The adjacent manifest records the retrieval date, model targets,
+selection filters, schema, byte size, and SHA-256 checksum.
+
+The UTF-8 CSV has no header. Columns are `tag,category,post_count,aliases`.
+Aliases share a comma-separated field; use a CSV parser that respects quoting.
+An empty alias field means no aliases. Category codes are 0 (general), 1
+(artist), 3 (copyright), 4 (character), and 5 (meta).
+
+In ComfyUI Settings, search **Embedding Autocomplete**, open its settings,
+then download the pack and choose the CSV under **Tag list file**. Enable
+**Show Custom Words** and select **Save Settings**. Importing stages the list;
+Cancel leaves the active list unchanged. The browser caches the saved file in
+IndexedDB for offline use and restores it after a refresh. Clearing browser site
+data removes this cache. There is no server-side autocomplete folder to populate.
+
+Alternatively, enter a CSV/TXT URL and select **Load URL**, then save. Remote
+servers must allow browser cross-origin requests; for GitHub release assets,
+download and import the file locally. Existing one-column word lists and
+`tag,frequency` lists remain supported. The default URL is unchanged.
+
+Parsing runs in a Web Worker with a 32 MB UTF-8 limit. Search checks canonical
+names and aliases, inserts the canonical tag, and ranks exact matches ahead of
+prefixes and substrings, then by descending post count. The number of displayed
+results is bounded by Maximum suggestions. Categories are retained in records;
+category-specific controls are not currently exposed.
+
+## Source and terms
+
+Source data: [Danbooru](https://danbooru.donmai.us/), collected 2026-10-16.
+Selection and packaging: ComfyAssets. This is an independent filtered snapshot,
+not an official Danbooru release or a guarantee of model compatibility.
+
+Refer to [Danbooru's Terms of Service](https://danbooru.donmai.us/terms) and the
+[official terms template](https://github.com/danbooru/danbooru/blob/master/app/views/static/terms_of_service.html.erb).
+The template's Copyright Infringement section identifies tags as factual
+information that is generally not copyrightable. Its API Usage section requires
+compliance with API rate limits. This reference does not claim an explicit
+dataset license or extend KikoTools' software license to upstream data.

docs/tag-packs/danbooru-illustrious-noobai-2026-10-16.manifest.json

@@ -0,0 +1,35 @@
+{
+  "source": "danbooru.donmai.us tags.json + tag_aliases.json",
+  "pulled": "2026-10-16",
+  "target_models": "Illustrious 1.0-3.x, NoobAI-XL",
+  "filters": {
+    "created_before": "2025-01-01",
+    "min_post_count": {
+      "general": 50,
+      "artist": 30,
+      "copyright": 20,
+      "character": 20
+    },
+    "artists_kept": true,
+    "deprecated_removed": true,
+    "meta_tags": "removed except small allowlist"
+  },
+  "tag_count": 165158,
+  "schema_version": 1,
+  "file": "danbooru-illustrious-noobai-2026-10-16.csv",
+  "encoding": "UTF-8",
+  "header_row": false,
+  "columns": [
+    "tag",
+    "category",
+    "post_count",
+    "aliases"
+  ],
+  "aliases_format": "Comma-separated inside a CSV-quoted field when necessary",
+  "size_bytes": 3979593,
+  "sha256": "733531a60f2e2d38925f53381b18cff21513ef14550d1f2ca670a0f55b86b798",
+  "prepared_by": "ComfyAssets",
+  "terms_url": "https://danbooru.donmai.us/terms",
+  "terms_source_url": "https://github.com/danbooru/danbooru/blob/master/app/views/static/terms_of_service.html.erb",
+  "release_tag": "tags-2026-10-16"
+}

docs/ui-migration.md

@@ -0,0 +1,45 @@
+# KikoTools UI migration
+
+KikoTools' custom controls use the original ComfyAssets foundation in `web/ui/`.
+They share blue primary actions, red destructive actions, keyboard controls and
+ComfyUI-following dark/light colors. Layouts resize with the available space.
+Pixaroma's toolkit inspired the organization; its code/assets are not vendored.
+
+| Interface | Shared implementation | Retained examples |
+| --- | --- | --- |
+| Local Image Loader | `views/image-browser.js`, controls and scoped controller | [Loader](screenshots/live-image-loader/) |
+| Save Image | Floating window, batch selection and responsive preview | [Viewer](screenshots/save-image-viewer/) |
+| Seed History | `views/seed-history.js`, scoped watcher and disclosure | [History](screenshots/seed-history/) |
+| Workflow Timer | Shared clock, controls and color picker | [Timer](screenshots/workflow-timer/) |
+| Width Height / Empty Latent swaps | `ui/dimension-swap.js`, `ui/dimensions.js` | [Swaps](screenshots/dimension-swap/) |
+| Model Resolution Picker | `views/resolution-picker.js`, `ui/resolution-picker.js`, shared swap | [Picker](screenshots/resolution-picker/) |
+| Node Dimensions | `views/node-dimensions.js`, native dialog shell | [Dimensions](screenshots/node-dimensions/) |
+| Display Text / Any | Shared output view, controller and widget adapter | [Output](screenshots/display-output/) |
+| Embedding Autocomplete | Shared suggestions/settings, worker parsing and cache | [Autocomplete](screenshots/embedding-autocomplete/) |
+| Custom Colors | Shared color picker, native node/group menus | [Colors](screenshots/custom-colors/) |
+| Follow Execution | Native host menus/settings, idempotent execution listeners | [Menus](screenshots/follow-execution/) |
+
+`createScope()` owns listeners, observers and delayed work. Node removal preserves
+previous lifecycle hooks while disposing owned resources. Host-specific text
+widget handling lives in `ui/text-widget-adapter.js`; floating windows and native
+dialogs manage their own focus and cleanup. See [module notes](../web/ui/README.md).
+
+Pure Python nodes continue using ComfyUI's native widgets. Gemini Prompt
+Engineer retains its legacy UI for saved workflows under the agreed deprecation;
+its UI migration was cancelled.
+
+The [test guide](../TESTING.md) distinguishes fixture coverage, real-host
+compatibility and model/GPU behavior. Required real-host CI uses a reviewed
+upstream commit, fresh Classic/Nodes 2.0 starts and disposable CPU-only state.
+
+## Remaining shared-toolset work
+
+Before PromptManager adopts the foundation, extract a versioned shared source
+package with reproducible browser artifacts. Then test both node packs alone and
+together, including different bundled foundation versions, isolated settings
+and identical styling. These requirements remain open in issue #81; the KikoTools
+migration does not establish cross-pack compatibility by itself.
+
+The approved design-preview draft [#82](https://github.com/ComfyAssets/ComfyUI-KikoTools/pull/82)
+records the original direction. This inventory describes the shipped interfaces
+and supersedes that draft's implementation sequence.

examples/documentation/batch_prompts.md

@@ -103,4 +103,4 @@ The node provides several ways to track progress:
 ### 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
+- 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

@@ -1,4 +1,15 @@
-# Gemini Prompt Engineer
+# Gemini Prompt Engineer (Deprecated)
+
+**Legacy documentation for existing workflows.** This node is soft-deprecated
+and hidden from normal new-node discovery through ComfyUI's deprecated-node
+metadata. Users who enable deprecated-node visibility may still find it.
+
+The `GeminiPrompt` registration, display name, input/output schema and execution
+remain available for saved workflows. Existing configuration and model-refresh
+behavior remain in place. Google API/model compatibility updates and UI migration
+have ended; the historical model and setup details below may no longer match
+Google's current service. No replacement or automatic workflow conversion is
+provided.
 
 The Gemini Prompt Engineer node uses Google's Gemini AI to analyze images and generate optimized prompts for various AI image generation models.
 
@@ -21,7 +32,7 @@ Get your free Gemini API key from [Google AI Studio](https://makersuite.google.c
 ### 2. Install Dependencies
 
 ```bash
-pip install google-generativeai
+pip install google-genai
 ```
 
 ### 3. Configure API Key
@@ -204,6 +215,6 @@ Errors are displayed in the prompt output for easy debugging.
 - Verify API key is valid
 - Image might be too large (resize if needed)
 
-**Import error for google-generativeai**:
-- Run `pip install google-generativeai` in your ComfyUI environment
-- Restart ComfyUI after installation
+**Import error for google-genai**:
+- Run `pip install google-genai` in your ComfyUI environment
+- 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

@@ -155,4 +155,4 @@ The node creates a visual widget that runs in the ComfyUI interface and communic
 - Save user preferences
 - Handle file selection
 
-All file operations are performed server-side for security, with proper path validation to prevent directory traversal attacks.
+All file operations are performed server-side for security, with proper path validation to prevent directory traversal attacks.

examples/documentation/lora_folder_batch.md

@@ -261,4 +261,4 @@ batch_mode: sequential
 - **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/model_resolution_picker.md

@@ -0,0 +1,190 @@
+# Model Resolution Picker Documentation
+
+## Overview
+
+The Model Resolution Picker is a ComfyUI node that picks a model family and a size for it, then outputs an empty latent plus the width and height. A chip grid of aspect ratios and a size list under the active chip replace hunting through a long preset dropdown. The sizes come from each family's official lists or from megapixel tiers rounded to the family's grid step.
+
+![Model Resolution Picker](../../docs/screenshots/resolution-picker/ModelResolutionPicker-dark.png)
+
+A light-theme capture is at `docs/screenshots/resolution-picker/ModelResolutionPicker-light.png`.
+
+## Node Interface
+
+- **Node id**: `ModelResolutionPicker`
+- **Display name**: Model Resolution Picker
+- **Category**: `🫶 ComfyAssets/🖼️ Resolution`
+
+### Inputs
+- **model**: Dropdown of the 14 shipped family labels (default `SDXL`)
+- **resolution**: Dropdown of `custom` plus size labels such as `1216×832 - 3:2 (1.0MP)` (default `custom`); see [Resolution dropdown](#resolution-dropdown)
+- **width**: Width in pixels (64-8192, step 8)
+- **height**: Height in pixels (64-8192, step 8)
+- **batch_size**: Number of empty latents (1-64)
+
+### Outputs
+- **latent**: Empty latent batch at the rounded size
+- **width**: Rounded width (INT)
+- **height**: Rounded height (INT)
+
+A `resolution` label other than `custom` that parses as `W×H` takes precedence over width and height; `custom` or an unparseable label uses width and height. Width and height are rounded to the selected family's step at execution and never go below 64. An unknown family label (for example from an old workflow) falls back to step 8 and logs a warning.
+
+The latent is the shared 4-channel 8x empty latent. It carries `downscale_ratio_spacial: 8`, which lets ComfyUI resize it for 16x and 32x VAEs, so the same output works with every family below.
+
+The frontend reads the family table from `GET /kikotools/model_resolution/families`. The response carries the table, plus a `warnings` list that is empty unless an override file was ignored.
+
+## Model Families
+
+| Label | Models covered | VAE ratio | Step | Megapixel tiers | Default size | Group |
+|---|---|---|---|---|---|---|
+| SD 1.5 | SD 1.5 and SD 1.5 finetunes | 8x | 64 | 0.25, 0.5 | 512×512 | image |
+| SDXL | SDXL, Pony and other SDXL finetunes | 8x | 64 | 1.0 | 1024×1024 | image |
+| Illustrious XL | Illustrious XL v1.0 and later, NoobAI, WAI and other Illustrious finetunes | 8x | 32 | 1.0, 1.5, 2.25 | 1024×1024 | image |
+| Anima | Anima | 8x | 16 | 0.5, 1.0, 1.5 | 1024×1024 | image |
+| Flux.1 | Flux.1 dev / schnell / Krea, Chroma, HiDream I1, SD3.5, Lumina 2 | 8x | 16 | 0.5, 1.0, 1.5, 2.0 | 1024×1024 | image |
+| Z-Image | Z-Image Turbo and Z-Image Base | 8x | 16 | 1.0, 1.6 | 1024×1024 | image |
+| Qwen-Image | Qwen-Image and Qwen-Image 2512 | 8x | 16 | 1.76 | 1328×1328 | image |
+| Flux.2 / Klein / MOSS | Flux.2 dev, Flux.2 Klein, Flux.3 Klein, MOSS-Image, Ideogram 4 | 16x | 16 | 1.0, 2.0, 4.0 | 1024×1024 | image |
+| Qwen-Image 2.1 | Qwen-Image 2.1 and 2.1 Turbo | 16x | 32 | 1.0, 4.0 | 1024×1024 | image |
+| HunyuanImage 2.1 | HunyuanImage 2.1 | 32x | 32 | 4.0 | 2048×2048 | image |
+| Wan 2.2 (keyframes) | Wan 2.2 (first/last-frame sizes) | 16x | 16 | 0.4, 0.9 | 1280×720 | video |
+| LTX-2 (keyframes) | LTX-2 (first/last-frame sizes) | 32x | 32 | 0.4, 0.9 | 768×512 | video |
+| HunyuanVideo 1.5 (keyframes) | HunyuanVideo 1.5 (first/last-frame sizes) | 16x | 16 | 0.4, 0.9 | 1280×720 | video |
+| MiniMax H3 (keyframes) | MiniMax H3 (first/last-frame sizes) | 16x | 32 | 0.4, 1.0 | 864×480 | video |
+
+The family steps and megapixel tiers are the grid the node rounds to and the tiers custom ratios use. Video families are suffixed `(keyframes)`; see the keyframe note below.
+
+## Family Table File
+
+The families live in `kikotools/tools/model_resolution_picker/families.json`, loaded and checked by `table.py` when ComfyUI starts. A shipped file that fails the check is a startup error. Top-level keys:
+
+- `version`: must be `1`
+- `chips`: exactly the 11 chips listed above, in that order
+- `mirror`: pairs every chip with its mirrored chip (`4:5` with `5:4`, `1:1` with itself)
+- `default`: label or alias of the family selected by default
+- `families`: a non-empty list of family objects
+
+Each family object has:
+
+- `label`: unique name shown in the dropdown; `aliases` (optional list) are old names that still resolve to it
+- `models`: description string; `notes` (optional string) is ignored by the node
+- `group`: `image` or `video`
+- `vaeRatio`: `8`, `16` or `32`
+- `step`: positive integer grid step, a multiple of 8 (at most 4096), so rounded sizes land on the 8-pixel latent grid
+- `megapixels`: non-empty list of tiers used by custom ratios (each above 0, at most 64)
+- `default`: a `[width, height]` pair that appears in `sizes`
+- `sizes`: an object with one key per chip, each a list of `[width, height]` pairs in ascending pixel order (an empty list disables the chip)
+
+Every size must be a multiple of `step`, within 7% of its chip's ratio, listed under one chip only, and have its swapped size under the mirrored chip. `validate_table` returns every problem as text and never raises.
+
+## User Override File
+
+To change sizes without editing the shipped file, create `model_resolutions.json` in a `kikotools` folder inside ComfyUI's user directory (`folder_paths.get_user_directory()`; typically `ComfyUI/user/kikotools/model_resolutions.json`). It uses the same schema as the shipped file, and any top-level `chips` or `mirror` are ignored. Rules:
+
+- Families are matched by `label`. A family with a shipped label replaces that family whole; a new label is appended after the shipped ones, in file order.
+- `remove` is a list of labels that deletes shipped families. It wins over `families` when both name the same label.
+- `default` is an optional label or alias that becomes the default family; it must name a family that survives the merge.
+- The file is read again when its modification time changes, so a page reload (or ComfyUI's "Refresh node definitions") picks up edits, including the `model` dropdown, without restarting ComfyUI.
+- The shipped file is never modified.
+
+This example replaces SDXL with a shorter list, adds a new family, hides two shipped ones and makes the new family the default:
+
+```json
+{
+  "version": 1,
+  "default": "My SDXL",
+  "remove": ["SD 1.5", "Anima"],
+  "families": [
+    {
+      "label": "SDXL",
+      "aliases": [],
+      "models": "SDXL with a trimmed size list",
+      "group": "image",
+      "vaeRatio": 8,
+      "step": 64,
+      "megapixels": [1.0],
+      "default": [1024, 1024],
+      "sizes": {
+        "1:1": [[1024, 1024]],
+        "4:5": [[832, 1024]],
+        "5:4": [[1024, 832]],
+        "3:4": [], "4:3": [], "2:3": [], "3:2": [],
+        "9:16": [], "16:9": [], "21:9": [], "9:21": []
+      }
+    },
+    {
+      "label": "My SDXL",
+      "aliases": ["my-sdxl"],
+      "models": "My own SDXL finetune",
+      "group": "image",
+      "vaeRatio": 8,
+      "step": 64,
+      "megapixels": [1.0],
+      "default": [1152, 896],
+      "sizes": {
+        "1:1": [[1024, 1024]],
+        "4:5": [[896, 1152]], "5:4": [[1152, 896]],
+        "3:4": [], "4:3": [], "2:3": [], "3:2": [],
+        "9:16": [], "16:9": [], "21:9": [], "9:21": []
+      }
+    }
+  ]
+}
+```
+
+The merged table is checked with the same `validate_table`. If the file is unreadable, is not valid JSON, nests too deeply, or fails the check, the whole file is ignored and the shipped table is used. ComfyUI logs a warning `Override ignored: <path>: <reason>`, the same text is returned in the `warnings` list of `GET /kikotools/model_resolution/families`, and the panel's status line shows the first warning. Fix the file and reload to clear it.
+
+## How to Use
+
+### Chips and size list
+1. **Pick a model** in the dropdown.
+2. **Click a ratio chip** (`1:1 4:5 5:4 3:4 4:3 2:3 3:2 9:16 16:9 21:9 9:21`; each shows a small outline of its shape). The size list under the active chip shows that family's sizes for the ratio.
+3. **Click a size** to write it to width and height. The header shows `W × H · ratio · MP` for the current values.
+
+A chip is disabled when the family lists no sizes for that ratio.
+
+### Resolution dropdown
+The native `resolution` dropdown sits between `model` and `width` and mirrors the panel. Its options are `custom` plus every size label from the shipped families (sorted as text), written `{w}×{h} - {ratio} ({mp}MP)` with 1 MP = 1,048,576 pixels, for example `1216×832 - 3:2 (1.0MP)`.
+
+- In the UI the dropdown lists the sizes of the active ratio chip, or every size of the family when `Custom ratio` is active or no chip matches.
+- Picking a label writes width and height and activates the matching chip.
+- Clicking a chip or a size, or swapping, sets the label to match.
+- Typing a size that is not in the list, wiring width or height, a families table that is still loading, or a failed load shows `custom`.
+- On execution a non-`custom` label that parses wins over width and height; `custom` or an unparseable label uses width and height. Labels that only an override file adds are accepted too.
+
+### Swap
+The Swap W×H button (the same control Width Height Selector and Empty Latent Batch use) exchanges width and height and lands on the mirrored chip, for example 3:4 becomes 4:3.
+
+### Changing the model
+Switching the model keeps the current size if the new family lists it. Otherwise it falls back to the active chip's default size in the new family, then to the family default.
+
+### Custom ratio
+Choose the `Custom ratio` chip and type a ratio such as `16:9`. The panel computes sizes at the family's megapixel tiers, rounded to the family's step. Bad input is rejected with "Enter a ratio like 16:9".
+
+### Custom resolution
+Type width and height directly in the native widgets. The panel re-derives its chip, list and header from those values. They are rounded to the family's step when the node runs.
+
+### Wired-in width or height
+When width or height is driven by another node, the panel and Swap are disabled.
+
+### Sizes unavailable
+If the families route fails, the panel shows "Sizes unavailable; type width and height" with the chips disabled. The node still works through the native widgets.
+
+Panel state is derived from the native widgets, so nothing extra is saved in the workflow. New nodes are 340 px wide and the node height follows the panel content: it is re-fitted whenever the list changes (a chip click, a model change, opening Custom ratio), so there is no empty space under the list. A saved workflow keeps its width; the height is fitted again on load.
+
+## Keyframe Note for Video Families
+
+`Wan 2.2`, `LTX-2`, `HunyuanVideo 1.5` and `MiniMax H3` (all suffixed `(keyframes)`) are listed for first/last-frame generation at the video model's frame size. The latent output is still an image latent and is never fed to a video model. The image latent decodes to the listed size when the keyframe image model's VAE ratio divides the video family's step (for example an 8x or 16x image model for Wan 2.2's 1280×720; a 32x model would not land on 720).
+
+## Manual GPU Check Before Merge
+
+The real-host CI never queues a generation, so the latent path is only unit-tested. Core `EmptyLatentImage` is the same 4-channel, 8x, marked latent this node emits, and the official Anima template already runs that path (channel repeat 4 → 16). Confirm two cases by hand on a GPU box. Each is one queued image through this node → KSampler → VAE Decode → Save:
+
+1. `Flux.2 / Klein / MOSS` (16x) at 1248×832.
+2. `HunyuanImage 2.1` (32x) at 2560×1536.
+
+For each case, the saved PNG's dimensions must equal the node's width and height outputs. Record both results in the PR description.
+
+## Related Nodes
+
+- [Width Height Selector](width_height_selector.md): preset-based dimensions with swap
+- [Empty Latent Batch](empty_latent_batch.md): empty latent batches with presets

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

@@ -11,4 +11,4 @@ Enchanted forest with magical glowing mushrooms, fairy lights, mystical atmosphe
 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
+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,7 +3,14 @@ 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.checkpoint_folder_iterator import CheckpointFolderIteratorNode
 from .tools.display_any import DisplayAnyNode
 from .tools.display_text import DisplayTextNode
 from .tools.embedding_autocomplete import KikoEmbeddingAutocomplete
@@ -13,14 +20,19 @@ 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.project_file_path import ProjectFilePathNode
+from .tools.model_compare_sheet import ModelCompareSheetNode
 from .tools.model_downloader import ModelDownloaderNode
+from .tools.model_resolution_picker import ModelResolutionPickerNode
 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,
@@ -32,6 +44,10 @@ 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,
@@ -39,6 +55,7 @@ NODE_CLASS_MAPPINGS = {
     "SamplerCombo": SamplerComboNode,
     "SamplerComboCompact": SamplerComboCompactNode,
     "EmptyLatentBatch": EmptyLatentBatchNode,
+    "ModelResolutionPicker": ModelResolutionPickerNode,
     "KikoSaveImage": KikoSaveImageNode,
     "ImageToMultipleOf": ImageToMultipleOfNode,
     "ImageScaleDownBy": ImageScaleDownByNode,
@@ -56,11 +73,20 @@ NODE_CLASS_MAPPINGS = {
     "FluxSamplerParams": FluxSamplerParamsNode,
     "PlotParameters+": PlotParametersNode,
     "LoRAFolderBatch": LoRAFolderBatchNode,
+    "CheckpointFolderIterator": CheckpointFolderIteratorNode,
+    "ModelCompareSheet": ModelCompareSheetNode,
+    "WidthHeightToVec2": WidthHeightToVec2Node,
+    "KikoWorkflowTimer": KikoWorkflowTimerNode,
+    "KikoProjectFilePath": ProjectFilePathNode,
     # 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",
@@ -68,6 +94,7 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "SamplerCombo": "Sampler Combo",
     "SamplerComboCompact": "Sampler Combo (Compact)",
     "EmptyLatentBatch": "Empty Latent Batch",
+    "ModelResolutionPicker": "Model Resolution Picker",
     "KikoSaveImage": "Kiko Save Image",
     "ImageToMultipleOf": "Image to Multiple of",
     "ImageScaleDownBy": "Image Scale Down By",
@@ -85,6 +112,11 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "FluxSamplerParams": "Flux Sampler Parameters",
     "PlotParameters+": "Plot Parameters",
     "LoRAFolderBatch": "LoRA Folder Batch",
+    "CheckpointFolderIterator": "Checkpoint Folder Iterator",
+    "ModelCompareSheet": "Model Compare Sheet",
+    "WidthHeightToVec2": "Width Height to VEC2",
+    "KikoWorkflowTimer": "Workflow Timer",
+    "KikoProjectFilePath": "Project File Path",
     # KikoEmbeddingAutocomplete removed - settings only, not a node
 }
 

kikotools/base/model_folders.py

@@ -0,0 +1,106 @@
+"""Scan ComfyUI model folders (loras, checkpoints, ...) for .safetensors files."""
+
+import logging
+import os
+import re
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+def get_model_roots(folder_key: str) -> List[str]:
+    """Return every configured root directory for a folder_paths key."""
+    try:
+        import folder_paths
+
+        entry = folder_paths.folder_names_and_paths.get(folder_key)
+        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, folder_key: str
+) -> List[Tuple[str, Optional[str]]]:
+    """
+    Resolve a folder setting to (directory, base_root) pairs to scan.
+
+    base_root is the model root the directory lives in, or None when the
+    directory is an absolute path outside every known root.
+    """
+    roots = get_model_roots(folder_key)
+
+    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 {folder_key} directory: {folder_path}")
+            continue
+        targets.append((candidate, root))
+    return targets
+
+
+def scan_model_entries(folder_path: str, folder_key: str) -> List[Tuple[str, str]]:
+    """Return naturally sorted (relative_name, absolute_path) for every .safetensors."""
+    entries: Dict[str, str] = {}
+    for directory, base in resolve_scan_targets(folder_path, folder_key):
+        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 natural_sort(items: List[str]) -> List[str]:
+    """Sort strings so embedded numbers compare numerically (v2 < v10)."""
+
+    def natural_key(text):
+        parts = []
+        for part in re.split(r"(\d+)", text):
+            if not part:
+                continue
+            parts.append((0, int(part)) if part.isdigit() else (1, part.lower()))
+        return parts
+
+    return sorted(items, key=natural_key)
+
+
+def filter_by_pattern(
+    names: List[str], include_pattern: str = "", exclude_pattern: str = ""
+) -> List[str]:
+    """Keep names matching include_pattern (if set) and not exclude_pattern (if set)."""
+    filtered = list(names)
+    if include_pattern:
+        try:
+            include_re = re.compile(include_pattern)
+            filtered = [f for f in filtered if include_re.search(f)]
+        except re.error as e:
+            logger.error(f"Invalid include pattern: {e}")
+    if exclude_pattern:
+        try:
+            exclude_re = re.compile(exclude_pattern)
+            filtered = [f for f in filtered if not exclude_re.search(f)]
+        except re.error as e:
+            logger.error(f"Invalid exclude pattern: {e}")
+    return filtered

kikotools/core/registry.py

@@ -1,95 +0,0 @@
-"""Tool registry for KikoTools.
-
-This module provides the central registration system for all KikoTools nodes.
-"""
-
-import importlib
-from typing import Dict, Any
-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:
-            # 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("        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("            options: (value) => {")
-                    js_lines.append(
-                        f"                const options = {json.dumps(setting.options)};"
-                    )
-                    js_lines.append("                return options.map(opt => ({")
-                    js_lines.append("                    value: opt,")
-                    js_lines.append("                    text: String(opt),")
-                    js_lines.append("                    selected: opt === value")
-                    js_lines.append("                }));")
-                    js_lines.append("            }},")
-
-                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("            onChange(value) {")
-                    js_lines.append(f"                {setting.on_change}")
-                    js_lines.append("            }")
-
-                js_lines.append("        }});")
-                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/node_simple.py

@@ -1,72 +0,0 @@
-"""Simple Batch Prompts node for ComfyUI - debugging version."""
-
-import os
-from typing import Tuple
-from ...base.base_node import ComfyAssetsBaseNode
-from .logic import (
-    load_prompts_from_file,
-    get_prompt_at_index,
-    split_prompt_into_positive_negative,
-)
-
-# Global counter that persists across all executions
-GLOBAL_COUNTER = {"count": 0}
-
-
-class SimpleBatchPromptsNode(ComfyAssetsBaseNode):
-    """
-    Simplified Batch Prompts node for debugging.
-    Uses a global counter to ensure prompts change.
-    """
-
-    @classmethod
-    def INPUT_TYPES(cls):
-        """Define the input types for the ComfyUI node."""
-        return {
-            "required": {
-                "prompt_file": ("STRING", {"default": "prompts.txt"}),
-            }
-        }
-
-    RETURN_TYPES = ("STRING", "STRING", "INT")
-    RETURN_NAMES = ("positive", "negative", "index")
-    FUNCTION = "get_next_prompt"
-    CATEGORY = "🫶 ComfyAssets/📝 Text"
-
-    @classmethod
-    def IS_CHANGED(cls, **kwargs):
-        """Force re-execution every time."""
-        GLOBAL_COUNTER["count"] += 1
-        return GLOBAL_COUNTER["count"]
-
-    def get_next_prompt(self, prompt_file: str) -> Tuple[str, str, int]:
-        """Get the next prompt in sequence."""
-        # Resolve file path
-        if not os.path.isabs(prompt_file):
-            try:
-                import folder_paths
-
-                input_dir = folder_paths.get_input_directory()
-                full_path = os.path.join(input_dir, prompt_file)
-            except ImportError:
-                full_path = os.path.abspath(prompt_file)
-        else:
-            full_path = prompt_file
-
-        # Load prompts
-        prompts = load_prompts_from_file(full_path)
-        if not prompts:
-            return ("No prompts found", "", 0)
-
-        # Get current prompt based on global counter
-        index = GLOBAL_COUNTER["count"] % len(prompts)
-        current_prompt, _ = get_prompt_at_index(prompts, index, wrap=True)
-
-        # Split positive/negative
-        positive, negative = split_prompt_into_positive_negative(current_prompt)
-
-        print(
-            f"[SimpleBatchPrompts] Counter={GLOBAL_COUNTER['count']}, Index={index}, Prompt={positive[:30]}..."
-        )
-
-        return (positive, negative, index)

kikotools/tools/batch_prompts/state_manager.py

@@ -19,7 +19,7 @@ class StateManager:
         """Load state from file."""
         if self.state_file.exists():
             try:
-                with open(self.state_file, "r") as f:
+                with open(self.state_file, "r", encoding="utf-8") as f:
                     return json.load(f)
             except (json.JSONDecodeError, IOError):
                 pass
@@ -28,7 +28,7 @@ class StateManager:
     def save_state(self, state: Dict[str, Any]):
         """Save state to file."""
         try:
-            with open(self.state_file, "w") as f:
+            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}")

kikotools/tools/checkpoint_folder_iterator/__init__.py

@@ -0,0 +1,5 @@
+"""Checkpoint Folder Iterator module."""
+
+from .node import CheckpointFolderIteratorNode
+
+__all__ = ["CheckpointFolderIteratorNode"]

kikotools/tools/checkpoint_folder_iterator/logic.py

@@ -0,0 +1,52 @@
+"""Logic for the Checkpoint Folder Iterator node."""
+
+import os
+from typing import List, Sequence, Tuple, TypeVar
+
+from ...base.model_folders import filter_by_pattern, scan_model_entries
+
+T = TypeVar("T")
+
+
+def list_checkpoint_entries(
+    folder_path: str, include_pattern: str = "", exclude_pattern: str = ""
+) -> List[Tuple[str, str]]:
+    """(name, absolute_path) pairs for every checkpoint, filtered, in natural order.
+
+    The absolute path is what gets loaded, so folders outside the configured
+    checkpoints roots work too; the name is relative to the root (or to the
+    folder itself when it lives outside every root) and is used for labels.
+    """
+    entries = scan_model_entries(folder_path, "checkpoints")
+    names = [name for name, _ in entries]
+    kept = set(filter_by_pattern(names, include_pattern, exclude_pattern))
+    return [(name, path) for name, path in entries if name in kept]
+
+
+def list_checkpoints(
+    folder_path: str, include_pattern: str = "", exclude_pattern: str = ""
+) -> List[str]:
+    """Checkpoint names (relative to the checkpoints roots) in natural order."""
+    entries = list_checkpoint_entries(folder_path, include_pattern, exclude_pattern)
+    return [name for name, _ in entries]
+
+
+def pick_checkpoint(items: Sequence[T], index: int) -> T:
+    """Return items[index], or raise when the sweep has run past the end.
+
+    Wrapping would silently restart the sweep (and, downstream, archive the
+    grid that just finished), so an over-queued run fails loudly instead.
+    """
+    if not items:
+        raise ValueError("No checkpoints found")
+    if not 0 <= index < len(items):
+        raise ValueError(
+            f"Index {index} is past the end: only {len(items)} checkpoints matched. "
+            "The sweep is complete; reset index to 0 to start a new one."
+        )
+    return items[index]
+
+
+def label_for(ckpt_name: str) -> str:
+    """Label drawn under a tile for this checkpoint. Default: the file stem."""
+    return os.path.splitext(os.path.basename(ckpt_name))[0]

kikotools/tools/checkpoint_folder_iterator/node.py

@@ -0,0 +1,80 @@
+"""Checkpoint Folder Iterator node for ComfyUI."""
+
+from typing import Tuple
+
+from ...base.base_node import ComfyAssetsBaseNode
+from .logic import label_for, list_checkpoint_entries, pick_checkpoint
+
+
+class CheckpointFolderIteratorNode(ComfyAssetsBaseNode):
+    """
+    Load one checkpoint from a folder per queued run.
+
+    Set index to 0 with "increment" and queue as many runs as there are
+    checkpoints: each run loads the next file, so only one model is in
+    memory at a time. A run past the last checkpoint fails with a clear
+    error rather than wrapping around, so over-queuing never restarts the
+    sweep. Pairs with Model Compare Sheet to build a labeled grid.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "folder": (
+                    "STRING",
+                    {
+                        "default": ".",
+                        "multiline": False,
+                        "tooltip": "Folder relative to models/checkpoints (or absolute)",
+                    },
+                ),
+                "index": (
+                    "INT",
+                    {
+                        "default": 0,
+                        "min": 0,
+                        "max": 9999,
+                        "control_after_generate": True,
+                        "tooltip": "Which checkpoint to load; errors past the end",
+                    },
+                ),
+            },
+            "optional": {
+                "include_pattern": (
+                    "STRING",
+                    {"default": "", "tooltip": "Regex to include (empty = all)"},
+                ),
+                "exclude_pattern": (
+                    "STRING",
+                    {"default": "", "tooltip": "Regex to exclude (empty = none)"},
+                ),
+            },
+        }
+
+    RETURN_TYPES = ("MODEL", "CLIP", "VAE", "STRING", "STRING", "INT", "INT")
+    RETURN_NAMES = ("model", "clip", "vae", "ckpt_name", "label", "index", "count")
+    FUNCTION = "load"
+    CATEGORY = "🫶 ComfyAssets/🧰 xyz-helpers"
+
+    def load(
+        self,
+        folder: str,
+        index: int,
+        include_pattern: str = "",
+        exclude_pattern: str = "",
+    ) -> Tuple[object, object, object, str, str, int, int]:
+        import folder_paths
+        import comfy.sd
+
+        entries = list_checkpoint_entries(folder, include_pattern, exclude_pattern)
+        ckpt_name, ckpt_path = pick_checkpoint(entries, index)
+        self.log_info(f"Loading {index + 1}/{len(entries)}: {ckpt_name}")
+
+        model, clip, vae = comfy.sd.load_checkpoint_guess_config(
+            ckpt_path,
+            output_vae=True,
+            output_clip=True,
+            embedding_directory=folder_paths.get_folder_paths("embeddings"),
+        )[:3]
+        return model, clip, vae, ckpt_name, label_for(ckpt_name), index, len(entries)

kikotools/tools/empty_latent_batch/logic.py

@@ -43,7 +43,8 @@ def create_empty_latent_batch(
     # Standard VAE uses 4 channels
     latent_tensor = torch.zeros(batch_size, 4, latent_height, latent_width)
 
-    return {"samples": latent_tensor}
+    # Same mark as core EmptyLatentImage: lets the sampler resize this empty latent for 16x VAEs
+    return {"samples": latent_tensor, "downscale_ratio_spacial": 8}
 
 
 def validate_dimensions(width: int, height: int) -> bool:

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"
 
     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

@@ -1,89 +0,0 @@
-{
-  "models": [
-    "gemini-2.5-pro",
-    "gemini-2.5-flash",
-    "gemini-2.5-flash-lite",
-    "gemini-2.5-pro-preview-03-25",
-    "gemini-2.5-flash-preview-05-20",
-    "gemini-2.5-pro-preview-05-06",
-    "gemini-2.5-pro-preview-06-05",
-    "gemini-2.5-flash-lite-preview-06-17",
-    "gemini-2.0-flash",
-    "gemini-2.0-flash-001",
-    "gemini-2.0-flash-lite-001",
-    "gemini-2.0-flash-lite",
-    "gemini-2.5-flash-preview-tts",
-    "gemini-2.5-pro-preview-tts",
-    "gemini-2.0-flash-preview-image-generation",
-    "gemini-2.0-flash-exp",
-    "gemini-2.0-flash-exp-image-generation",
-    "gemini-2.0-flash-lite-preview-02-05",
-    "gemini-2.0-flash-lite-preview",
-    "gemini-2.0-pro-exp",
-    "gemini-2.0-pro-exp-02-05",
-    "learnlm-2.0-flash-experimental",
-    "gemini-1.5-pro-latest",
-    "gemini-1.5-pro-002",
-    "gemini-1.5-pro",
-    "gemini-1.5-flash-latest",
-    "gemini-1.5-flash",
-    "gemini-1.5-flash-002",
-    "gemini-1.5-flash-8b",
-    "gemini-1.5-flash-8b-001",
-    "gemini-1.5-flash-8b-latest",
-    "gemini-2.0-flash-thinking-exp-01-21",
-    "gemini-2.0-flash-thinking-exp",
-    "gemini-2.0-flash-thinking-exp-1219",
-    "gemma-3-1b-it",
-    "gemma-3-4b-it",
-    "gemma-3-12b-it",
-    "gemma-3-27b-it",
-    "gemma-3n-e4b-it",
-    "gemma-3n-e2b-it",
-    "gemini-exp-1206"
-  ],
-  "descriptions": {
-    "gemini-1.5-pro-latest": "Gemini 1.5 Pro Latest",
-    "gemini-1.5-pro-002": "Gemini 1.5 Pro 002",
-    "gemini-1.5-pro": "Gemini 1.5 Pro",
-    "gemini-1.5-flash-latest": "Gemini 1.5 Flash Latest",
-    "gemini-1.5-flash": "Gemini 1.5 Flash",
-    "gemini-1.5-flash-002": "Gemini 1.5 Flash 002",
-    "gemini-1.5-flash-8b": "Gemini 1.5 Flash-8B",
-    "gemini-1.5-flash-8b-001": "Gemini 1.5 Flash-8B 001",
-    "gemini-1.5-flash-8b-latest": "Gemini 1.5 Flash-8B Latest",
-    "gemini-2.5-pro-preview-03-25": "Gemini 2.5 Pro Preview 03-25",
-    "gemini-2.5-flash-preview-05-20": "Gemini 2.5 Flash Preview 05-20",
-    "gemini-2.5-flash": "Gemini 2.5 Flash",
-    "gemini-2.5-flash-lite-preview-06-17": "Gemini 2.5 Flash-Lite Preview 06-17",
-    "gemini-2.5-pro-preview-05-06": "Gemini 2.5 Pro Preview 05-06",
-    "gemini-2.5-pro-preview-06-05": "Gemini 2.5 Pro Preview",
-    "gemini-2.5-pro": "Gemini 2.5 Pro",
-    "gemini-2.0-flash-exp": "Gemini 2.0 Flash Experimental",
-    "gemini-2.0-flash": "Gemini 2.0 Flash",
-    "gemini-2.0-flash-001": "Gemini 2.0 Flash 001",
-    "gemini-2.0-flash-exp-image-generation": "Gemini 2.0 Flash (Image Generation) Experimental",
-    "gemini-2.0-flash-lite-001": "Gemini 2.0 Flash-Lite 001",
-    "gemini-2.0-flash-lite": "Gemini 2.0 Flash-Lite",
-    "gemini-2.0-flash-preview-image-generation": "Gemini 2.0 Flash Preview Image Generation",
-    "gemini-2.0-flash-lite-preview-02-05": "Gemini 2.0 Flash-Lite Preview 02-05",
-    "gemini-2.0-flash-lite-preview": "Gemini 2.0 Flash-Lite Preview",
-    "gemini-2.0-pro-exp": "Gemini 2.0 Pro Experimental",
-    "gemini-2.0-pro-exp-02-05": "Gemini 2.0 Pro Experimental 02-05",
-    "gemini-exp-1206": "Gemini Experimental 1206",
-    "gemini-2.0-flash-thinking-exp-01-21": "Gemini 2.5 Flash Preview 05-20",
-    "gemini-2.0-flash-thinking-exp": "Gemini 2.5 Flash Preview 05-20",
-    "gemini-2.0-flash-thinking-exp-1219": "Gemini 2.5 Flash Preview 05-20",
-    "gemini-2.5-flash-preview-tts": "Gemini 2.5 Flash Preview TTS",
-    "gemini-2.5-pro-preview-tts": "Gemini 2.5 Pro Preview TTS",
-    "learnlm-2.0-flash-experimental": "LearnLM 2.0 Flash Experimental",
-    "gemma-3-1b-it": "Gemma 3 1B",
-    "gemma-3-4b-it": "Gemma 3 4B",
-    "gemma-3-12b-it": "Gemma 3 12B",
-    "gemma-3-27b-it": "Gemma 3 27B",
-    "gemma-3n-e4b-it": "Gemma 3n E4B",
-    "gemma-3n-e2b-it": "Gemma 3n E2B",
-    "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:
@@ -115,30 +115,24 @@ def analyze_image_with_gemini(
     else:
         system_prompt = PROMPT_TEMPLATES.get(prompt_type, PROMPT_TEMPLATES["flux"])
 
-    # Here we would normally make the API call to Gemini
-    # For now, we'll import the google-generativeai library
     try:
-        import google.generativeai as genai
+        from google import genai
     except ImportError:
         return (
             "",
-            "google-generativeai library not installed. Please run: pip install google-generativeai",
+            "google-genai library not installed. Please run: pip install google-genai",
         )
 
     try:
-        # Configure Gemini
-        genai.configure(api_key=api_key)
+        client = genai.Client(api_key=api_key)
 
-        # Create model
-        model = genai.GenerativeModel(model_name)
-
-        # Generate content
-        response = model.generate_content(
-            [
+        response = client.models.generate_content(
+            model=model_name,
+            contents=[
                 system_prompt,
                 pil_image,
                 "Analyze this image and generate an appropriate prompt according to the instructions.",
-            ]
+            ],
         )
 
         # Extract text from response

kikotools/tools/gemini_prompt/models.py

@@ -59,10 +59,10 @@ def _fetch_models_from_api(
         Tuple of (model_names_list, model_descriptions_dict)
     """
     try:
-        import google.generativeai as genai
+        from google import genai
     except ImportError:
         if not silent:
-            logger.error("google-generativeai not installed")
+            logger.error("google-genai not installed")
         return [], {}
 
     # Get API key
@@ -77,15 +77,15 @@ def _fetch_models_from_api(
         return [], {}
 
     try:
-        genai.configure(api_key=api_key)
+        client = genai.Client(api_key=api_key)
 
         models = []
         descriptions = {}
 
         # Fetch all models
-        for model in genai.list_models():
+        for model in client.models.list():
             # Only include models that support generateContent
-            if "generateContent" in model.supported_generation_methods:
+            if "generateContent" in (model.supported_actions or []):
                 # Remove "models/" prefix from name
                 model_name = model.name.replace("models/", "")
                 models.append(model_name)
@@ -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

@@ -12,6 +12,8 @@ from .models import get_available_models
 class GeminiPromptNode(ComfyAssetsBaseNode):
     """Analyzes images using Gemini AI to generate optimized prompts for various AI models."""
 
+    DEPRECATED = True
+
     @classmethod
     def INPUT_TYPES(cls):
         """Define input types for the node."""
@@ -54,6 +56,9 @@ class GeminiPromptNode(ComfyAssetsBaseNode):
     CATEGORY = "🫶 ComfyAssets/🧠 Prompts"
 
     DESCRIPTION = """
+Deprecated: retained for existing workflows only. This node no longer receives
+Google API/model compatibility updates.
+
 Analyzes images using Google's Gemini AI to generate optimized prompts.
 
 Supports multiple prompt formats:
@@ -63,7 +68,7 @@ Supports multiple prompt formats:
 - Video: Motion and temporal descriptions for video generation
 
 Requires Gemini API key (set GEMINI_API_KEY env var or provide in node).
-Install: pip install google-generativeai
+Install: pip install google-genai
 """
 
     def generate_prompt(

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",
                     },
                 ),

kikotools/tools/kiko_purge_vram/node.py

@@ -55,6 +55,11 @@ class KikoPurgeVRAM(BaseNode):
     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,

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