sammykumar-ComfyUI-SwissArmyKnife/dev-docs/web-js/README.md

UI Widgets Documentation

Reusable UI components and custom widgets for ComfyUI-SwissArmyKnife nodes.

📄 Documentation Files

Core Widgets

• CONTROL_PANEL.md - Dashboard widget for monitoring and displaying workflow data
• DIMENSIONS_DISPLAY.md - Media dimension display widget with troubleshooting
• RESOURCE_MONITOR.md - Floating HUD with live telemetry + inline restart workflow
• SEED_WIDGET.md - Randomization seed widget for reproducible workflows
• UPLOAD_WIDGETS.md - Interactive upload buttons for media files
• WIDGET_FIXES.md - General widget fixes, visibility management, and state persistence

🎯 Widget Categories

Control Panel

• Multi-option configuration interface
• JSON data handling and parsing
• Two-column layout for metadata and content
• Dynamic option visibility
• Workflow serialization and execution monitoring

Dimension Display

• Automatic width/height display
• Multiple message format support
• API event handler integration
• Real-time updates after execution
• Debug logging and troubleshooting

Seed Widget

• Random seed generation with 🎲 button
• Seed value persistence across workflows
• Smart visibility (shows only for "Randomize from Path" mode)
• Reproducible file selection
• Large integer range support (0 to 2^64-1)

Resource Monitor ⭐ NEW: OOM Detection System

• Floating HUD: Glassmorphism bar with live CPU/RAM/GPU/VRAM monitoring via WebSocket
• Workflow Profiler: Popup showing execution stats, cache hits, VRAM peaks
• OOM Detection & Analysis: ✅ FULLY IMPLEMENTED & TESTED
  • Pre-OOM warnings at 85% (⚠️ yellow) and 95% (🔴 red) VRAM thresholds
  • Visual warning indicators on stats cards in profiler popup
  • 💥 OOM column in node execution table showing failed nodes
  • Comprehensive "💥 OOM Analysis" modal tab with:
    • Summary cards (Total OOMs, OOM Rate, Workflow Count)
    • Recent OOM events with detailed context (VRAM, models, timing)
    • Node type ranking by OOM frequency
    • Model correlation analysis (problematic combinations)
    • Auto-generated recommendations with severity indicators
• Restart Workflow: Full /swissarmyknife/restart lifecycle with health polling
• Independent Extension: Separate from menu-based widgets for modular development

Upload Widgets

• Interactive file upload buttons for images and videos
• ComfyUI integration with built-in upload system
• Dynamic widget visibility based on media type
• Click-to-upload interface with file browser
• Real-time button updates showing selected filenames

Widget Fixes

• Visibility management and hiding mechanism
• Final string widget update handling
• State persistence with onSerialize/onConfigure
• Upload widget management
• Dynamic widget system improvements

🔧 Implementation Patterns

Widget Registration

app.registerExtension({
    name: 'widget_name',
    async beforeRegisterNodeDef(nodeType, nodeData, app) {
        // Widget setup
    },
});

State Persistence

Widgets should:

1. Save state to node properties
2. Restore state on node creation
3. Serialize state in workflow JSON
4. Handle missing/invalid state gracefully

Event Handling

• Listen to ComfyUI API events
• Update UI on node execution
• Handle user interactions
• Clean up event listeners on removal

🆕 Latest Updates

November 29, 2025 - OOM Detection System v1.4.0

Status: ✅ COMPLETE & TESTED

Comprehensive Out of Memory detection and analysis system:

• Backend: Full OOM tracking with historical statistics (profiler_core.py)
• API: REST endpoint at /swissarmyknife/profiler/stats returns .data.oom_stats
• Frontend: Visual indicators, 💥 column, and dedicated OOM Analysis tab
• Testing: User-verified working with live OOM data from WanVideoSampler workflows

See RESOURCE_MONITOR.md for complete implementation details.

📚 Related Documentation

• Debug System - For widget debugging

---

Category: UI Components Status: Active Development