154 lines
8.6 KiB
Markdown
154 lines
8.6 KiB
Markdown
# 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 |