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

Control Panel Widget

Last Updated: October 8, 2025
Status: Completed

The Control Panel node is a display-only dashboard node that shows data from connected workflow nodes. It includes a predefined input (legacy name all_media_describe_data) that can accept any JSON payload, plus the ability to add dynamic wildcard inputs for other connections.

---

Table of Contents

1. Overview
2. Implementation Details
3. JSON Data Format
4. Usage
5. Troubleshooting

---

Overview

The Control Panel provides a flexible dashboard for monitoring workflow data with:

• Predefined Input: all_media_describe_data input for structured describe JSON (legacy name retained)
• Dynamic Inputs: Add unlimited wildcard inputs via context menu
• Dual Display Modes: Connection info (before execution) and execution results (after execution)
• Two-Column Layout: Organized display with left (metadata) and right (content) columns
• Real-time Updates: Automatically updates when connections change or execution completes

---

Implementation Details

Backend (Python)

File: nodes/utils/control_panel.py

Key Features

1. Predefined Input

   • Includes all_media_describe_data input (wire any JSON string here)
   • Type: STRING with forceInput: True (connection-only, no text widget)
   • Perfect for connecting LM Studio structured nodes' json_output (or any aggregated output)

2. Dynamic Input Handling

   • Accepts **kwargs to handle any connected inputs dynamically
   • Python side automatically receives all connected data
   • Can add more wildcard inputs via JavaScript context menu

3. OUTPUT_NODE Configuration

   • Set as OUTPUT_NODE = True to display in UI
   • RETURN_TYPES = () - no outputs, display-only node
   • Returns data via {"ui": {...}} format for JavaScript consumption

4. Console Logging

   • Logs all connected data to console with formatting
   • Truncates long strings (>200 chars) for readability
   • Displays "(No inputs connected)" when no data available

5. Data Format

   • Converts all values to lists (ComfyUI convention)
   • Returns {"ui": {key: [value], ...}} structure
   • JavaScript reads from message.output in execution handler

Frontend (JavaScript)

File: web/js/swiss-army-knife.js

Key Features

1. Predefined Input Display

   • Node starts with all_media_describe_data input (from Python definition)
   • No default wildcard inputs added (predefined input is sufficient)
   • Input counter initialized from existing inputs

2. Dynamic Wildcard Inputs

   • Uses "*" type to accept any datatype (except primitives)
   • Right-click context menu: "➕ Add input" to add more
   • Can add as many additional inputs as needed

3. DOM Widget Display

   • Scrollable monospace display area (max 300px height)
   • Shows two modes:
     • Connection mode: Lists connected nodes and outputs
     • Execution mode: Shows actual data values from execution

4. Connection Information Display

   • Shows inputName ⇐ NodeName.outputName format
   • Updates automatically when connections change
   • Uses getInputLink() and getNodeById() to resolve connections

5. Execution Data Display

   • Triggered by onExecuted handler
   • Reads from message.output structure
   • Formats data with emoji prefixes and truncation
   • Handles both array and direct values

6. Context Menu Options

   • "➕ Add input": Adds a new wildcard input slot
   • "♻︎ Rebuild summary": Forces refresh of connection display

7. Auto-Update Triggers

   • onConnectionsChange: Updates when links are made/broken
   • onExecuted: Updates with execution results
   • onResize: Adjusts DOM width to match node width

---

JSON Data Format

The Problem (Original Implementation)

The original MediaDescribe node sent a pre-formatted text string to the Control Panel:

# Old approach - formatted string
all_data = (
    f"📝 Description:\n{description}\n\n"
    f"📊 Media Info:\n{media_info_text}\n\n"
    # ... etc
)

This prevented the Control Panel from accessing individual fields, making it impossible to:

• Parse and format individual values
• Create organized multi-column layouts
• Filter or transform specific fields

The Solution (JSON Format)

Changed all_media_describe_data to a JSON string containing individual fields:

# New approach - structured JSON
all_data = json.dumps({
    "description": description,
    "media_info": media_info_text,
    "gemini_status": gemini_status,
    "processed_media_path": processed_media_path,
    "final_string": final_string,
    "height": output_height,
    "width": output_width
})

This change was applied to all four locations in mediia_describe.py where all_data is created:

1. Image upload with cache hit
2. Image processing without cache
3. Video with cache hit
4. Video processing without cache

Two-Column Layout

The Control Panel now uses a flexbox two-column layout:

Left Column (50% width) - Technical Metadata:

• 📊 Media Info
• 🔄 Gemini Status
• 📁 Processed Media Path
• 📐 Height
• 📐 Width

Right Column (50% width) - Content & Outputs:

• 📝 Description
• ✨ Final String

Each column:

• Has independent scrolling for long content
• Uses monospace font for better readability
• Properly handles truncation (>500 characters)
• Falls back to raw display if JSON parsing fails

Files Modified

Python:

• nodes/media_describe/mediia_describe.py
  • Added import json at the top
  • Converted all 4 all_data assignments to use json.dumps()

JavaScript:

• web/js/swiss-army-knife.js
  • Created two-column flex layout for Control Panel DOM
  • Updated updateControlPanelData() function to parse JSON and distribute fields
  • Updated updateControlPanelSummary() to work with two-column layout
  • Added _cp_leftColumn and _cp_rightColumn references for column management

Benefits

1. Structured Data: Control Panel receives structured JSON instead of pre-formatted text
2. Two-Column Layout: Better organization with metadata and content separation
3. Independent Scrolling: Each column scrolls independently for long content
4. Flexibility: JavaScript can format, truncate, or transform individual fields
5. Extensibility: Easy to add new fields or change display order
6. Better UX: Clearly labeled sections in an organized layout
7. Space Efficiency: 50/50 split maximizes horizontal space usage

---

Usage

Basic Setup

1. Add "🎛️ Control Panel" node to workflow
2. Node starts with all_media_describe_data input (legacy name)
3. Connect your structured describe node's json_output (or any JSON string) to it

Adding More Inputs

1. Right-click on Control Panel node
2. Select "➕ Add input"
3. New input slot appears (in1, in2, etc.)
4. Connect any non-primitive output to the new input

Viewing Results

Before Execution (Connection Mode):

all_media_describe_data ⇐ LLMStudioStructuredDescribe.json_output

After Execution (Data Mode):

═══ EXECUTION RESULTS ═══

Left Column:              Right Column:
📊 Media Info:           📝 Description:
📹 Video Processing...   A woman with long...

🔄 Gemini Status:        ✨ Final String:
✅ Complete              woman, long hair...

📁 Processed Media Path:
/path/to/media.mp4

📐 Dimensions:
1920 x 1080

Testing

To verify the Control Panel:

1. Create a workflow with:

   • LLMStudioStructuredDescribe (or LM Studio Structured Video Describe) node
   • ControlPanel node
   • Connect the describe node's json_output to ControlPanel's all_media_describe_data input

2. Execute the workflow with an image or video

3. Verify Control Panel displays:

   • Two-column layout (50/50 split)
   • Left column: media_info, gemini_status, processed_media_path, height, width
   • Right column: description, final_string
   • Each field individually displayed with emoji labels
   • Proper formatting and spacing
   • Independent scrolling for each column

---

Troubleshooting

Issue: NullArgumentError - LGraph reference null or undefined

Solution: Fixed by adding proper null checks in updateControlPanelSummary() function. The function now checks for this.graph || app.graph with fallback and defers the initial summary update by 100ms to ensure the graph is fully initialized.

Issue: Control Panel not updating with execution results

Solution: The Control Panel node now listens to API execution events in the setup() method. Added handler for node.comfyClass === "ControlPanel" that calls node.updateControlPanelData(output) when execution completes.

Issue: Inputs not accepting connections

Solution: Verify the output is not a primitive type. Wildcard inputs ("*") only accept non-primitive datatypes (STRING, INT, IMAGE, etc. - not direct text input).

Issue: Data not displaying after execution

Solution:

1. Check browser console for debug logs (enable DEBUG mode)
2. Verify Python node is returning {"ui": {...}} structure
3. Ensure the upstream describe node outputs JSON instead of a formatted string

Issue: Display area too small/large

Solution:

1. Adjust maxHeight in DOM element styling (currently 300px)
2. Or resize node manually by dragging corners
3. Use onResize to adjust width automatically

Issue: Browser cache showing old version

Solution: Hard refresh (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux) or use cache clearing utilities. See JavaScript Improvements for cache busting details.

Issue: JSON parsing fails

Solution: The Control Panel includes fallback handling. If JSON parsing fails, it displays the raw data. Check:

1. Upstream describe node emits JSON output
2. all_media_describe_data contains valid JSON string
3. No corruption in data transmission

---

Technical Details

ComfyUI Integration

Node Registration:

• Python class exported via CONTROL_PANEL_NODE_CLASS_MAPPINGS
• Display name: "🎛️ Control Panel"
• Category: "Utils"

Wildcard Input Type ("*"):

• Accepts any non-primitive datatype
• Allows connection to STRING, INT, IMAGE, etc.
• Does NOT accept primitive widgets (direct text input)

Execution Flow:

User connects nodes → Queue execution → Python runs →
Returns {"ui": data} → JavaScript onExecuted receives message.output →
DOM widget updates with parsed JSON

Data Structure:

// Python returns:
{"ui": {"all_media_describe_data": ["{\"description\": \"...\", ...}"]}}

// JavaScript receives in message.output:
{"all_media_describe_data": ["{\"description\": \"...\", ...}"]}

// JavaScript parses to:
{description: "...", media_info: "...", gemini_status: "...", ...}

Styling

Uses CSS custom properties for theming:

• --comfy-menu-bg / fallback #1e1e1e
• --border-color / fallback #333
• --fg-color / fallback #d4d4d4

Monospace font stack for cross-platform consistency:

font-family:
    ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
    monospace;

---

Known Limitations

1. Primitive Inputs: Wildcard "*" type doesn't accept primitive widgets (text input fields)
2. Serialization: DOM content not saved to workflow (by design - serialize: false)
3. Large Data: Values truncated at 500 characters to prevent UI slowdown
4. Input Naming: Inputs named sequentially (in1, in2, etc.) - not customizable via UI
5. JSON Parsing: If upstream nodes output non-JSON data, falls back to raw display

---

Future Enhancements

Possible improvements:

1. Custom Input Names: Allow renaming inputs via context menu
2. Collapsible Sections: Expand/collapse individual data fields
3. Export Data: Copy-to-clipboard or save-to-file functionality
4. Data Formatting: JSON prettification, syntax highlighting
5. Filter/Search: Search within displayed data
6. Display Modes: Toggle between compact/expanded views
7. Column Resize: Draggable divider for custom column widths

---

Related Documentation

• LM Studio Structured Describe Nodes - AI content analysis integration
• JavaScript Improvements - Cache busting and updates
• Debug System - For widget debugging