ComfyUI Annotations

A pure annotation/markup overlay system for ComfyUI's node editor. Draw freehand annotations directly on the canvas without modifying workflow data.

Features

• Freehand Drawing - Draw directly on the canvas with smooth strokes
• World-Space Annotations - Strokes follow zoom/pan, staying anchored to nodes
• Eraser Tool - Remove strokes with visual cursor feedback
• Undo/Redo - Full history support with configurable depth
• Persistence - Annotations save/load with your workflow
• Performance Optimized - Handles thousands of points smoothly
• Non-Destructive - Doesn't modify workflow data or break ComfyUI

Installation

Method 1: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager
2. Search for "Annotations"
3. Click Install
4. Restart ComfyUI

Method 2: Git Clone

cd ComfyUI/custom_nodes
git clone https://github.com/0dot77/comfyui-annotations.git

Then restart ComfyUI.

Method 3: Manual Download

1. Download the latest release from GitHub
2. Extract to ComfyUI/custom_nodes/comfyui-annotations/
3. Restart ComfyUI

Uninstallation

Via ComfyUI Manager

1. Open ComfyUI Manager
2. Find "ComfyUI Annotations" in installed extensions
3. Click Uninstall
4. Restart ComfyUI

Manual Uninstallation

cd ComfyUI/custom_nodes
rm -rf comfyui-annotations

Then restart ComfyUI.

Note: Uninstalling this extension will not affect your workflows. Annotations are stored in the workflow's extra field and will simply be ignored if the extension is not installed.

Usage

Quick Start

1. Press A to toggle annotation mode ON/OFF
2. Draw with your mouse or pen
3. Press A again to exit and return to normal node editing
4. Save your workflow - annotations are included automatically!

Keyboard Shortcuts

Key	Action
A	Toggle annotation mode ON/OFF
T	Collapse/expand toolbar
P	Switch to Pen tool
E	Switch to Eraser tool
Ctrl+Z / Cmd+Z	Undo
Ctrl+Shift+Z / Cmd+Shift+Z	Redo
Ctrl+Y / Cmd+Y	Redo (alternative)
Escape	Exit annotation mode

Toolbar

The toolbar appears in the top-right corner (below ComfyUI Manager) and provides:

• Mode Toggle - ON/OFF button for annotation mode
• Tool Selector - Pen and Eraser buttons
• Pen Settings - Size slider, opacity slider, color picker with presets
• Eraser Settings - Size slider
• Action Buttons - Undo, Redo, Clear (with disabled states)

Tips

• Annotations follow zoom/pan - they stay anchored to their position in the node graph
• Draw near nodes to annotate specific parts of your workflow
• Use different colors to categorize annotations
• Eraser removes entire strokes on contact (not partial erasure)

Compatibility

Browser Support

Browser	Version	Status	Notes
Chrome	90+	✅ Full	Primary development target
Edge	90+	✅ Full	Chromium-based
Firefox	88+	✅ Full	All features work
Safari	14+	✅ Full	Uses fallbacks for some features
Opera	76+	✅ Full	Chromium-based

Feature Support

The extension automatically detects browser capabilities and uses fallbacks:

• OffscreenCanvas - Used for stroke caching (fallback: regular canvas)
• getCoalescedEvents - Smoother fast strokes on Chromium (graceful degradation on others)
• Desynchronized Canvas - Lower latency on Chromium (ignored by others)

Check browser compatibility in the console:

comfyAnnotations.browser.printReport()

Tested With

• ComfyUI (latest)
• Python 3.10+
• Modern browsers (Chrome, Firefox, Safari, Edge)

Requirements

• ComfyUI with LiteGraph canvas
• No Python dependencies (frontend-only extension)

Known Issues

• None currently

File Structure

comfyui-annotations/
├── __init__.py                 # Extension registration
├── LICENSE                     # MIT License
├── README.md                   # This file
└── web/
    ├── main.js                 # Entry point & extension setup
    ├── style.css               # Overlay styles
    └── modules/
        ├── annotationOverlay.js    # DOM & canvas management
        ├── browserCompat.js        # Browser feature detection & fallbacks
        ├── coordinateUtils.js      # Coordinate transforms
        ├── hitTesting.js           # Stroke hit-testing for eraser
        ├── historyManager.js       # Undo/redo history stack
        ├── toolbarUI.js            # Collapsible toolbar UI
        ├── persistence.js          # Save/load with workflow
        └── renderOptimizer.js      # RAF batching, stroke caching

Debug API

For developers and troubleshooting, open the browser console:

// Mode & rendering
window.comfyAnnotations.toggle()           // Toggle annotation mode
window.comfyAnnotations.isActive()         // Check if mode is active
window.comfyAnnotations.render()           // Force re-render

// Stroke management
window.comfyAnnotations.getStrokes()       // Get all strokes array
window.comfyAnnotations.clearStrokes()     // Clear all strokes (with undo)

// Tool management
window.comfyAnnotations.getTool()          // Get current tool
window.comfyAnnotations.setTool('pen')     // Switch tool

// Pen settings
window.comfyAnnotations.setColor('#00FF00')// Set pen color
window.comfyAnnotations.setSize(8)         // Set pen size (1-50)
window.comfyAnnotations.setOpacity(0.5)    // Set pen opacity (0.1-1.0)

// Eraser settings
window.comfyAnnotations.setEraserSize(30)  // Set eraser radius (5-100)

// History
window.comfyAnnotations.undo()             // Undo last action
window.comfyAnnotations.redo()             // Redo last undone action
window.comfyAnnotations.canUndo()          // Check if undo available
window.comfyAnnotations.canRedo()          // Check if redo available

// Toolbar
window.comfyAnnotations.toolbar.toggle()   // Toggle toolbar collapse
window.comfyAnnotations.toolbar.show()     // Show toolbar
window.comfyAnnotations.toolbar.hide()     // Hide toolbar

// Performance
window.comfyAnnotations.performance.getMetrics()      // Get FPS, render times
window.comfyAnnotations.performance.runBenchmark()    // Run benchmark
window.comfyAnnotations.performance.setUseCache(true) // Enable/disable caching

// Debug
window.comfyAnnotations.debug.enable()     // Enable debug visualizer
window.comfyAnnotations.debug.runTests()   // Run coordinate tests

// Browser compatibility
window.comfyAnnotations.browser.printReport()  // Print compatibility report
window.comfyAnnotations.browser.getFeatures()  // Get all detected features
window.comfyAnnotations.browser.hasFeature('offscreenCanvas')  // Check specific feature

Performance

Optimized for large drawings with thousands of points:

• RAF Batching - Multiple pointer events coalesced into single render
• Stroke Cache - Completed strokes rendered to offscreen canvas
• Path2D Caching - Stroke paths cached for reuse

Run window.comfyAnnotations.performance.runBenchmark() to test performance.

Data Format

Annotations are stored in workflow JSON under extra.annotations:

{
  "extra": {
    "annotations": {
      "version": 1,
      "strokes": [
        {
          "id": "stroke_1234567890_abc123",
          "points": [{"x": 100, "y": 200}, ...],
          "color": "#FF5555",
          "size": 4,
          "opacity": 1.0
        }
      ]
    }
  }
}

The versioned format ensures forward compatibility for future updates.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Changelog

v1.0.0 (Initial Release)

• Freehand drawing with smooth strokes
• Pen tool with color, size, opacity settings
• Eraser tool with hit-testing
• Undo/redo with configurable history
• Clear all with undo support
• Collapsible toolbar UI
• Persistence (save/load with workflow)
• Performance optimizations (RAF batching, stroke caching)
• Keyboard shortcuts
• Debug API

License

MIT License - see LICENSE file for details.

Credits

Built for the ComfyUI community.