alexopus-ComfyUI-Notes-Sidebar/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a ComfyUI extension that adds a server-side notes sidebar for managing markdown notes. The extension provides a complete notes management system with both backend API endpoints and a frontend JavaScript interface.

Architecture

Backend (Python)

• Main Module: __init__.py - Core extension entry point
• NotesManager Class: Handles all note operations (CRUD) with file system storage
• API Endpoints: RESTful endpoints using aiohttp web framework integrated with ComfyUI's PromptServer
• File Storage: Notes stored as .md files in ComfyUI's user directory under default/comfyui-notes-sidebar/notes/ (fallback to extension's notes/ directory)

Frontend (JavaScript)

• Extension Module: js/extension.js - Main ComfyUI extension integration and UI orchestration
• State Management: js/stores/NotesStore.js - Event-driven state management using EventTarget pattern
• Components:
  • js/components/AppendMenu.js - Append functionality (currently LoRA integration) with submenu UI
• API Layer: js/api/notesApi.js - Centralized API calls with consistent error handling
• Utilities: js/utils/validation.js - Filename validation helpers
• Styling: js/notes-sidebar.css - Complete UI styling for dark theme integration

Key Components

1. Server Integration: Uses ComfyUI's PromptServer.instance.routes for API endpoints
2. File Management: Notes stored as markdown files with automatic directory creation
3. UI Architecture: Tab-based interface with content area and action buttons
4. Extension Registration: Properly registers with ComfyUI's extension manager as a sidebar tab
5. State Management: Centralized state using NotesStore class with EventTarget pattern:
   • noteContent: Current content for each note (including unsaved)
   • savedContent: Last saved content from server
   • unsavedChanges: Boolean flag for each note's modification state
   • Event-driven updates automatically sync UI components

API Endpoints

The extension exposes these REST endpoints:

Notes Management

• GET /notes_sidebar/list - List all notes
• GET /notes_sidebar/note/{note_name} - Get specific note content
• POST /notes_sidebar/note/{note_name} - Save/create note
• DELETE /notes_sidebar/note/{note_name} - Delete note

LoRA Integration

• GET /notes_sidebar/loras - List all available LoRA files
• GET /notes_sidebar/loras_with_metadata - List LoRAs with associated metadata from .txt files

Development Notes

Extension Structure

• Must export NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS, and WEB_DIRECTORY for ComfyUI compatibility
• JavaScript extension uses ComfyUI's app.registerExtension() pattern
• Sidebar integration uses app.extensionManager.registerSidebarTab()

File Operations

• Notes are automatically saved as .md files in the notes/ directory
• File names are URL-encoded for safe handling
• Directory creation is handled automatically on initialization

UI State Management

• Active note tracking with tab highlighting
• Content persistence across sidebar open/close cycles
• Real-time tab rendering on note operations
• Button layout: Save/Rename/LoRA submenu on left, Delete on right, Zoom in/out and Refresh in tabs area
• Search Functionality: Live search through note content with highlighted results and line navigation
• Unsaved Changes Tracking: Visual indicators (*) for modified notes
• Content Preservation: Tab switching preserves unsaved content
• Change Detection: Automatic tracking of modifications vs saved state
• Append Integration: Submenu with three formatting options for appending LoRA lists (extensible for other content types)
• Font Size Control: Zoom in/out buttons with persistent settings storage (8-24px range)

Search Functionality

• Search Input: Located below button container with "Search lines..." placeholder
• Live Search: Results update as you type, case-insensitive matching
• Split View: Original textarea remains fully editable while search results appear below
• Result Navigation: Click any search result to jump to that line in the main editor
• Highlighting: Matching text highlighted with yellow background in search results
• Clear Button: PrimeVue pi-times-circle icon for quick search clearing
• Auto-Update: Search results refresh when switching between notes
• HTML Safety: Proper escaping prevents HTML injection in search results

Unsaved Changes Behavior

• Notes with modifications show asterisk (*) in tab name
• Switching tabs preserves unsaved content in inactive notes
• onTextAreaChange() method tracks real-time content changes
• Save operation clears unsaved state and updates saved content reference
• Delete/rename operations properly clean up tracking maps

Key Architectural Patterns

• State Management: Uses EventTarget pattern for reactive state updates
• File I/O: Synchronous file operations in Python with proper error handling
• API Design: RESTful endpoints with JSON responses and consistent error handling
• UI Updates: Event-driven architecture prevents manual DOM manipulation
• Extension Integration: Follows ComfyUI's extension patterns (NODE_CLASS_MAPPINGS, registerExtension)
• ComfyUI Integration: Leverages folder_paths module for LoRA discovery and metadata loading

Development Commands

Installation & Setup

• No build process required - extension loads directly in ComfyUI
• Place extension folder in ComfyUI's custom_nodes/ directory
• Restart ComfyUI to load the extension

Testing the Extension

No automated tests defined. Manual testing workflow:

1. Load extension in ComfyUI
2. Verify sidebar tab appears with "Notes" label and book icon
3. Test CRUD operations: create, edit, save, rename, delete notes
4. Verify tab switching and content persistence
5. Test search functionality: enter search terms, verify results highlighting and line navigation
6. Test LoRA integration: verify submenu appears on click with three format options
7. Verify unsaved changes tracking with asterisk (*) indicators

Development Workflow

1. Modify Python code in __init__.py for backend changes
2. Modify JavaScript in js/extension.js for frontend changes
3. Update CSS in js/notes-sidebar.css for styling changes
4. Python changes: Restart ComfyUI completely to reload the extension
5. JavaScript/CSS changes: Browser refresh is sufficient

Common Development Tasks

• Adding new API endpoints: Add route handlers in __init__.py and corresponding methods in js/api/notesApi.js
• Modifying note storage: Update NotesManager class methods in __init__.py
• UI state changes: Modify NotesStore class in js/stores/NotesStore.js
• Append functionality changes: Update js/components/AppendMenu.js and related backend endpoints
• Adding new components: Create new files in js/components/ and import them in extension.js
• Search functionality changes: Modify onSearchChange() and related methods in extension.js
• API changes: Update js/api/notesApi.js static methods and error handling

File Structure

• notes/ - Storage directory for markdown notes (auto-created, actual location determined by ComfyUI user directory)
• js/ - Frontend assets loaded by ComfyUI
  • extension.js - Main extension entry point (~580 lines, includes search functionality)
  • stores/NotesStore.js - State management (~80 lines)
  • components/AppendMenu.js - Append functionality (~170 lines)
  • api/notesApi.js - API service layer (~90 lines)
  • utils/validation.js - Validation utilities (~10 lines)
  • notes-sidebar.css - UI styling (includes search component styles)
• __init__.py - Main extension code
• pyproject.toml - Project metadata

Important Development Considerations

• Filename validation: Use isValidFilename() from js/utils/validation.js to validate user input
• URL encoding: Note names are URL-encoded in API calls for safe handling
• Event-driven architecture: UI updates are triggered by state changes through EventTarget pattern in NotesStore
• Modular architecture: Components are separated by concern (state, UI, API, utilities)
• API centralization: All fetch calls are centralized in js/api/notesApi.js with consistent error handling
• ComfyUI integration: Uses folder_paths.get_filename_list("loras") for LoRA discovery
• Error handling: All API endpoints include try/catch with JSON error responses
• Import structure: ES6 modules with clear dependency relationships