# 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