ComfyUI/custom_nodes/ComfyUI-Impact-Pack/docs/wildcards/SUMMARY.md

Wildcard System - Project Summary

Overview

Progressive on-demand wildcard loading system for ComfyUI Impact Pack with dynamic prompt support, UTF-8 encoding, and comprehensive testing.

Status: ✅ Production Ready Test Coverage: 86 tests, 100% pass rate Documentation: Complete PRD, design docs, and testing guide

---

Core Features

• Wildcard Expansion: __wildcard__ syntax with transitive multi-level expansion
• Dynamic Prompts:
  • Basic selection: {option1|option2|option3}
  • Weighted selection: {10::common|1::rare} (weight comes first)
  • Multi-select: {2$$, $$red|blue|green} with custom separators
• UTF-8 Support: Korean, Chinese, Arabic, emoji, special characters
• Pattern Matching: Depth-agnostic __*/name__ syntax
• On-Demand Loading: Progressive lazy loading with configurable cache limits
• Error Handling: Circular reference detection, graceful fallbacks

---

Architecture

Implementation

• modules/impact/wildcards.py - Core LazyWildcardLoader and expansion engine
• modules/impact/impact_server.py - Server API endpoint (/impact/wildcards)
• modules/impact/config.py - Configuration with quoted path support

Key Design Decisions

• Lazy Loading: Memory-efficient progressive loading strategy
• Transitive Expansion: Multi-level wildcard references through directory hierarchy
• Case-Insensitive Matching: Fuzzy matching for user convenience
• Circular Reference Detection: Max 100 iterations with clear error messages

---

Testing

Test Suites (86 tests)

1. UTF-8 Encoding (15 tests) - Multi-language support validation
2. Error Handling (10 tests) - Graceful error recovery
3. Edge Cases (20 tests) - Boundary conditions and special scenarios
4. Deep Nesting (17 tests) - 7-level transitive expansion + pattern matching
5. On-Demand Loading (8 tests) - Progressive loading with cache limits
6. Config Quotes (5 tests) - Configuration path handling
7. Dynamic Prompts (11 tests) - Statistical validation of dynamic features

Test Infrastructure

• Dedicated ports per suite (8188-8198)
• Automated server lifecycle management
• Comprehensive logging in /tmp/
• 100% pass rate with statistical validation

---

Documentation

• README - Quick start and feature overview
• PRD - Complete product requirements
• Design - Technical architecture
• Testing Guide - Test procedures and validation

---

Quick Start

Basic Usage

# Simple wildcard
"a photo of __animal__"

# Dynamic prompt
"a {red|blue|green} __vehicle__"

# Weighted selection (weight comes FIRST)
"{10::common|1::rare} scene"

# Multi-select
"{2$$, $$happy|sad|angry|excited} person"

Running Tests

cd tests/
bash test_encoding.sh
bash test_error_handling.sh
bash test_edge_cases.sh
bash test_deep_nesting.sh
bash test_ondemand_loading.sh
bash test_config_quotes.sh
bash test_dynamic_prompts_full.sh

---

Key Implementations

Weighted Selection Syntax

Correct: {weight::option} - Weight comes FIRST

• {10::common|1::rare} → 91% common, 9% rare ✅
• {5::red|3::green|2::blue} → 50%, 30%, 20% ✅

Incorrect: {option::weight} - Treated as equal weights

• {common::10|rare::1} → 50% each ❌

Empty Line Filtering

Filter empty lines AND comment lines:

[x for x in lines if x.strip() and not x.strip().startswith('#')]

Config Path Quotes

Strip quotes from configuration paths:

custom_wildcards_path = default_conf.get('custom_wildcards', '').strip('\'"')

---

Limitations

• Weighted selection supports integers and simple decimals only
• Complex decimal weights may conflict with multiselect pattern detection
• Circular references limited to 100 iterations
• Prefer integer weight ratios for clarity

---

Performance

• Lazy Loading: Only load wildcards when needed
• On-Demand Mode: Progressive loading based on cache limits
• Memory Efficient: Configurable cache size (0.5MB - 100MB)
• Fast Lookup: Optimized directory traversal with pattern matching

---

Production Ready

✅ Zero known bugs ✅ Complete PRD coverage ✅ 100% test pass rate ✅ Statistical validation ✅ Comprehensive documentation ✅ Multi-language support ✅ Graceful error handling