docs/REVISION_NOTES_PREACT.md

# Revision Notes Preact Overhaul

## Overview

Complete rewrite of the revision notes/annotation system using Preact (no build setup) with modern features and improved UX.

## New Features

### 1. **Image Upload & Reference Panel**
- Drag & drop image upload
- Multiple reference images support
- Image grid with selection
- Upload from file browser

### 2. **Enhanced Toolbar**
- Modern glassmorphism design
- Tool selection: Pen, Marker, Eraser
- Color picker with 6 colors
- Adjustable brush size (1-30)
- Undo functionality
- Clear all with confirmation

### 3. **History Panel**
- Visual history states
- Click to restore any previous state
- Up to 30 states stored

### 4. **Improved Drawing**
- Unified pointer events (mouse, touch, pen)
- Smooth stroke rendering
- Pressure-sensitive stylus support (where available)
- Optimized canvas performance

### 5. **Responsive Design**
- Full-screen modal
- Mobile-friendly touch controls
- Adaptive layout

## File Structure

```
templates/
├── _revision_notes_preact.html    # New Preact-based notes modal
└── question_entry_v2.html          # Updated to use new notes

image_routes.py                     # Added upload endpoint
```

## Routes

### Existing (Unchanged)
- `/save_note_json` - Save annotations
- `/get_note_json/<image_id>` - Load annotations
- `/delete_note` - Delete note
- `/toggle_note_in_pdf` - Include/exclude from PDF

### New
- `/upload_note_reference` - Upload reference images

## Usage

### Opening the Notes Editor

```javascript
openNotesModal(imageId, refImageUrl, sessionId, csrfToken);
```

### Example Button

```html
<button onclick="openNotesModal('{{ image.id }}', '/image/processed/{{ image.processed_filename }}', '{{ session_id }}', '{{ csrf_token() }}')">
    <i class="bi bi-pencil"></i> Edit Notes
</button>
```

## Component Architecture

### Main Components

1. **`NotesEditor`** - Main canvas and toolbar
2. **`ToolButton`** - Reusable tool button
3. **`ColorPicker`** - Color selection
4. **`ReferencePanel`** - Image upload & references
5. **`HistoryPanel`** - Undo history

### State Management

Uses Preact hooks (`useState`, `useEffect`, `useCallback`) for reactive state.

## Technical Details

### Canvas Optimization

```javascript
// Will-read-frequently for better performance
const ctx = canvas.getContext('2d', { willReadFrequently: false });

// Smooth rendering
ctx.lineCap = 'round';
ctx.lineJoin = 'round';
ctx.imageSmoothingEnabled = true;
```

### Pointer Events

Unified handling for all input types:

```javascript
canvas.onpointerdown = handlePointerDown;
canvas.onpointermove = handlePointerMove;
canvas.onpointerup = handlePointerUp;
```

### Tool Modes

| Tool | Behavior | Opacity |
|------|----------|---------|
| Pen | Solid line | 100% |
| Marker | Thick line | 35% |
| Eraser | Large eraser | 100% |

## Migration from Old System

### Old Code
```html
{% include '_revision_notes.html' %}
<script>
window.openNotesModal = function(id, ref) { ... };
</script>
```

### New Code
```html
{% include '_revision_notes_preact.html' %}
<!-- Global functions automatically available -->
```

## Performance Improvements

1. **Faster rendering** - Preact virtual DOM
2. **Optimized canvas** - Reduced redraws
3. **Lazy loading** - Images loaded on demand
4. **Efficient history** - Max 30 states, auto-cleanup

## Browser Support

- Chrome/Edge (recommended)
- Firefox
- Safari
- Mobile browsers (touch-optimized)

## Future Enhancements

- [ ] Text annotations
- [ ] Shape tools (rectangle, circle, arrow)
- [ ] Freehand highlighter
- [ ] Export annotations as PDF
- [ ] Collaborative editing
- [ ] Voice notes
- [ ] OCR from reference images

## Testing

Test the following scenarios:

1. **Basic Drawing**
   - Pen tool with different colors
   - Marker transparency
   - Eraser functionality

2. **Image Upload**
   - Drag & drop
   - File browser
   - Multiple images

3. **History**
   - Undo multiple times
   - Restore old states

4. **Save/Load**
   - Save annotations
   - Reload page
   - Verify persistence

5. **Mobile**
   - Touch drawing
   - Responsive layout
   - Reference panel

## Troubleshooting

### Canvas not drawing
- Check browser console for errors
- Verify Preact loaded from CDN
- Ensure container has dimensions

### Images not uploading
- Check file size limits
- Verify TEMP_FOLDER permissions
- Check CSRF token

### History not working
- Ensure saveState() called after each stroke
- Check history array length

## Credits

Built with:
- [Preact](https://preactjs.com/) - Fast 3KB React alternative
- [HTM](https://github.com/developit/htm) - Hyperscript Tagged Markup
- Bootstrap Icons - Icon library