621 lines
19 KiB
Markdown
621 lines
19 KiB
Markdown
# Comprehensive Improvement Plan for Twitch Panels Project
|
|
|
|
**Analysis Date**: 2025-02-07
|
|
**Project**: Twitch Panels Creator
|
|
**Tech Stack**: Svelte 5, TypeScript, SvelteKit, Konva, Vitest
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
This plan outlines all necessary improvements for the Twitch Panels project, categorized by priority and impact. The project has a solid foundation with Svelte 5 runes, proper error handling, and good component structure, but critical gaps exist in **image upload functionality** and **test coverage** that must be addressed.
|
|
|
|
**Key Focus Areas**:
|
|
|
|
1. **Complete image loading system** (upload, crop, preview)
|
|
2. **Rewrite and expand test suite** (currently broken/incomplete)
|
|
3. **Architectural refinements** (service layer, state management)
|
|
4. **Code quality** (type safety, error handling, accessibility)
|
|
|
|
---
|
|
|
|
## 🔴 CRITICAL PRIORITY (Must Fix Before Production)
|
|
|
|
### 1. Image Loading System - INCOMPLETE
|
|
|
|
**Current State**:
|
|
|
|
- `ImageManager.svelte` has UI buttons but no functionality
|
|
- `CropInline.svelte` exists but is not integrated
|
|
- `imageConfig.svelte.ts` has hardcoded default image load
|
|
- No actual image upload handlers (drag-drop, paste, URL)
|
|
- Missing image service layer
|
|
|
|
**Required Implementation**:
|
|
|
|
#### 1.1 Create Image Service (`src/services/imageService.ts`)
|
|
|
|
```typescript
|
|
export class ImageService {
|
|
// Upload from file (drag-drop, paste, file input)
|
|
async uploadFromFile(file: File): Promise<ImageResult>;
|
|
|
|
// Upload from URL
|
|
async uploadFromURL(url: string): Promise<ImageResult>;
|
|
|
|
// Validate image (size, format, dimensions)
|
|
validateImage(file: File): ValidationResult;
|
|
|
|
// Process image (resize, compress if needed)
|
|
processImage(image: HTMLImageElement): ProcessedImage;
|
|
|
|
// Set as background
|
|
setBackground(image: ProcessedImage): void;
|
|
|
|
// Reset to default
|
|
resetToDefault(): void;
|
|
}
|
|
```
|
|
|
|
#### 1.2 Implement ImageUpload Component
|
|
|
|
Create `src/components/image/ImageUpload.svelte` with:
|
|
|
|
- Drag-and-drop zone with visual feedback
|
|
- Paste from clipboard (Ctrl+V)
|
|
- URL input field with validation
|
|
- File input fallback
|
|
- Loading states and error messages
|
|
|
|
#### 1.3 Integrate Cropper.js
|
|
|
|
- Create `src/components/image/ImageCropper.svelte` wrapper
|
|
- Integrate with `CropInline.svelte` or replace it
|
|
- Add crop controls (aspect ratio 16:5 for panels)
|
|
- Handle crop completion and update background
|
|
|
|
#### 1.4 Wire Up ImageManager.svelte
|
|
|
|
Add onclick handlers to buttons:
|
|
|
|
- "Загрузить" → Open file picker or show upload options
|
|
- "Редактировать" → Activate crop mode
|
|
- "Сбросить" → Reset to default background
|
|
|
|
#### 1.5 Remove Hardcoded Default
|
|
|
|
- Move default image loading to a proper initialization
|
|
- Make it configurable or lazy-loaded
|
|
- Add fallback if default image fails to load
|
|
|
|
---
|
|
|
|
### 2. Test Suite - BROKEN/INCOMPLETE
|
|
|
|
**Current State**:
|
|
|
|
- `downloadService.test.ts` has **syntax errors** (line 92: `[{ ...id: "test-panel-2" }]`)
|
|
- Tests reference **non-existent methods** (`handleDownload`, `downloadPanels`)
|
|
- Only 2 test files exist (errorHandler.test.ts is good, downloadService is broken)
|
|
- **Zero component tests**
|
|
- **Zero integration tests**
|
|
- Test coverage is effectively 0%
|
|
|
|
**Required Fixes**:
|
|
|
|
#### 2.1 Fix downloadService.test.ts
|
|
|
|
```typescript
|
|
// CURRENT BROKEN CODE (line 92):
|
|
let panels = [{ ...id: "test-panel-2" }]; // Syntax error!
|
|
|
|
// SHOULD BE:
|
|
let panels: DownloadItem[] = [{
|
|
filename: "test-panel-2",
|
|
stage: mockKonvaStage
|
|
}];
|
|
```
|
|
|
|
Remove or fix tests that call non-existent methods:
|
|
|
|
- `handleDownload` → should be `downloadPanel`
|
|
- `downloadPanels` → should be `downloadAll`
|
|
|
|
#### 2.2 Expand Test Coverage
|
|
|
|
**Unit Tests Needed**:
|
|
|
|
- `src/services/downloadService.test.ts` (fix existing)
|
|
- `src/services/imageService.test.ts` (new, after creating service)
|
|
- `src/lib/utils/errorUtils.test.ts` (expand existing)
|
|
- `src/states/*.svelte.ts.test.ts` (all state files)
|
|
- `src/lib/utils/panelStorage.test.ts` (if exists)
|
|
|
|
**Component Tests Needed**:
|
|
|
|
- `src/components/image/ImageManager.test.ts`
|
|
- `src/components/image/ImageUpload.test.ts` (after creation)
|
|
- `src/components/image/ImageCropper.test.ts` (after creation)
|
|
- `src/components/text/TextManager.test.ts`
|
|
- `src/components/text/TextConfig.test.ts`
|
|
- `src/components/panel/PreviewManager.test.ts`
|
|
- `src/components/panel/Preview.svelte.test.ts`
|
|
|
|
**Integration Tests**:
|
|
|
|
- Full user flow: upload image → crop → add texts → preview → download
|
|
- Error scenarios: invalid image, network failure, disk full
|
|
|
|
#### 2.3 Test Quality Standards
|
|
|
|
- **Target Coverage**: 80% overall, 100% for critical paths
|
|
- **Mocking**: Properly mock external dependencies (file-saver, jszip, cropperjs)
|
|
- **Assertions**: Test both success and failure cases
|
|
- **Cleanup**: Ensure proper test isolation
|
|
|
|
---
|
|
|
|
## 🟡 HIGH PRIORITY (Important for Quality)
|
|
|
|
### 3. Architectural Improvements
|
|
|
|
#### 3.1 Service Layer Completion
|
|
|
|
**Problem**: Only `downloadService.ts` exists. Implementation plan references `imageService`, `panelService`, `exportService` that don't exist.
|
|
|
|
**Solution**: Create missing services:
|
|
|
|
- `src/services/imageService.ts` (as described above)
|
|
- `src/services/panelService.ts` - manage panel creation, validation, metadata
|
|
- Consider merging `downloadService` into `exportService` or keep as is
|
|
|
|
**Benefits**:
|
|
|
|
- Clear separation of concerns
|
|
- Easier testing (services can be unit tested)
|
|
- Reusable business logic
|
|
|
|
#### 3.2 State Management Review
|
|
|
|
**Current State**: Multiple state files using Svelte 5 runes - this is good!
|
|
|
|
- `imageConfig.svelte.ts` - image state
|
|
- `textConfig.svelte.ts` - text styling state
|
|
- `texts.svelte.ts` - text list state
|
|
- `konvaStage.svelte.ts` - single stage
|
|
- `konvaAllStages.svelte.ts` - array of stages
|
|
|
|
**Issues**:
|
|
|
|
- `imageConfig.svelte.ts:94` hardcodes default image load - should be in component
|
|
- `textConfig.svelte.ts:35` has bug: `state.fontFamily = this.fontFamily` should be `state.fontFamily = fontFamily`
|
|
- State files mix state creation with side effects
|
|
|
|
**Required Fixes**:
|
|
|
|
1. Fix `textConfig.svelte.ts` setter bug
|
|
2. Remove hardcoded image load from `imageConfig.svelte.ts` - move to component
|
|
3. Consider consolidating related states (e.g., image + crop = imageManagerState)
|
|
4. Add proper cleanup in state destructors if needed
|
|
|
|
#### 3.3 Component Structure Alignment
|
|
|
|
**Problem**: Documentation (`COMPONENT_ORGANIZATION.md`) references components that don't exist:
|
|
|
|
- `ImageUpload.svelte` (doesn't exist, should be created)
|
|
- `ImageCropper.svelte` (doesn't exist, should be created)
|
|
- `PanelPreview.svelte` (exists as `Preview.svelte`)
|
|
- `PanelsList.svelte` (doesn't exist, functionality in `PreviewManager.svelte`)
|
|
|
|
**Solution Options**:
|
|
|
|
- **Option A**: Create missing components to match documentation
|
|
- **Option B**: Update documentation to match reality
|
|
- **Recommended**: Hybrid - create essential missing components (ImageUpload, ImageCropper), update docs to reflect actual structure
|
|
|
|
---
|
|
|
|
### 4. Missing Features & UX Improvements
|
|
|
|
#### 4.1 Panel Persistence
|
|
|
|
**Current State**: No localStorage or persistence. Refresh loses all data.
|
|
|
|
**Required**:
|
|
|
|
- Implement `panelStorage.ts` utility (referenced in docs but missing)
|
|
- Auto-save to localStorage on state changes
|
|
- Load saved panels on app initialization
|
|
- Add "Clear All" button with confirmation
|
|
|
|
#### 4.2 User Feedback System
|
|
|
|
**Missing**:
|
|
|
|
- Loading indicators during image upload/crop
|
|
- Success notifications (toast) after download
|
|
- Error messages displayed to user (currently only console.log)
|
|
- Progress bar for batch downloads
|
|
|
|
**Implementation**:
|
|
|
|
- Create `src/components/feedback/Toast.svelte` or use simple notification
|
|
- Add UI state for loading/error/success
|
|
- Use errorUtils to format user-friendly messages
|
|
|
|
#### 4.3 Accessibility (WCAG 2.1)
|
|
|
|
**Current Gaps**:
|
|
|
|
- No ARIA labels on buttons
|
|
- No keyboard navigation support
|
|
- No screen reader announcements
|
|
- Color contrast may not meet AA standards
|
|
|
|
**Required**:
|
|
|
|
- Add `aria-label` to all icon-only buttons
|
|
- Ensure keyboard navigation works (tab order, focus states)
|
|
- Add `role="alert"` for error messages
|
|
- Test with screen readers
|
|
- Add high contrast mode support if needed
|
|
|
|
#### 4.4 Internationalization
|
|
|
|
**Problem**: Mixed Russian/English in UI and error messages.
|
|
|
|
**Solution**:
|
|
|
|
- Standardize on Russian (current UI language)
|
|
- Or implement i18n system (e.g., svelte-i18n)
|
|
- Ensure all user-facing text is consistent
|
|
- Keep error codes in English for debugging
|
|
|
|
---
|
|
|
|
## 🟢 MEDIUM PRIORITY (Polish & Optimization)
|
|
|
|
### 5. Code Quality & Type Safety
|
|
|
|
#### 5.1 TypeScript Improvements
|
|
|
|
- Add stricter tsconfig settings (`strict: true`, `noImplicitAny: true`)
|
|
- Define proper return types for all functions
|
|
- Use `satisfies` operator for type-safe object literals
|
|
- Add `// @ts-expect-error` only with justification comments
|
|
|
|
#### 5.2 Error Handling Consistency
|
|
|
|
**Current**: Good error type hierarchy exists (`AppError`, `ImageError`, etc.)
|
|
**Issues**:
|
|
|
|
- Not all errors are properly typed
|
|
- Some errors throw strings instead of Error objects
|
|
- Error messages in Russian but codes in English - this is actually good!
|
|
|
|
**Required**:
|
|
|
|
- Audit all `throw` statements - should throw `AppError` subclasses
|
|
- Use `createError` utility consistently
|
|
- Add error context/details where helpful
|
|
|
|
#### 5.3 Code Documentation
|
|
|
|
- Add JSDoc comments to all public functions and classes
|
|
- Document complex logic (especially image processing)
|
|
- Add inline comments for non-obvious code
|
|
- Update README with setup and usage instructions
|
|
|
|
#### 5.4 Component Prop Validation
|
|
|
|
- Add proper prop types with defaults
|
|
- Use `svelte-check` to catch type errors
|
|
- Consider runtime validation for user inputs
|
|
|
|
---
|
|
|
|
### 6. Performance Optimization
|
|
|
|
#### 6.1 Image Optimization
|
|
|
|
- Compress uploaded images (use canvas to resize/compress)
|
|
- Convert to appropriate format (WebP for smaller size)
|
|
- Implement lazy loading for background preview
|
|
- Add image caching strategy
|
|
|
|
#### 6.2 Konva Rendering Optimization
|
|
|
|
- Currently creates new Stage for each panel - this is expensive
|
|
- Consider reusing stages or optimizing layer updates
|
|
- Debounce rapid text changes
|
|
- Use `shouldComponentUpdate` patterns if available
|
|
|
|
#### 6.3 Bundle Size
|
|
|
|
- Check bundle analyzer (vite-bundle-analyzer)
|
|
- Remove unused dependencies
|
|
- Enable code splitting for large libraries (cropperjs, jszip)
|
|
- Consider dynamic imports for non-critical features
|
|
|
|
---
|
|
|
|
### 7. Build & Development Experience
|
|
|
|
#### 7.1 Build Configuration
|
|
|
|
- Add bundle analysis to build script
|
|
- Configure proper source maps for debugging
|
|
- Set up environment variable handling
|
|
- Add build size reporting
|
|
|
|
#### 7.2 Development Tools
|
|
|
|
- Add ESLint with Svelte and TypeScript rules
|
|
- Add Prettier for consistent formatting
|
|
- Configure husky + lint-staged for pre-commit hooks
|
|
- Add commit message linting (conventional commits)
|
|
|
|
#### 7.3 CI/CD (if deploying)
|
|
|
|
- GitHub Actions for test automation
|
|
- Automated build and deployment
|
|
- Coverage reporting to Codecov or similar
|
|
- Dependency vulnerability scanning
|
|
|
|
---
|
|
|
|
## 📋 DETAILED TASK BREAKDOWN
|
|
|
|
### Phase 1: Critical Fixes (Week 1-2)
|
|
|
|
#### Task 1.1: Fix Broken Tests (Day 1)
|
|
|
|
- [ ] Fix syntax error in `downloadService.test.ts:92`
|
|
- [ ] Remove tests for non-existent methods
|
|
- [ ] Run test suite and ensure all pass
|
|
- [ ] Add missing mocks for file-saver, jszip
|
|
|
|
#### Task 1.2: Complete Image Upload UI (Day 2-3)
|
|
|
|
- [ ] Create `ImageUpload.svelte` component
|
|
- [ ] Implement drag-drop, paste, URL input
|
|
- [ ] Add file validation (size, type)
|
|
- [ ] Add loading states
|
|
- [ ] Wire up ImageManager button handlers
|
|
|
|
#### Task 1.3: Implement Image Cropping (Day 4-5)
|
|
|
|
- [ ] Create `ImageCropper.svelte` wrapper for cropperjs
|
|
- [ ] Integrate with CropInline or replace
|
|
- [ ] Add crop aspect ratio constraints (16:5)
|
|
- [ ] Handle crop completion and update state
|
|
- [ ] Add crop cancellation
|
|
|
|
#### Task 1.4: Create Image Service (Day 6-7)
|
|
|
|
- [ ] Implement `imageService.ts` with all methods
|
|
- [ ] Add proper error handling
|
|
- [ ] Write unit tests for imageService
|
|
- [ ] Integrate service with components
|
|
|
|
#### Task 1.5: Remove Hardcoded Default (Day 8)
|
|
|
|
- [ ] Move default image loading to component
|
|
- [ ] Add fallback if default fails
|
|
- [ ] Make default configurable
|
|
|
|
---
|
|
|
|
### Phase 2: Testing Expansion (Week 3)
|
|
|
|
#### Task 2.1: Component Test Infrastructure (Day 1-2)
|
|
|
|
- [ ] Set up `@testing-library/svelte` properly
|
|
- [ ] Create test utilities for component rendering
|
|
- [ ] Write test for `TextManager.svelte`
|
|
- [ ] Write test for `TextConfig.svelte`
|
|
|
|
#### Task 2.2: Image Component Tests (Day 3-4)
|
|
|
|
- [ ] Test `ImageManager.svelte`
|
|
- [ ] Test `ImageUpload.svelte`
|
|
- [ ] Test `ImageCropper.svelte`
|
|
- [ ] Test error scenarios
|
|
|
|
#### Task 2.3: Panel Component Tests (Day 5-6)
|
|
|
|
- [ ] Test `Preview.svelte`
|
|
- [ ] Test `PreviewManager.svelte`
|
|
- [ ] Test download functionality
|
|
- [ ] Test navigation
|
|
|
|
#### Task 2.4: Integration Tests (Day 7-10)
|
|
|
|
- [ ] Set up Playwright or use Testing Library for full flow
|
|
- [ ] Test complete user journey
|
|
- [ ] Test error recovery
|
|
- [ ] Achieve 80% coverage target
|
|
|
|
---
|
|
|
|
### Phase 3: Architecture & Quality (Week 4-5)
|
|
|
|
#### Task 3.1: State Management Cleanup (Day 1-2)
|
|
|
|
- [ ] Fix `textConfig.svelte.ts:35` bug
|
|
- [ ] Review all state files for similar issues
|
|
- [ ] Add proper cleanup where needed
|
|
- [ ] Consider state consolidation
|
|
|
|
#### Task 3.2: Create Missing Services (Day 3-4)
|
|
|
|
- [ ] Create `panelService.ts` for panel management
|
|
- [ ] Refactor panel logic from components to service
|
|
- [ ] Write tests for panelService
|
|
- [ ] Update components to use service
|
|
|
|
#### Task 3.3: Implement Persistence (Day 5-6)
|
|
|
|
- [ ] Create `panelStorage.ts` utility
|
|
- [ ] Implement auto-save on state changes
|
|
- [ ] Load saved state on app init
|
|
- [ ] Add migration logic for schema changes
|
|
- [ ] Write tests for storage
|
|
|
|
#### Task 3.4: User Feedback System (Day 7-8)
|
|
|
|
- [ ] Create Toast notification component
|
|
- [ ] Add loading states to all async operations
|
|
- [ ] Display errors to users (not just console)
|
|
- [ ] Add success confirmations
|
|
|
|
#### Task 3.5: Accessibility (Day 9-10)
|
|
|
|
- [ ] Add ARIA labels to all interactive elements
|
|
- [ ] Implement keyboard navigation
|
|
- [ ] Test with screen readers
|
|
- [ ] Add focus management
|
|
- [ ] Verify color contrast
|
|
|
|
---
|
|
|
|
### Phase 4: Polish & Optimization (Week 6)
|
|
|
|
#### Task 4.1: Code Quality (Day 1-3)
|
|
|
|
- [ ] Enable strict TypeScript mode
|
|
- [ ] Add ESLint + Prettier
|
|
- [ ] Fix all linting errors
|
|
- [ ] Add JSDoc documentation
|
|
- [ ] Update README
|
|
|
|
#### Task 4.2: Performance (Day 4-5)
|
|
|
|
- [ ] Implement image compression
|
|
- [ ] Add lazy loading
|
|
- [ ] Optimize Konva rendering
|
|
- [ ] Analyze and reduce bundle size
|
|
|
|
#### Task 4.3: Final Testing & Bug Fixes (Day 6-7)
|
|
|
|
- [ ] Cross-browser testing
|
|
- [ ] Mobile responsiveness check
|
|
- [ ] Performance profiling
|
|
- [ ] Fix any remaining issues
|
|
|
|
---
|
|
|
|
## 📊 SUCCESS METRICS
|
|
|
|
### Testing
|
|
|
|
- ✅ 80%+ code coverage overall
|
|
- ✅ 100% coverage for critical paths (download, image upload)
|
|
- ✅ All tests passing consistently
|
|
- ✅ No broken or skipped tests
|
|
|
|
### Code Quality
|
|
|
|
- ✅ Zero TypeScript errors in strict mode
|
|
- ✅ Zero ESLint errors (or justified exceptions)
|
|
- ✅ All public APIs documented
|
|
- ✅ Consistent error handling
|
|
|
|
### Functionality
|
|
|
|
- ✅ Image upload works (drag-drop, paste, URL)
|
|
- ✅ Image cropping works with proper constraints
|
|
- ✅ All download functions work (single, batch)
|
|
- ✅ State persists across page refreshes
|
|
- ✅ No memory leaks
|
|
|
|
### User Experience
|
|
|
|
- ✅ Loading states for all async operations
|
|
- ✅ Clear error messages displayed to users
|
|
- ✅ Keyboard navigation works
|
|
- ✅ Screen reader compatible
|
|
- ✅ Responsive design
|
|
|
|
---
|
|
|
|
## 🎯 QUICK WINS (Can Do Immediately)
|
|
|
|
These are small improvements that can be done quickly while working on larger tasks:
|
|
|
|
1. **Fix the obvious test bug** (line 92 in downloadService.test.ts) - 5 minutes
|
|
2. **Add onclick handlers** to ImageManager buttons (even if just console.log for now) - 10 minutes
|
|
3. **Fix textConfig.svelte.ts bug** (line 35) - 2 minutes
|
|
4. **Remove hardcoded default image** from state file - 5 minutes
|
|
5. **Add basic error display** in components (show error state) - 30 minutes
|
|
6. **Add loading spinners** to buttons during async operations - 1 hour
|
|
7. **Add ARIA labels** to all buttons - 1 hour
|
|
8. **Update README** with project description - 30 minutes
|
|
|
|
---
|
|
|
|
## 📚 REFERENCE MATERIAL
|
|
|
|
### Existing Plans (Already Created)
|
|
|
|
- `plans/TECHNICAL_DEBT_ANALYSIS.md` - Good analysis of debt categories
|
|
- `plans/implementation-plan.md` - Original implementation tasks
|
|
- `plans/PROJECT_PLAN.md` - MVP requirements (in Russian)
|
|
- `plans/CRITICAL_ISSUES_REMEDIATION_PLAN.md` - Similar to this plan
|
|
|
|
### This Plan Builds Upon
|
|
|
|
- All existing plans are still valid
|
|
- This plan provides **specific, actionable tasks** with file references
|
|
- Focuses on **immediate critical issues** (image loading, tests)
|
|
- Provides **concrete implementation details**
|
|
|
|
---
|
|
|
|
## 🚀 IMPLEMENTATION ORDER
|
|
|
|
**Recommended Order** (based on dependencies):
|
|
|
|
1. **Fix broken tests** → Establish baseline
|
|
2. **Complete image upload** → Core feature is broken
|
|
3. **Create image service** → Needed for testable architecture
|
|
4. **Expand test coverage** → While implementing features
|
|
5. **Fix state bugs** → Prevents future issues
|
|
6. **Add persistence** → Improves UX significantly
|
|
7. **User feedback system** → Better UX
|
|
8. **Accessibility** → Compliance and usability
|
|
9. **Code quality** → Polish
|
|
10. **Performance** → Final optimization
|
|
|
|
---
|
|
|
|
## ⚠️ RISKS & MITIGATIONS
|
|
|
|
| Risk | Impact | Mitigation |
|
|
| ----------------------- | ------ | ------------------------------------------------------------------------- |
|
|
| Image upload complexity | High | Break into small tasks, use proven libraries (cropperjs already included) |
|
|
| Test time investment | Medium | Prioritize critical path tests first, expand gradually |
|
|
| State management bugs | Medium | Write tests for states before fixing |
|
|
| Accessibility oversight | Medium | Use automated tools (axe) + manual testing |
|
|
| Performance issues | Low | Profile before optimizing, focus on bottlenecks |
|
|
|
|
---
|
|
|
|
## 📝 NOTES
|
|
|
|
- **Svelte 5 runes** are being used correctly - keep this pattern
|
|
- **Error handling** infrastructure is well-designed - reuse it
|
|
- **Component structure** is mostly good - just needs completion
|
|
- **TypeScript** usage is decent - improve with strict mode
|
|
- **Dependencies** are appropriate - no need to change
|
|
|
|
---
|
|
|
|
**Next Steps**:
|
|
|
|
1. Review this plan with the team
|
|
2. Prioritize tasks based on resources
|
|
3. Start with Phase 1, Task 1.1 (fix broken tests)
|
|
4. Create GitHub issues for each task
|
|
5. Track progress against success metrics
|