christianandClaude Opus 5
0db5e9b07d
First commit on the local Gitea server, made after moving the tree off the Windows machine. Build outputs, node_modules and the AI models stay out (see .gitignore); everything the installer build needs is tracked. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
330 lines
10 KiB
Markdown
330 lines
10 KiB
Markdown
# Bible App Annotation Tools Documentation
|
|
|
|
## Overview
|
|
|
|
The Bible App features a comprehensive annotation system with multiple tools for marking up Bible passages. This document provides detailed information about all available tools, their features, and usage instructions.
|
|
|
|
## Current Tools
|
|
|
|
### 1. Pen Tool 🖊️
|
|
**Icon:** `fas fa-pen`
|
|
**Purpose:** Freehand drawing and writing on Bible text
|
|
|
|
**Features:**
|
|
- **Colors:** 8 preset colors (White, Red, Blue, Green, Yellow, Magenta, Cyan, Black)
|
|
- **Size Range:** 2-40 pixels
|
|
- **Opacity:** 100% (fully opaque)
|
|
- **Smooth Drawing:** Anti-aliased lines for clean appearance
|
|
- **Color Preview:** Toolbar icon shows current color
|
|
|
|
**Usage:**
|
|
1. Click the pen icon in the toolbar
|
|
2. Select color from dropdown (click pen icon again)
|
|
3. Adjust size using slider (hold pen icon for 350ms)
|
|
4. Draw directly on Bible text
|
|
|
|
**Technical Details:**
|
|
- Uses `source-over` composite operation
|
|
- Line cap: round, Line join: round
|
|
- Hardware accelerated with `translateZ(0)`
|
|
|
|
### 2. Highlighter Tool 🖍️
|
|
**Icon:** `fas fa-highlighter`
|
|
**Purpose:** Semi-transparent highlighting of text
|
|
|
|
**Features:**
|
|
- **Colors:** Same 8 preset colors as pen
|
|
- **Auto-sizing:** Automatically sized to text height (1.3x font size)
|
|
- **Transparency:** 30% opacity by default
|
|
- **Non-destructive:** Overlays text without obscuring it
|
|
- **Color Preview:** Toolbar icon shows current color
|
|
|
|
**Usage:**
|
|
1. Click the highlighter icon in the toolbar
|
|
2. Select color from dropdown
|
|
3. Draw over text to highlight
|
|
4. Automatically adjusts to text size
|
|
|
|
**Technical Details:**
|
|
- Uses `source-over` composite operation
|
|
- Alpha: 0.3 (30% opacity)
|
|
- Size calculated as `Math.max(fontSize * 1.3, 18)`
|
|
|
|
### 3. Eraser Tool 🧽
|
|
**Icon:** `fas fa-eraser`
|
|
**Purpose:** Remove existing annotations
|
|
|
|
**Features:**
|
|
- **Size:** 1.5x current pen size
|
|
- **Complete Removal:** Erases all annotation types
|
|
- **Real-time Feedback:** Immediate visual feedback
|
|
- **Smooth Operation:** Anti-aliased erasing
|
|
|
|
**Usage:**
|
|
1. Click the eraser icon in the toolbar
|
|
2. Draw over annotations to remove them
|
|
3. Works on all annotation types (pen, highlighter, shapes, text)
|
|
|
|
**Technical Details:**
|
|
- Uses `destination-out` composite operation
|
|
- Size: `penSize * 1.5`
|
|
- Alpha: 1.0 (fully opaque)
|
|
|
|
## Tool Management
|
|
|
|
### Undo/Redo System
|
|
**Icons:** `fas fa-undo`, `fas fa-redo`
|
|
**Purpose:** Navigate through annotation history
|
|
|
|
**Features:**
|
|
- **History Limit:** 50 steps per passage
|
|
- **Passage-based:** History tied to specific Bible passages
|
|
- **Cross-tab:** Works across multiple tabs
|
|
- **Automatic Saving:** Saves on drawing completion
|
|
|
|
**Usage:**
|
|
- Click undo button to revert last action
|
|
- Click redo button to restore undone action
|
|
- History persists when switching tabs
|
|
|
|
### Clear All
|
|
**Icon:** `fas fa-trash`
|
|
**Purpose:** Remove all annotations from current passage
|
|
|
|
**Features:**
|
|
- **Complete Reset:** Removes all annotation types
|
|
- **Confirmation:** No confirmation required (for speed)
|
|
- **Passage-specific:** Only clears current passage
|
|
- **Immediate:** Instant clearing
|
|
|
|
## Enhanced Tools (Proposed)
|
|
|
|
### 4. Text Annotation Tool 📝
|
|
**Icon:** `fas fa-font`
|
|
**Purpose:** Add text notes and comments
|
|
|
|
**Features:**
|
|
- **Custom Text:** User-defined text input
|
|
- **Font Options:** Multiple font families
|
|
- **Size Control:** 12-48px range
|
|
- **Color Selection:** Full color picker
|
|
- **Opacity Control:** 10-100% transparency
|
|
|
|
**Implementation Status:** ✅ Ready for development
|
|
|
|
### 5. Rectangle Tool ⬜
|
|
**Icon:** `fas fa-square`
|
|
**Purpose:** Draw rectangular shapes and boxes
|
|
|
|
**Features:**
|
|
- **Fill Options:** Outline or filled rectangles
|
|
- **Size Control:** 1-10px line width
|
|
- **Color Selection:** Full color picker
|
|
- **Opacity Control:** 10-100% transparency
|
|
- **Perfect Squares:** Hold Shift for square shapes
|
|
|
|
**Implementation Status:** ✅ Ready for development
|
|
|
|
### 6. Circle Tool ⭕
|
|
**Icon:** `fas fa-circle`
|
|
**Purpose:** Draw circular shapes and highlights
|
|
|
|
**Features:**
|
|
- **Fill Options:** Outline or filled circles
|
|
- **Size Control:** 1-10px line width
|
|
- **Color Selection:** Full color picker
|
|
- **Opacity Control:** 10-100% transparency
|
|
- **Perfect Circles:** Hold Shift for perfect circles
|
|
|
|
**Implementation Status:** ✅ Ready for development
|
|
|
|
### 7. Arrow Tool ➡️
|
|
**Icon:** `fas fa-arrow-right`
|
|
**Purpose:** Draw arrows for connections and emphasis
|
|
|
|
**Features:**
|
|
- **Arrow Heads:** Automatic arrow head rendering
|
|
- **Size Control:** 1-10px line width
|
|
- **Color Selection:** Full color picker
|
|
- **Opacity Control:** 10-100% transparency
|
|
- **Direction:** Click and drag to set direction
|
|
|
|
**Implementation Status:** ✅ Ready for development
|
|
|
|
## Advanced Features
|
|
|
|
### Advanced Color Picker
|
|
**Purpose:** Enhanced color selection beyond preset colors
|
|
|
|
**Features:**
|
|
- **Custom Colors:** Full RGB color picker
|
|
- **Color Presets:** Quick access to common colors
|
|
- **Opacity Control:** Slider for transparency
|
|
- **Live Preview:** Real-time color preview
|
|
- **Modal Interface:** Centered overlay design
|
|
|
|
**Implementation Status:** ✅ Ready for development
|
|
|
|
### Tool Presets
|
|
**Purpose:** Save and load custom tool configurations
|
|
|
|
**Features:**
|
|
- **Preset Storage:** Save color, size, opacity combinations
|
|
- **Quick Access:** One-click preset switching
|
|
- **Custom Names:** User-defined preset names
|
|
- **Export/Import:** Share presets between users
|
|
|
|
**Implementation Status:** 🔄 Planning phase
|
|
|
|
### Selection Tool
|
|
**Purpose:** Select and modify existing annotations
|
|
|
|
**Features:**
|
|
- **Annotation Selection:** Click to select annotations
|
|
- **Move Annotations:** Drag to reposition
|
|
- **Resize Annotations:** Drag handles to resize
|
|
- **Delete Selected:** Remove selected annotations
|
|
- **Multi-select:** Select multiple annotations
|
|
|
|
**Implementation Status:** 🔄 Planning phase
|
|
|
|
## Touch Support
|
|
|
|
### Gesture Recognition
|
|
**Purpose:** Enhanced touch interaction on mobile devices
|
|
|
|
**Features:**
|
|
- **Two-finger Pinch/Zoom:** 50%-300% zoom range
|
|
- **Two-finger Scroll:** Navigate long passages
|
|
- **Single-finger Drawing:** Standard annotation tools
|
|
- **Gesture Detection:** Automatic gesture recognition
|
|
- **Smooth Animations:** CSS transitions for zoom
|
|
|
|
**Implementation Status:** ✅ Fully implemented
|
|
|
|
### Mobile Optimization
|
|
**Purpose:** Optimized interface for touch devices
|
|
|
|
**Features:**
|
|
- **Touch-friendly Buttons:** Larger touch targets
|
|
- **Responsive Design:** Adapts to screen size
|
|
- **Gesture Support:** Native touch gestures
|
|
- **Performance:** Optimized for mobile rendering
|
|
|
|
**Implementation Status:** ✅ Fully implemented
|
|
|
|
## Technical Architecture
|
|
|
|
### Canvas System
|
|
**Purpose:** Efficient annotation rendering
|
|
|
|
**Components:**
|
|
- **Visible Canvas:** Viewport-sized for real-time drawing
|
|
- **Offscreen Canvas:** Full scrollable area for persistence
|
|
- **Synchronization:** Automatic sync between canvases
|
|
- **Hardware Acceleration:** GPU-accelerated rendering
|
|
|
|
### Storage System
|
|
**Purpose:** Persistent annotation storage
|
|
|
|
**Features:**
|
|
- **Passage-based Keys:** Unique keys per Bible passage
|
|
- **LocalStorage:** Browser-based storage
|
|
- **JSON Format:** Structured data storage
|
|
- **Automatic Saving:** Save on drawing completion
|
|
- **Cross-tab Persistence:** Shared across tabs
|
|
|
|
### Performance Optimization
|
|
**Purpose:** Smooth annotation experience
|
|
|
|
**Techniques:**
|
|
- **RequestAnimationFrame:** Smooth animations
|
|
- **Canvas Scaling:** Efficient zoom handling
|
|
- **Memory Management:** Proper cleanup
|
|
- **Event Optimization:** Efficient event handling
|
|
|
|
## Usage Guidelines
|
|
|
|
### Best Practices
|
|
1. **Use Appropriate Tools:**
|
|
- Pen for detailed notes
|
|
- Highlighter for text emphasis
|
|
- Shapes for visual organization
|
|
- Text for comments
|
|
|
|
2. **Color Coding:**
|
|
- Use consistent colors for similar purposes
|
|
- Red for important passages
|
|
- Blue for cross-references
|
|
- Green for personal insights
|
|
- Yellow for general highlighting
|
|
|
|
3. **Size Selection:**
|
|
- Small sizes (2-8px) for detailed work
|
|
- Medium sizes (8-16px) for general use
|
|
- Large sizes (16-40px) for emphasis
|
|
|
|
### Accessibility
|
|
- **Keyboard Navigation:** All tools accessible via keyboard
|
|
- **Screen Reader Support:** Proper ARIA labels
|
|
- **High Contrast:** Works with high contrast modes
|
|
- **Touch Support:** Full touch device compatibility
|
|
|
|
## Future Enhancements
|
|
|
|
### Planned Features
|
|
1. **Annotation Export:** Export as images or PDF
|
|
2. **Cloud Sync:** Cloud-based annotation storage
|
|
3. **Collaboration:** Share annotations with others
|
|
4. **Voice Notes:** Audio annotation support
|
|
5. **Search Annotations:** Search within annotations
|
|
6. **Annotation Layers:** Multiple annotation layers
|
|
7. **Template System:** Pre-defined annotation templates
|
|
|
|
### Technical Improvements
|
|
1. **WebGL Rendering:** GPU-accelerated drawing
|
|
2. **Vector Graphics:** Scalable annotation format
|
|
3. **Real-time Sync:** Live collaboration features
|
|
4. **Offline Support:** Work without internet
|
|
5. **Performance Monitoring:** Usage analytics
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
1. **Annotations Not Saving:**
|
|
- Check localStorage availability
|
|
- Verify browser storage quota
|
|
- Clear browser cache if needed
|
|
|
|
2. **Performance Issues:**
|
|
- Reduce annotation complexity
|
|
- Close unnecessary tabs
|
|
- Restart browser if needed
|
|
|
|
3. **Touch Gestures Not Working:**
|
|
- Ensure touch device support
|
|
- Check browser compatibility
|
|
- Verify touch events enabled
|
|
|
|
### Debug Information
|
|
Enable debug logging in browser console:
|
|
```javascript
|
|
localStorage.setItem('bible-app-debug', 'true');
|
|
```
|
|
|
|
## File Structure
|
|
```
|
|
bible-app/
|
|
├── app.js # Main application logic
|
|
├── enhanced-tools.js # Enhanced tools module
|
|
├── enhanced-tools.css # Enhanced tools styles
|
|
├── styles.css # Main application styles
|
|
├── test-tools.html # Tool testing interface
|
|
└── TOOLS_DOCUMENTATION.md # This documentation
|
|
```
|
|
|
|
## Conclusion
|
|
|
|
The Bible App annotation system provides a comprehensive set of tools for marking up Bible passages. The current implementation includes basic drawing tools with advanced features like touch support and persistence. Future enhancements will add more sophisticated annotation capabilities while maintaining the app's performance and usability.
|
|
|
|
For questions or feature requests, please refer to the project documentation or create an issue in the project repository. |