Cursor Rules for FastLED WASM Project

CRITICAL: Python Command Usage

ALWAYS use uv to run Python code, NOT python or python3!

Command Guidelines:

• ✅ Use: uv run <script.py>
• ✅ Use: uv run -m <module>
• ✅ Use: uv run python <script.py> (if explicitly needed)
• ❌ NEVER use: python <script.py>
• ❌ NEVER use: python3 <script.py>

Examples:

• Instead of python src/fastled/cli.py, use uv run src/fastled/cli.py
• Instead of python -m pytest, use uv run -m pytest
• Instead of python3 build_exe.py, use uv run build_exe.py

Rationale:

• This project uses uv for Python package and environment management
• Using python or python3 directly may use the wrong Python version or miss dependencies
• uv ensures consistent execution with the project's specified Python version and dependencies

Testing:

• Follow the user rule: run unit tests with bash test
• For manual testing, use uv run prefix for any Python commands

Development Workflow:

1. Use uv for all Python execution
2. Ensure virtual environment is managed by uv
3. Install dependencies with uv add <package>
4. Run scripts with uv run <script>

Emoji/Emoticon Usage

ALWAYS use the EMO() function for emojis, NEVER hardcode emojis directly!

Guidelines:

• ✅ Use: from fastled.emoji_util import EMO then EMO('⚠️', 'WARNING:')
• ✅ Use: from fastled.emoji_util import safe_print for Unicode-safe printing
• ❌ NEVER use: hardcoded emojis like print("⚠️ Warning")
• ❌ NEVER use: raw Unicode without fallback handling

Common Patterns:

• Warning messages: EMO('⚠️', 'WARNING:')
• Success messages: EMO('✅', 'SUCCESS:')
• Error messages: EMO('❌', 'ERROR:')
• Info messages: EMO('ℹ️', 'INFO:')
• Playwright/browser: EMO('🎭', '*')
• Package/install: EMO('📦', '*')

Rationale:

• Windows cmd.exe has poor Unicode support and will crash on raw emojis
• The EMO() function provides fallback text for systems that don't support emojis
• Ensures consistent behavior across all platforms (Windows, macOS, Linux)
• Prevents application crashes due to encoding issues

Examples:

# Good - with EMO function
from fastled.emoji_util import EMO
print(f"{EMO('⚠️', 'WARNING:')} Debug mode detected with Playwright installed")

# Bad - hardcoded emoji
print("⚠️ Debug mode detected with Playwright installed")

Additional Rules:

• When suggesting Python commands, always prefix with uv run
• When creating scripts that execute Python, use uv run in the script
• When documenting Python usage, emphasize uv run syntax
• Update any existing scripts that use python or python3 to use uv run
• When adding user-facing messages with emojis, always use the EMO() function