mirror of
https://github.com/zadam/trilium.git
synced 2025-12-06 07:24:25 +01:00
docs: add comprehensive development workflow documentation
Copilot Integration: - Streamlined instructions (70% shorter than original) - Task templates for common operations - Three-tier usage strategy (free/strategic/manual) - Optimized for GitHub Copilot Basic tier limits Development Resources: - Common task workflows with time estimates - Feature parity checklist with priorities - Debugging and troubleshooting guides - Testing scenarios and checklists - Code quality standards Workflow Optimization: - Efficient Copilot task budgeting - Real-world implementation examples - Performance and success metrics - Project completion roadmap Reduces repetitive context in prompts. Maximizes limited Copilot task budget.
This commit is contained in:
Octech2722
parent
57c155ea3f
commit
1f444ebc69
176
apps/web-clipper-manifestv3/.github/copilot-instructions.md
vendored
Normal file
176
apps/web-clipper-manifestv3/.github/copilot-instructions.md
vendored
Normal file
@ -0,0 +1,176 @@
|
||||
# GitHub Copilot Instructions - Trilium Web Clipper MV3
|
||||
|
||||
## Project Identity
|
||||
**Working Directory**: `apps/web-clipper-manifestv3/` (active development)
|
||||
**Reference Directory**: `apps/web-clipper/` (MV2 legacy - reference only)
|
||||
**Goal**: Feature-complete MV3 migration with architectural improvements
|
||||
|
||||
## Quick Context Links
|
||||
- Architecture & Systems: See `docs/ARCHITECTURE.md`
|
||||
- Feature Status: See `docs/FEATURE-PARITY-CHECKLIST.md`
|
||||
- Development Patterns: See `docs/DEVELOPMENT-GUIDE.md`
|
||||
- Migration Patterns: See `docs/MIGRATION-PATTERNS.md`
|
||||
|
||||
## Critical Rules
|
||||
|
||||
### Workspace Boundaries
|
||||
- ✅ Work ONLY in `apps/web-clipper-manifestv3/`
|
||||
- ✅ Reference `apps/web-clipper/` for feature understanding
|
||||
- ❌ DO NOT suggest patterns from other monorepo projects
|
||||
- ❌ DO NOT copy MV2 code directly
|
||||
|
||||
### Code Standards (Non-Negotiable)
|
||||
1. **No Emojis in Code**: Never use emojis in `.ts`, `.js`, `.json` files, string literals, or code comments
|
||||
2. **Use Centralized Logging**: `const logger = Logger.create('ComponentName', 'background')`
|
||||
3. **Use Theme System**: Import `theme.css`, use CSS variables `var(--color-*)`, call `ThemeManager.initialize()`
|
||||
4. **TypeScript Everything**: Full type safety, no `any` types
|
||||
5. **Error Handling**: Always wrap async operations in try-catch with proper logging
|
||||
|
||||
### Development Mode
|
||||
- **Current Phase**: Active development (use `npm run dev`)
|
||||
- **Build**: Watch mode with live reload
|
||||
- **Focus**: Debugging, rapid iteration, feature implementation
|
||||
- ⚠️ Only use `npm run build` for final validation
|
||||
|
||||
## Essential Patterns
|
||||
|
||||
### Message Passing Template
|
||||
```typescript
|
||||
// Background service worker
|
||||
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
|
||||
(async () => {
|
||||
try {
|
||||
const result = await handleMessage(message);
|
||||
sendResponse({ success: true, data: result });
|
||||
} catch (error) {
|
||||
logger.error('Handler error', error);
|
||||
sendResponse({ success: false, error: error.message });
|
||||
}
|
||||
})();
|
||||
return true; // Required for async
|
||||
});
|
||||
```
|
||||
|
||||
### Storage Pattern
|
||||
```typescript
|
||||
// Use chrome.storage, NEVER localStorage in service workers
|
||||
await chrome.storage.local.set({ key: value });
|
||||
const { key } = await chrome.storage.local.get(['key']);
|
||||
```
|
||||
|
||||
### Component Structure
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
import { ThemeManager } from '@/shared/theme';
|
||||
|
||||
const logger = Logger.create('ComponentName', 'background');
|
||||
|
||||
async function initialize() {
|
||||
await ThemeManager.initialize();
|
||||
logger.info('Component initialized');
|
||||
}
|
||||
```
|
||||
|
||||
## When Suggesting Code
|
||||
|
||||
### Checklist for Every Response
|
||||
1. [ ] Verify API usage against `reference/chrome_extension_docs/`
|
||||
2. [ ] Include proper error handling with centralized logging
|
||||
3. [ ] Use TypeScript with full type annotations
|
||||
4. [ ] If UI code: integrate theme system
|
||||
5. [ ] Reference legacy code for functionality, not implementation
|
||||
6. [ ] Explain MV2→MV3 changes if applicable
|
||||
|
||||
### Response Format
|
||||
```
|
||||
**Task**: [What we're implementing]
|
||||
**Legacy Pattern** (if migrating): [Brief description]
|
||||
**Modern Approach**: [Show TypeScript implementation]
|
||||
**Files Modified**: [List affected files]
|
||||
**Testing**: [How to verify it works]
|
||||
```
|
||||
|
||||
## Common MV3 Patterns
|
||||
|
||||
### Service Worker Persistence
|
||||
```typescript
|
||||
// State must be stored, not kept in memory
|
||||
const getState = async () => {
|
||||
const { state } = await chrome.storage.local.get(['state']);
|
||||
return state || defaultState;
|
||||
};
|
||||
```
|
||||
|
||||
### Content Script Communication
|
||||
```typescript
|
||||
// Inject scripts programmatically
|
||||
await chrome.scripting.executeScript({
|
||||
target: { tabId },
|
||||
files: ['content.js']
|
||||
});
|
||||
```
|
||||
|
||||
### Manifest V3 APIs
|
||||
- `chrome.action` (not browserAction)
|
||||
- `chrome.storage` (not localStorage)
|
||||
- `chrome.alarms` (not setTimeout in service worker)
|
||||
- `declarativeNetRequest` (not webRequest blocking)
|
||||
|
||||
## Feature Development Workflow
|
||||
|
||||
### Before Starting Work
|
||||
1. Check `docs/FEATURE-PARITY-CHECKLIST.md` for feature status
|
||||
2. Review legacy implementation in `apps/web-clipper/`
|
||||
3. Check if feature needs manifest permissions
|
||||
4. Plan which files will be modified
|
||||
|
||||
### During Development
|
||||
1. Use centralized logging liberally for debugging
|
||||
2. Test frequently with `npm run dev` + Chrome reload
|
||||
3. Check console in both popup and service worker contexts
|
||||
4. Update feature checklist when complete
|
||||
|
||||
### Before Committing
|
||||
1. Run `npm run type-check`
|
||||
2. Test all related functionality
|
||||
3. Verify no console errors
|
||||
4. Update `FEATURE-PARITY-CHECKLIST.md`
|
||||
|
||||
## Current Development Focus
|
||||
|
||||
**Phase**: Screenshot Features (see FEATURE-PARITY-CHECKLIST.md)
|
||||
**Next Priority**: Screenshot cropping implementation
|
||||
**Key Files**:
|
||||
- `src/background/index.ts` (capture handlers)
|
||||
- `src/content/` (selection UI)
|
||||
- `src/shared/` (utilities)
|
||||
|
||||
## What NOT to Include in Suggestions
|
||||
|
||||
❌ Long explanations of basic TypeScript concepts
|
||||
❌ Generic Chrome extension tutorials
|
||||
❌ Detailed history of MV2→MV3 migration
|
||||
❌ Code from other monorepo projects
|
||||
❌ Placeholder/TODO comments without implementation
|
||||
❌ Overly defensive coding for edge cases not in legacy version
|
||||
|
||||
## What TO Focus On
|
||||
|
||||
✅ Concrete, working code that solves the task
|
||||
✅ Feature parity with legacy extension
|
||||
✅ Modern TypeScript patterns
|
||||
✅ Proper error handling and logging
|
||||
✅ Clear migration explanations when relevant
|
||||
✅ Specific file paths and line references
|
||||
✅ Testing instructions
|
||||
|
||||
## Documentation References
|
||||
|
||||
- **Chrome APIs**: `reference/chrome_extension_docs/`
|
||||
- **Readability**: `reference/Mozilla_Readability_docs/`
|
||||
- **DOMPurify**: `reference/cure53_DOMPurify_docs/`
|
||||
- **Cheerio**: `reference/cheerio_docs/`
|
||||
|
||||
---
|
||||
|
||||
**Remember**: This is an active development project in an existing codebase. Be specific, be practical, and focus on getting features working efficiently. When in doubt, check the architecture docs first.
|
||||
377
apps/web-clipper-manifestv3/WORKING-STATUS.md
Normal file
377
apps/web-clipper-manifestv3/WORKING-STATUS.md
Normal file
@ -0,0 +1,377 @@
|
||||
# <20> Trilium Web Clipper MV3 - Working Status
|
||||
|
||||
**Extension Status:** ✅ CORE FUNCTIONALITY WORKING
|
||||
**Last Updated:** October 17, 2025
|
||||
**Build System:** esbuild + IIFE
|
||||
**Target:** Manifest V3 (Chrome/Edge/Brave)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
```bash
|
||||
# Make sure you are in the correct working directory
|
||||
cd apps/web-clipper-manifestv3
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
# Load in Chrome
|
||||
chrome://extensions/ → Load unpacked → Select dist/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Implemented & Working
|
||||
|
||||
### Core Functionality
|
||||
- ✅ **Content script injection** (declarative)
|
||||
- ✅ **Save Selection** to Trilium
|
||||
- ✅ **Save Page** to Trilium (with Readability + DOMPurify + Cheerio pipeline)
|
||||
- ✅ **Save Link** (basic - URL + title only)
|
||||
- ✅ **Save Screenshot** (full page capture, metadata stored)
|
||||
- ✅ **Duplicate note detection** with user choice (new/update/cancel)
|
||||
- ✅ **HTML/Markdown/Both** save formats
|
||||
- ✅ **Context menus** (Save Selection, Save Page, Save Link, Save Screenshot, Save Image)
|
||||
- ✅ **Keyboard shortcuts** (Ctrl+Shift+S for save, Ctrl+Shift+A for screenshot)
|
||||
|
||||
### UI Components
|
||||
- ✅ **Popup UI** with theming (light/dark/auto)
|
||||
- ✅ **Settings page** with Trilium connection config
|
||||
- ✅ **Logs page** with filtering
|
||||
- ✅ **Toast notifications** (basic success/error)
|
||||
- ✅ **Connection status** indicator
|
||||
- ✅ **System theme detection**
|
||||
|
||||
### Build System
|
||||
- ✅ **esbuild** bundling (IIFE format)
|
||||
- ✅ **TypeScript** compilation
|
||||
- ✅ **HTML transformation** (script refs fixed)
|
||||
- ✅ **Asset copying** (CSS, icons, manifest)
|
||||
- ✅ **Type checking** (`npm run type-check`)
|
||||
|
||||
---
|
||||
|
||||
## 🔴 Missing Features (vs MV2)
|
||||
|
||||
### High Priority
|
||||
|
||||
#### 1. **Screenshot Cropping** 🎯 NEXT UP
|
||||
- **MV2:** `cropImage()` function crops screenshot to selected area
|
||||
- **MV3:** Crop rectangle stored in metadata but NOT applied to image
|
||||
- **Impact:** Users get full-page screenshot instead of selected area
|
||||
- **Solution:** Use OffscreenCanvas API or content script canvas
|
||||
- **Files:** `src/background/index.ts:504-560`, need crop implementation
|
||||
|
||||
#### 2. **Image Processing (Full Page)**
|
||||
- **MV2:** Downloads all external images, converts to base64, embeds in note
|
||||
- **MV3:** Only processes images for **selection saves**, not full page
|
||||
- **Impact:** External images in full-page clips may break/disappear
|
||||
- **Solution:** Apply `postProcessImages()` to all capture types
|
||||
- **Files:** `src/background/index.ts:668-740`
|
||||
|
||||
#### 3. **Screenshot Selection UI Verification**
|
||||
- **MV2:** Overlay with drag-to-select, Escape to cancel, visual feedback
|
||||
- **MV3:** Likely exists in content script but needs testing against MV2
|
||||
- **Impact:** Unknown - need to verify feature parity
|
||||
- **Files:** Check `src/content/` against `apps/web-clipper/content.js:66-193`
|
||||
|
||||
### Medium Priority
|
||||
|
||||
#### 4. **Save Tabs (Bulk Save)**
|
||||
- **MV2:** "Save tabs" context menu saves all open tabs as single note with links
|
||||
- **MV3:** Not implemented
|
||||
- **Impact:** Users can't bulk-save research sessions
|
||||
- **Solution:** Add context menu + background handler
|
||||
- **Files:** Reference `apps/web-clipper/background.js:302-326`
|
||||
|
||||
#### 5. **"Already Visited" Popup Detection**
|
||||
- **MV2:** Popup shows if page already clipped, with link to existing note
|
||||
- **MV3:** Background has `checkForExistingNote()` but popup doesn't use it
|
||||
- **Impact:** Users don't know if they've already saved a page
|
||||
- **Solution:** Call `checkForExistingNote()` on popup open, show banner
|
||||
- **Files:** `src/popup/`, reference `apps/web-clipper/popup/popup.js`
|
||||
|
||||
### Low Priority (Quality of Life)
|
||||
|
||||
#### 6. **Link with Custom Note**
|
||||
- **MV2:** Save link with custom text entry (textarea in popup)
|
||||
- **MV3:** Only saves URL + page title
|
||||
- **Impact:** Can't add context/thoughts when saving links
|
||||
- **Solution:** Add textarea to popup for "Save Link" action
|
||||
- **Files:** `src/popup/index.ts`, `src/background/index.ts:562-592`
|
||||
|
||||
#### 7. **Date Metadata Extraction**
|
||||
- **MV2:** Extracts `publishedDate`/`modifiedDate` from meta tags
|
||||
- **MV3:** Not implemented
|
||||
- **Impact:** Lost temporal metadata for articles
|
||||
- **Solution:** Add meta tag parsing to content script
|
||||
- **Files:** Add to content script, reference `apps/web-clipper/content.js:44-65`
|
||||
|
||||
#### 8. **Interactive Toast Notifications**
|
||||
- **MV2:** Toasts have "Open in Trilium" and "Close Tabs" buttons
|
||||
- **MV3:** Basic toasts with text only
|
||||
- **Impact:** Extra step to open saved notes
|
||||
- **Solution:** Add button elements to toast HTML
|
||||
- **Files:** `src/content/toast.ts`, reference `apps/web-clipper/content.js:253-291`
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Partially Implemented
|
||||
|
||||
| Feature | Status | Gap |
|
||||
|---------|--------|-----|
|
||||
| Screenshot capture | ✅ Working | No cropping applied |
|
||||
| Image processing | ⚠️ Selection only | Full page clips missing |
|
||||
| Save link | ✅ Basic | No custom note text |
|
||||
| Toast notifications | ✅ Basic | No interactive buttons |
|
||||
| Duplicate detection | ✅ Working | Not shown in popup proactively |
|
||||
|
||||
---
|
||||
|
||||
## 📋 Feature Comparison Matrix
|
||||
|
||||
| Feature | MV2 | MV3 | Priority |
|
||||
|---------|-----|-----|----------|
|
||||
| **Content Capture** ||||
|
||||
| Save Selection | ✅ | ✅ | - |
|
||||
| Save Full Page | ✅ | ✅ | - |
|
||||
| Save Link | ✅ | ⚠️ Basic | LOW |
|
||||
| Save Screenshot | ✅ | ⚠️ No crop | **HIGH** |
|
||||
| Save Image | ✅ | ✅ | - |
|
||||
| Save Tabs | ✅ | ❌ | MED |
|
||||
| **Content Processing** ||||
|
||||
| Readability extraction | ✅ | ✅ | - |
|
||||
| DOMPurify sanitization | ✅ | ✅ | - |
|
||||
| Cheerio cleanup | ✅ | ✅ | - |
|
||||
| Image downloading | ✅ | ⚠️ Partial | **HIGH** |
|
||||
| Date metadata | ✅ | ❌ | LOW |
|
||||
| Screenshot cropping | ✅ | ❌ | **HIGH** |
|
||||
| **Save Formats** ||||
|
||||
| HTML | ✅ | ✅ | - |
|
||||
| Markdown | ✅ | ✅ | - |
|
||||
| Both (parent/child) | ✅ | ✅ | - |
|
||||
| **UI Features** ||||
|
||||
| Popup | ✅ | ✅ | - |
|
||||
| Settings page | ✅ | ✅ | - |
|
||||
| Logs page | ✅ | ✅ | - |
|
||||
| Context menus | ✅ | ✅ | - |
|
||||
| Keyboard shortcuts | ✅ | ✅ | - |
|
||||
| Toast notifications | ✅ | ⚠️ Basic | LOW |
|
||||
| Already visited banner | ✅ | ❌ | MED |
|
||||
| Screenshot selection UI | ✅ | ❓ Unknown | **HIGH** |
|
||||
| **Connection** ||||
|
||||
| HTTP/HTTPS servers | ✅ | ✅ | - |
|
||||
| Desktop app mode | ✅ | ✅ | - |
|
||||
| Connection testing | ✅ | ✅ | - |
|
||||
| Auto-reconnect | ✅ | ✅ | - |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Current Development Phase
|
||||
|
||||
### Phase 1: Critical Features ✅ COMPLETE
|
||||
- ✅ Build system working
|
||||
- ✅ Content script injection
|
||||
- ✅ Basic save functionality
|
||||
- ✅ Settings & logs UI
|
||||
|
||||
### Phase 2: Screenshot Features 🔄 IN PROGRESS
|
||||
- ⏳ **Task 2.1:** Verify screenshot selection UI
|
||||
- ⏳ **Task 2.2:** Implement screenshot cropping
|
||||
- ⏳ **Task 2.3:** Test crop workflow end-to-end
|
||||
|
||||
### Phase 3: Image Processing (Planned)
|
||||
- ⏸️ Apply image processing to full page captures
|
||||
- ⏸️ Test with various image formats
|
||||
- ⏸️ Handle CORS edge cases
|
||||
|
||||
### Phase 4: Quality of Life (Planned)
|
||||
- ⏸️ Save tabs feature
|
||||
- ⏸️ Already visited detection
|
||||
- ⏸️ Link with custom note
|
||||
- ⏸️ Date metadata extraction
|
||||
- ⏸️ Interactive toasts
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Build System
|
||||
|
||||
**Source:** `src/` (TypeScript)
|
||||
**Output:** `dist/` (IIFE JavaScript)
|
||||
**Config:** `build.mjs`
|
||||
|
||||
### Key Transformations
|
||||
- `.ts` → `.js` (IIFE bundled)
|
||||
- HTML script refs fixed (`.ts` → `.js`)
|
||||
- Paths rewritten for flat structure
|
||||
- CSS + icons copied
|
||||
- manifest.json validated
|
||||
|
||||
### Common Commands
|
||||
```bash
|
||||
# Build for production
|
||||
npm run build
|
||||
|
||||
# Type checking
|
||||
npm run type-check
|
||||
|
||||
# Clean build
|
||||
npm run clean && npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 File Structure
|
||||
|
||||
```
|
||||
dist/
|
||||
├── background.js # Service worker (IIFE)
|
||||
├── content.js # Content script (IIFE)
|
||||
├── popup.js # Popup UI logic (IIFE)
|
||||
├── options.js # Settings page (IIFE)
|
||||
├── logs.js # Logs page (IIFE)
|
||||
├── *.html # HTML files (script refs fixed)
|
||||
├── *.css # Styles (includes theme.css)
|
||||
├── icons/ # Extension icons
|
||||
├── shared/ # Shared assets (theme.css)
|
||||
└── manifest.json # Chrome extension manifest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing Checklist
|
||||
|
||||
### Before Each Build
|
||||
- [ ] `npm run type-check` passes
|
||||
- [ ] `npm run build` completes without errors
|
||||
- [ ] No console errors in background service worker
|
||||
- [ ] No console errors in content script
|
||||
|
||||
### Core Functionality
|
||||
- [ ] Popup displays correctly
|
||||
- [ ] Settings page accessible
|
||||
- [ ] Logs page accessible
|
||||
- [ ] Connection status shows correctly
|
||||
- [ ] Theme switching works (light/dark/auto)
|
||||
|
||||
### Save Operations
|
||||
- [ ] Save Selection works
|
||||
- [ ] Save Page works
|
||||
- [ ] Save Link works
|
||||
- [ ] Save Screenshot works (full page)
|
||||
- [ ] Save Image works
|
||||
- [ ] Context menu items appear
|
||||
- [ ] Keyboard shortcuts work
|
||||
|
||||
### Error Handling
|
||||
- [ ] Invalid Trilium URL shows error
|
||||
- [ ] Network errors handled gracefully
|
||||
- [ ] Restricted URLs (chrome://) blocked properly
|
||||
- [ ] Duplicate note dialog works
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### Immediate (This Session)
|
||||
1. **Verify screenshot selection UI** exists and works
|
||||
2. **Implement screenshot cropping** using OffscreenCanvas
|
||||
3. **Test end-to-end** screenshot workflow
|
||||
|
||||
### Short Term (Next Session)
|
||||
4. Fix image processing for full page captures
|
||||
5. Add "already visited" detection to popup
|
||||
6. Implement "save tabs" feature
|
||||
|
||||
### Long Term
|
||||
7. Add custom note text for links
|
||||
8. Extract date metadata
|
||||
9. Add interactive toast buttons
|
||||
10. Performance optimization
|
||||
11. Cross-browser testing (Firefox, Edge)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- `BUILD-MIGRATION-SUMMARY.md` - Build system details
|
||||
- `reference/dev_notes/TOAST-NOTIFICATION-IMPLEMENTATION.md` - Toast system
|
||||
- `reference/chrome_extension_docs/` - Chrome API docs
|
||||
- `reference/Mozilla_Readability_docs/` - Readability docs
|
||||
- `reference/cure53_DOMPurify_docs/` - DOMPurify docs
|
||||
- `reference/cheerio_docs/` - Cheerio docs
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Known Issues
|
||||
|
||||
1. **Screenshot cropping not applied** - Crop rect stored but image not cropped
|
||||
2. **Images not embedded in full page** - Only works for selections
|
||||
3. **No "already visited" indicator** - Backend exists, UI doesn't use it
|
||||
4. **Screenshot selection UI untested** - Need to verify against MV2
|
||||
|
||||
---
|
||||
|
||||
## 💡 Support
|
||||
|
||||
**Issue:** Extension not loading?
|
||||
**Fix:** Check `chrome://extensions/` errors, rebuild with `npm run build`
|
||||
|
||||
**Issue:** Buttons not working?
|
||||
**Fix:** Open DevTools, check console for errors, verify script paths in HTML
|
||||
|
||||
**Issue:** Missing styles?
|
||||
**Fix:** Check `dist/shared/theme.css` exists after build
|
||||
|
||||
**Issue:** Content script not injecting?
|
||||
**Fix:** Check URL isn't restricted (chrome://, about:, file://)
|
||||
|
||||
**Issue:** Can't connect to Trilium?
|
||||
**Fix:** Verify URL in settings, check CORS headers, test with curl
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Architecture Notes
|
||||
|
||||
### Content Processing Pipeline
|
||||
```
|
||||
Raw HTML
|
||||
↓
|
||||
Phase 1: Readability (article extraction)
|
||||
↓
|
||||
Phase 2: DOMPurify (security sanitization)
|
||||
↓
|
||||
Phase 3: Cheerio (final polish)
|
||||
↓
|
||||
Clean HTML → Trilium
|
||||
```
|
||||
|
||||
### Save Format Options
|
||||
- **HTML:** Human-readable, rich formatting (default)
|
||||
- **Markdown:** AI/LLM-friendly, plain text with structure
|
||||
- **Both:** HTML parent note + Markdown child note
|
||||
|
||||
### Message Flow
|
||||
```
|
||||
Content Script → Background → Trilium Server
|
||||
↑ ↓
|
||||
Toast Storage/State
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
- ✅ DOMPurify sanitization on all HTML
|
||||
- ✅ CSP compliant (no inline scripts/eval)
|
||||
- ✅ Restricted URL blocking
|
||||
- ✅ HTTPS recommended for Trilium connection
|
||||
- ⚠️ Auth token stored in chrome.storage.local (encrypted by browser)
|
||||
|
||||
---
|
||||
|
||||
**Status:** 🟢 Ready for Phase 2 Development
|
||||
**Next Task:** Screenshot Selection UI Verification & Cropping Implementation
|
||||
|
||||
Ready to build! 🚀
|
||||
264
apps/web-clipper-manifestv3/docs/FEATURE-PARITY-CHECKLIST.md
Normal file
264
apps/web-clipper-manifestv3/docs/FEATURE-PARITY-CHECKLIST.md
Normal file
@ -0,0 +1,264 @@
|
||||
# Feature Parity Checklist - MV2 to MV3 Migration
|
||||
|
||||
**Last Updated**: October 18, 2025
|
||||
**Current Phase**: Screenshot Features
|
||||
|
||||
---
|
||||
|
||||
## Status Legend
|
||||
- ✅ **Complete** - Fully implemented and tested
|
||||
- 🚧 **In Progress** - Currently being worked on
|
||||
- ⚠️ **Partial** - Working but missing features
|
||||
- ❌ **Missing** - Not yet implemented
|
||||
- ❓ **Unknown** - Needs verification
|
||||
|
||||
---
|
||||
|
||||
## Core Capture Features
|
||||
|
||||
| Feature | Status | Notes | Priority |
|
||||
|---------|--------|-------|----------|
|
||||
| Save Selection | ✅ | Working with image processing | - |
|
||||
| Save Full Page | ✅ | Readability + DOMPurify + Cheerio | - |
|
||||
| Save Link | ⚠️ | Basic (URL + title only) | LOW |
|
||||
| Save Screenshot | ⚠️ | No cropping applied | **HIGH** |
|
||||
| Save Image | ✅ | Downloads and embeds | - |
|
||||
| Save Tabs (Bulk) | ❌ | Not implemented | MED |
|
||||
|
||||
---
|
||||
|
||||
## Content Processing
|
||||
|
||||
| Feature | Status | Notes | Files |
|
||||
|---------|--------|-------|-------|
|
||||
| Readability extraction | ✅ | Working | `background/index.ts:608-630` |
|
||||
| DOMPurify sanitization | ✅ | Working | `background/index.ts:631-653` |
|
||||
| Cheerio cleanup | ✅ | Working | `background/index.ts:654-666` |
|
||||
| Image downloading | ⚠️ | Selection only | `background/index.ts:668-740` |
|
||||
| Screenshot cropping | ❌ | Rect stored, not applied | `background/index.ts:504-560` |
|
||||
| Date metadata extraction | ❌ | Not implemented | - |
|
||||
|
||||
### Priority Issues:
|
||||
|
||||
#### 1. Screenshot Cropping (HIGH)
|
||||
**Problem**: Full-page screenshot captured, crop rectangle stored in metadata, but crop NOT applied to image.
|
||||
|
||||
**MV2 Implementation**: `apps/web-clipper/background.js:393-427` (cropImage function)
|
||||
|
||||
**What's Needed**:
|
||||
- Implement `cropImage()` function in background
|
||||
- Use OffscreenCanvas API or send to content script
|
||||
- Apply crop before saving to Trilium
|
||||
- Test with various screen sizes
|
||||
|
||||
**Files to Modify**:
|
||||
- `src/background/index.ts` (add crop function)
|
||||
- Possibly `src/content/screenshot.ts` (if canvas needed)
|
||||
|
||||
#### 2. Image Processing for Full Page (HIGH)
|
||||
**Problem**: `postProcessImages()` only runs for selection saves, not full page captures.
|
||||
|
||||
**MV2 Implementation**: `apps/web-clipper/background.js:293-301` (downloads all images)
|
||||
|
||||
**What's Needed**:
|
||||
- Call `postProcessImages()` for all capture types
|
||||
- Handle CORS errors gracefully
|
||||
- Test with various image formats
|
||||
- Consider performance for image-heavy pages
|
||||
|
||||
**Files to Modify**:
|
||||
- `src/background/index.ts:608-630` (processContent function)
|
||||
|
||||
---
|
||||
|
||||
## UI Features
|
||||
|
||||
| Feature | Status | Notes | Priority |
|
||||
|---------|--------|-------|----------|
|
||||
| Popup interface | ✅ | With theme support | - |
|
||||
| Settings page | ✅ | Connection config | - |
|
||||
| Logs viewer | ✅ | Filter/search/export | - |
|
||||
| Context menus | ✅ | All save types | - |
|
||||
| Keyboard shortcuts | ✅ | Save (Ctrl+Shift+S), Screenshot (Ctrl+Shift+A) | - |
|
||||
| Toast notifications | ⚠️ | Basic only | LOW |
|
||||
| Already visited banner | ❌ | Backend exists, UI doesn't use | MED |
|
||||
| Screenshot selection UI | ❓ | Needs verification | **HIGH** |
|
||||
|
||||
### Priority Issues:
|
||||
|
||||
#### 3. Screenshot Selection UI Verification (HIGH)
|
||||
**Problem**: Unknown if MV3 version has feature parity with MV2 overlay UI.
|
||||
|
||||
**MV2 Implementation**: `apps/web-clipper/content.js:66-193`
|
||||
- Drag-to-select with visual overlay
|
||||
- Escape key to cancel
|
||||
- Visual feedback during selection
|
||||
- Crosshair cursor
|
||||
|
||||
**What's Needed**:
|
||||
- Test MV3 screenshot selection workflow
|
||||
- Compare UI/UX with MV2 version
|
||||
- Verify all keyboard shortcuts work
|
||||
- Check visual styling matches
|
||||
|
||||
**Files to Check**:
|
||||
- `src/content/screenshot.ts`
|
||||
- `src/content/index.ts`
|
||||
|
||||
#### 4. Already Visited Detection (MED)
|
||||
**Problem**: Popup doesn't show if page was already clipped.
|
||||
|
||||
**MV2 Implementation**: `apps/web-clipper/popup/popup.js` (checks on open)
|
||||
|
||||
**What's Needed**:
|
||||
- Call `checkForExistingNote()` when popup opens
|
||||
- Show banner with link to existing note
|
||||
- Allow user to still save (update or new note)
|
||||
|
||||
**Files to Modify**:
|
||||
- `src/popup/index.ts`
|
||||
|
||||
---
|
||||
|
||||
## Save Format Options
|
||||
|
||||
| Format | Status | Notes |
|
||||
|--------|--------|-------|
|
||||
| HTML | ✅ | Rich formatting preserved |
|
||||
| Markdown | ✅ | AI/LLM-friendly |
|
||||
| Both (parent/child) | ✅ | HTML parent + MD child |
|
||||
|
||||
---
|
||||
|
||||
## Trilium Integration
|
||||
|
||||
| Feature | Status | Notes |
|
||||
|---------|--------|-------|
|
||||
| HTTP/HTTPS connection | ✅ | Working |
|
||||
| Desktop app mode | ✅ | Working |
|
||||
| Connection testing | ✅ | Working |
|
||||
| Auto-reconnect | ✅ | Working |
|
||||
| Duplicate detection | ✅ | User choice dialog |
|
||||
| Parent note selection | ✅ | Working |
|
||||
| Note attributes | ✅ | Labels and relations |
|
||||
|
||||
---
|
||||
|
||||
## Quality of Life Features
|
||||
|
||||
| Feature | Status | Notes | Priority |
|
||||
|---------|--------|-------|----------|
|
||||
| Link with custom note | ❌ | Only URL + title | LOW |
|
||||
| Date metadata | ❌ | publishedDate, modifiedDate | LOW |
|
||||
| Interactive toasts | ⚠️ | No "Open in Trilium" button | LOW |
|
||||
| Save tabs feature | ❌ | Bulk save all tabs | MED |
|
||||
|
||||
---
|
||||
|
||||
## Current Development Phase
|
||||
|
||||
### Phase 1: Core Functionality ✅ COMPLETE
|
||||
- [x] Build system working
|
||||
- [x] Content script injection
|
||||
- [x] Basic save operations
|
||||
- [x] Settings and logs UI
|
||||
- [x] Theme system
|
||||
- [x] Centralized logging
|
||||
|
||||
### Phase 2: Screenshot Features 🚧 IN PROGRESS
|
||||
- [ ] **Task 2.1**: Verify screenshot selection UI against MV2
|
||||
- [ ] **Task 2.2**: Implement screenshot cropping function
|
||||
- [ ] **Task 2.3**: Test end-to-end screenshot workflow
|
||||
- [ ] **Task 2.4**: Handle edge cases (very large/small crops)
|
||||
|
||||
**Current Task**: Screenshot selection UI verification
|
||||
|
||||
### Phase 3: Image Processing (PLANNED)
|
||||
- [ ] Apply image processing to full page captures
|
||||
- [ ] Test with various image formats (PNG, JPG, WebP, SVG)
|
||||
- [ ] Handle CORS edge cases
|
||||
- [ ] Performance testing with image-heavy pages
|
||||
|
||||
### Phase 4: Quality of Life (PLANNED)
|
||||
- [ ] Implement "save tabs" feature
|
||||
- [ ] Add "already visited" detection to popup
|
||||
- [ ] Add custom note text for links
|
||||
- [ ] Extract date metadata from pages
|
||||
- [ ] Add interactive toast buttons
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Before Each Session
|
||||
- [ ] `npm run type-check` passes
|
||||
- [ ] `npm run dev` running successfully
|
||||
- [ ] No console errors in service worker
|
||||
- [ ] No console errors in content script
|
||||
|
||||
### Feature Testing
|
||||
- [ ] Test on regular article pages
|
||||
- [ ] Test on image-heavy pages
|
||||
- [ ] Test on dynamic/SPA pages
|
||||
- [ ] Test on restricted URLs (chrome://)
|
||||
- [ ] Test with slow network
|
||||
- [ ] Test with Trilium server down
|
||||
|
||||
### Edge Cases
|
||||
- [ ] Very long pages
|
||||
- [ ] Pages with many images
|
||||
- [ ] Pages with embedded media
|
||||
- [ ] Pages with complex layouts
|
||||
- [ ] Mobile-responsive pages
|
||||
|
||||
---
|
||||
|
||||
## Known Issues
|
||||
|
||||
### Critical (Blocking)
|
||||
1. **Screenshot cropping not applied** - Full image saved instead of selection
|
||||
2. **Images not embedded in full page** - Only works for selection saves
|
||||
|
||||
### Important (Should fix)
|
||||
3. **Screenshot selection UI untested** - Need to verify against MV2
|
||||
4. **No "already visited" indicator** - Backend function exists but unused
|
||||
|
||||
### Nice to Have
|
||||
5. **No custom note text for links** - Only saves URL and title
|
||||
6. **No date metadata extraction** - Loses temporal context
|
||||
7. **Basic toast notifications** - No interactive buttons
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Where Features Live
|
||||
|
||||
### Capture Handlers
|
||||
- **Background**: `src/background/index.ts:390-850`
|
||||
- **Content Script**: `src/content/index.ts:1-200`
|
||||
- **Screenshot UI**: `src/content/screenshot.ts`
|
||||
|
||||
### UI Components
|
||||
- **Popup**: `src/popup/`
|
||||
- **Options**: `src/options/`
|
||||
- **Logs**: `src/logs/`
|
||||
|
||||
### Shared Systems
|
||||
- **Logging**: `src/shared/utils.ts`
|
||||
- **Theme**: `src/shared/theme.ts` + `src/shared/theme.css`
|
||||
- **Types**: `src/shared/types.ts`
|
||||
|
||||
---
|
||||
|
||||
## Migration Reference
|
||||
|
||||
When implementing missing features, compare against MV2:
|
||||
|
||||
```
|
||||
apps/web-clipper/
|
||||
├── background.js # Service worker logic
|
||||
├── content.js # Content script logic
|
||||
└── popup/
|
||||
└── popup.js # Popup UI logic
|
||||
```
|
||||
|
||||
**Remember**: Reference for functionality, not implementation. Use modern TypeScript patterns.
|
||||
548
apps/web-clipper-manifestv3/docs/MIGRATION-PATTERNS.md
Normal file
548
apps/web-clipper-manifestv3/docs/MIGRATION-PATTERNS.md
Normal file
@ -0,0 +1,548 @@
|
||||
# MV2 to MV3 Migration Patterns
|
||||
|
||||
Quick reference for common migration scenarios when implementing features from the legacy extension.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: Background Page → Service Worker
|
||||
|
||||
### MV2 (Don't Use)
|
||||
```javascript
|
||||
// Persistent background page with global state
|
||||
let cachedData = {};
|
||||
|
||||
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
|
||||
cachedData[msg.id] = msg.data;
|
||||
sendResponse({success: true});
|
||||
});
|
||||
```
|
||||
|
||||
### MV3 (Use This)
|
||||
```typescript
|
||||
// Stateless service worker with chrome.storage
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('BackgroundHandler', 'background');
|
||||
|
||||
chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
|
||||
(async () => {
|
||||
try {
|
||||
// Store in chrome.storage, not memory
|
||||
await chrome.storage.local.set({ [msg.id]: msg.data });
|
||||
logger.info('Data stored', { id: msg.id });
|
||||
sendResponse({ success: true });
|
||||
} catch (error) {
|
||||
logger.error('Storage failed', error);
|
||||
sendResponse({ success: false, error: error.message });
|
||||
}
|
||||
})();
|
||||
return true; // Required for async sendResponse
|
||||
});
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- No global state (service worker can terminate)
|
||||
- Use `chrome.storage` for persistence
|
||||
- Always return `true` for async handlers
|
||||
- Centralized logging for debugging
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Content Script DOM Manipulation
|
||||
|
||||
### MV2 Pattern
|
||||
```javascript
|
||||
// Simple DOM access
|
||||
const content = document.body.innerHTML;
|
||||
```
|
||||
|
||||
### MV3 Pattern (Same, but with error handling)
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('ContentExtractor', 'content');
|
||||
|
||||
function extractContent(): string {
|
||||
try {
|
||||
if (!document.body) {
|
||||
logger.warn('Document body not available');
|
||||
return '';
|
||||
}
|
||||
|
||||
const content = document.body.innerHTML;
|
||||
logger.debug('Content extracted', { length: content.length });
|
||||
return content;
|
||||
} catch (error) {
|
||||
logger.error('Content extraction failed', error);
|
||||
return '';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- Add null checks for DOM elements
|
||||
- Use centralized logging
|
||||
- Handle errors gracefully
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: Screenshot Capture
|
||||
|
||||
### MV2 Pattern
|
||||
```javascript
|
||||
chrome.tabs.captureVisibleTab(null, {format: 'png'}, (dataUrl) => {
|
||||
// Crop using canvas
|
||||
const canvas = document.createElement('canvas');
|
||||
// ... cropping logic
|
||||
});
|
||||
```
|
||||
|
||||
### MV3 Pattern
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('ScreenshotCapture', 'background');
|
||||
|
||||
async function captureAndCrop(
|
||||
tabId: number,
|
||||
cropRect: { x: number; y: number; width: number; height: number }
|
||||
): Promise<string> {
|
||||
try {
|
||||
// Step 1: Capture full tab
|
||||
const dataUrl = await chrome.tabs.captureVisibleTab(null, {
|
||||
format: 'png'
|
||||
});
|
||||
logger.info('Screenshot captured', { tabId });
|
||||
|
||||
// Step 2: Crop using OffscreenCanvas (MV3 service worker compatible)
|
||||
const response = await fetch(dataUrl);
|
||||
const blob = await response.blob();
|
||||
const bitmap = await createImageBitmap(blob);
|
||||
|
||||
const offscreen = new OffscreenCanvas(cropRect.width, cropRect.height);
|
||||
const ctx = offscreen.getContext('2d');
|
||||
|
||||
if (!ctx) {
|
||||
throw new Error('Could not get canvas context');
|
||||
}
|
||||
|
||||
ctx.drawImage(
|
||||
bitmap,
|
||||
cropRect.x, cropRect.y, cropRect.width, cropRect.height,
|
||||
0, 0, cropRect.width, cropRect.height
|
||||
);
|
||||
|
||||
const croppedBlob = await offscreen.convertToBlob({ type: 'image/png' });
|
||||
const reader = new FileReader();
|
||||
|
||||
return new Promise((resolve, reject) => {
|
||||
reader.onloadend = () => resolve(reader.result as string);
|
||||
reader.onerror = reject;
|
||||
reader.readAsDataURL(croppedBlob);
|
||||
});
|
||||
} catch (error) {
|
||||
logger.error('Screenshot crop failed', error);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- Use `OffscreenCanvas` (available in service workers)
|
||||
- No DOM canvas manipulation in background
|
||||
- Full async/await pattern
|
||||
- Comprehensive error handling
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Image Processing
|
||||
|
||||
### MV2 Pattern
|
||||
```javascript
|
||||
// Download image and convert to base64
|
||||
function processImage(imgSrc) {
|
||||
return new Promise((resolve) => {
|
||||
const xhr = new XMLHttpRequest();
|
||||
xhr.open('GET', imgSrc);
|
||||
xhr.responseType = 'blob';
|
||||
xhr.onload = () => {
|
||||
const reader = new FileReader();
|
||||
reader.onloadend = () => resolve(reader.result);
|
||||
reader.readAsDataURL(xhr.response);
|
||||
};
|
||||
xhr.send();
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### MV3 Pattern
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('ImageProcessor', 'background');
|
||||
|
||||
async function downloadAndEncodeImage(
|
||||
imgSrc: string,
|
||||
baseUrl: string
|
||||
): Promise<string> {
|
||||
try {
|
||||
// Resolve relative URLs
|
||||
const absoluteUrl = new URL(imgSrc, baseUrl).href;
|
||||
logger.debug('Downloading image', { url: absoluteUrl });
|
||||
|
||||
// Use fetch API (modern, async)
|
||||
const response = await fetch(absoluteUrl);
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
|
||||
}
|
||||
|
||||
const blob = await response.blob();
|
||||
|
||||
// Convert to base64
|
||||
return new Promise((resolve, reject) => {
|
||||
const reader = new FileReader();
|
||||
reader.onloadend = () => resolve(reader.result as string);
|
||||
reader.onerror = () => reject(new Error('FileReader failed'));
|
||||
reader.readAsDataURL(blob);
|
||||
});
|
||||
} catch (error) {
|
||||
logger.warn('Image download failed', { url: imgSrc, error });
|
||||
// Return original URL as fallback
|
||||
return imgSrc;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- Use `fetch()` instead of `XMLHttpRequest`
|
||||
- Handle CORS errors gracefully
|
||||
- Return original URL on failure (don't break the note)
|
||||
- Resolve relative URLs properly
|
||||
|
||||
---
|
||||
|
||||
## Pattern 5: Context Menu Creation
|
||||
|
||||
### MV2 Pattern
|
||||
```javascript
|
||||
chrome.contextMenus.create({
|
||||
id: "save-selection",
|
||||
title: "Save to Trilium",
|
||||
contexts: ["selection"]
|
||||
});
|
||||
```
|
||||
|
||||
### MV3 Pattern (Same API, better structure)
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('ContextMenu', 'background');
|
||||
|
||||
interface MenuConfig {
|
||||
id: string;
|
||||
title: string;
|
||||
contexts: chrome.contextMenus.ContextType[];
|
||||
}
|
||||
|
||||
const MENU_ITEMS: MenuConfig[] = [
|
||||
{ id: 'save-selection', title: 'Save Selection to Trilium', contexts: ['selection'] },
|
||||
{ id: 'save-page', title: 'Save Page to Trilium', contexts: ['page'] },
|
||||
{ id: 'save-link', title: 'Save Link to Trilium', contexts: ['link'] },
|
||||
{ id: 'save-image', title: 'Save Image to Trilium', contexts: ['image'] },
|
||||
{ id: 'save-screenshot', title: 'Save Screenshot to Trilium', contexts: ['page'] }
|
||||
];
|
||||
|
||||
async function setupContextMenus(): Promise<void> {
|
||||
try {
|
||||
// Remove existing menus
|
||||
await chrome.contextMenus.removeAll();
|
||||
|
||||
// Create all menu items
|
||||
for (const item of MENU_ITEMS) {
|
||||
await chrome.contextMenus.create(item);
|
||||
logger.debug('Context menu created', { id: item.id });
|
||||
}
|
||||
|
||||
logger.info('Context menus initialized', { count: MENU_ITEMS.length });
|
||||
} catch (error) {
|
||||
logger.error('Context menu setup failed', error);
|
||||
}
|
||||
}
|
||||
|
||||
// Call during service worker initialization
|
||||
chrome.runtime.onInstalled.addListener(() => {
|
||||
setupContextMenus();
|
||||
});
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- Centralized menu configuration
|
||||
- Clear typing with interfaces
|
||||
- Proper error handling
|
||||
- Logging for debugging
|
||||
|
||||
---
|
||||
|
||||
## Pattern 6: Sending Messages from Content to Background
|
||||
|
||||
### MV2 Pattern
|
||||
```javascript
|
||||
chrome.runtime.sendMessage({type: 'SAVE', data: content}, (response) => {
|
||||
console.log('Saved:', response);
|
||||
});
|
||||
```
|
||||
|
||||
### MV3 Pattern
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('ContentScript', 'content');
|
||||
|
||||
interface SaveMessage {
|
||||
type: 'SAVE_SELECTION' | 'SAVE_PAGE' | 'SAVE_LINK';
|
||||
data: {
|
||||
content: string;
|
||||
metadata: {
|
||||
title: string;
|
||||
url: string;
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
interface SaveResponse {
|
||||
success: boolean;
|
||||
noteId?: string;
|
||||
error?: string;
|
||||
}
|
||||
|
||||
async function sendToBackground(message: SaveMessage): Promise<SaveResponse> {
|
||||
return new Promise((resolve, reject) => {
|
||||
chrome.runtime.sendMessage(message, (response: SaveResponse) => {
|
||||
if (chrome.runtime.lastError) {
|
||||
logger.error('Message send failed', chrome.runtime.lastError);
|
||||
reject(new Error(chrome.runtime.lastError.message));
|
||||
return;
|
||||
}
|
||||
|
||||
if (!response.success) {
|
||||
logger.warn('Background operation failed', { error: response.error });
|
||||
reject(new Error(response.error));
|
||||
return;
|
||||
}
|
||||
|
||||
logger.info('Message handled successfully', { noteId: response.noteId });
|
||||
resolve(response);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// Usage
|
||||
try {
|
||||
const result = await sendToBackground({
|
||||
type: 'SAVE_SELECTION',
|
||||
data: {
|
||||
content: selectedHtml,
|
||||
metadata: {
|
||||
title: document.title,
|
||||
url: window.location.href
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
showToast(`Saved to Trilium: ${result.noteId}`);
|
||||
} catch (error) {
|
||||
logger.error('Save failed', error);
|
||||
showToast('Failed to save to Trilium', 'error');
|
||||
}
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- Strong typing for messages and responses
|
||||
- Promise wrapper for callback API
|
||||
- Always check `chrome.runtime.lastError`
|
||||
- Handle errors at both send and response levels
|
||||
|
||||
---
|
||||
|
||||
## Pattern 7: Storage Operations
|
||||
|
||||
### MV2 Pattern
|
||||
```javascript
|
||||
// Mix of localStorage and chrome.storage
|
||||
localStorage.setItem('setting', value);
|
||||
chrome.storage.local.get(['data'], (result) => {
|
||||
console.log(result.data);
|
||||
});
|
||||
```
|
||||
|
||||
### MV3 Pattern
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('StorageManager', 'background');
|
||||
|
||||
// NEVER use localStorage in service workers - it doesn't exist
|
||||
|
||||
interface StorageData {
|
||||
settings: {
|
||||
triliumUrl: string;
|
||||
authToken: string;
|
||||
saveFormat: 'html' | 'markdown' | 'both';
|
||||
};
|
||||
cache: {
|
||||
lastSync: number;
|
||||
noteIds: string[];
|
||||
};
|
||||
}
|
||||
|
||||
async function loadSettings(): Promise<StorageData['settings']> {
|
||||
try {
|
||||
const { settings } = await chrome.storage.local.get(['settings']);
|
||||
logger.debug('Settings loaded', { hasToken: !!settings?.authToken });
|
||||
return settings || getDefaultSettings();
|
||||
} catch (error) {
|
||||
logger.error('Settings load failed', error);
|
||||
return getDefaultSettings();
|
||||
}
|
||||
}
|
||||
|
||||
async function saveSettings(settings: Partial<StorageData['settings']>): Promise<void> {
|
||||
try {
|
||||
const current = await loadSettings();
|
||||
const updated = { ...current, ...settings };
|
||||
await chrome.storage.local.set({ settings: updated });
|
||||
logger.info('Settings saved', { keys: Object.keys(settings) });
|
||||
} catch (error) {
|
||||
logger.error('Settings save failed', error);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function getDefaultSettings(): StorageData['settings'] {
|
||||
return {
|
||||
triliumUrl: '',
|
||||
authToken: '',
|
||||
saveFormat: 'html'
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- NEVER use `localStorage` (not available in service workers)
|
||||
- Use `chrome.storage.local` for all data
|
||||
- Use `chrome.storage.sync` for user preferences (sync across devices)
|
||||
- Full TypeScript typing for stored data
|
||||
- Default values for missing data
|
||||
|
||||
---
|
||||
|
||||
## Pattern 8: Trilium API Communication
|
||||
|
||||
### MV2 Pattern
|
||||
```javascript
|
||||
function saveToTrilium(content, metadata) {
|
||||
const xhr = new XMLHttpRequest();
|
||||
xhr.open('POST', triliumUrl + '/api/notes');
|
||||
xhr.setRequestHeader('Authorization', token);
|
||||
xhr.send(JSON.stringify({content, metadata}));
|
||||
}
|
||||
```
|
||||
|
||||
### MV3 Pattern
|
||||
```typescript
|
||||
import { Logger } from '@/shared/utils';
|
||||
const logger = Logger.create('TriliumAPI', 'background');
|
||||
|
||||
interface TriliumNote {
|
||||
title: string;
|
||||
content: string;
|
||||
type: 'text';
|
||||
mime: 'text/html' | 'text/markdown';
|
||||
parentNoteId?: string;
|
||||
}
|
||||
|
||||
interface TriliumResponse {
|
||||
note: {
|
||||
noteId: string;
|
||||
title: string;
|
||||
};
|
||||
}
|
||||
|
||||
async function createNote(
|
||||
note: TriliumNote,
|
||||
triliumUrl: string,
|
||||
authToken: string
|
||||
): Promise<string> {
|
||||
try {
|
||||
const url = `${triliumUrl}/api/create-note`;
|
||||
|
||||
logger.debug('Creating note in Trilium', {
|
||||
title: note.title,
|
||||
contentLength: note.content.length
|
||||
});
|
||||
|
||||
const response = await fetch(url, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': authToken,
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify(note)
|
||||
});
|
||||
|
||||
if (!response.ok) {
|
||||
const errorText = await response.text();
|
||||
throw new Error(`HTTP ${response.status}: ${errorText}`);
|
||||
}
|
||||
|
||||
const data: TriliumResponse = await response.json();
|
||||
logger.info('Note created successfully', { noteId: data.note.noteId });
|
||||
|
||||
return data.note.noteId;
|
||||
} catch (error) {
|
||||
logger.error('Note creation failed', error);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key Changes:**
|
||||
- Use `fetch()` API (modern, promise-based)
|
||||
- Full TypeScript typing for requests/responses
|
||||
- Comprehensive error handling
|
||||
- Detailed logging for debugging
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: When to Use Each Pattern
|
||||
|
||||
| Task | Pattern | Files Typically Modified |
|
||||
|------|---------|-------------------------|
|
||||
| Add capture feature | Pattern 1, 6, 8 | `background/index.ts`, `content/index.ts` |
|
||||
| Process images | Pattern 4 | `background/index.ts` |
|
||||
| Add context menu | Pattern 5 | `background/index.ts` |
|
||||
| Screenshot with crop | Pattern 3 | `background/index.ts`, possibly `content/screenshot.ts` |
|
||||
| Settings management | Pattern 7 | `options/index.ts`, `background/index.ts` |
|
||||
| Trilium communication | Pattern 8 | `background/index.ts` |
|
||||
|
||||
---
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
1. **Service Worker Termination**
|
||||
- Don't store state in global variables
|
||||
- Use `chrome.storage` or `chrome.alarms`
|
||||
|
||||
2. **Async Message Handlers**
|
||||
- Always return `true` in listener
|
||||
- Always check `chrome.runtime.lastError`
|
||||
|
||||
3. **Canvas in Service Workers**
|
||||
- Use `OffscreenCanvas`, not regular `<canvas>`
|
||||
- No DOM access in background scripts
|
||||
|
||||
4. **CORS Issues**
|
||||
- Handle fetch failures gracefully
|
||||
- Provide fallbacks for external resources
|
||||
|
||||
5. **Type Safety**
|
||||
- Define interfaces for all messages
|
||||
- Type all chrome.storage data structures
|
||||
|
||||
---
|
||||
|
||||
**Usage**: When implementing a feature, find the relevant pattern above and adapt it. Don't copy MV2 code directly—use these proven MV3 patterns instead.
|
||||
@ -0,0 +1,24 @@
|
||||
## For Feature Implementation:
|
||||
Implement [FEATURE_NAME] from FEATURE-PARITY-CHECKLIST.md.
|
||||
|
||||
Legacy reference: apps/web-clipper/[FILE]:[LINES]
|
||||
Target files: src/[FILES]
|
||||
|
||||
Use centralized logging and theme system. Update checklist when done.
|
||||
|
||||
## For Bug Fixes:
|
||||
Fix [ISSUE] in src/[FILE].
|
||||
|
||||
Expected behavior: [DESCRIBE]
|
||||
Current behavior: [DESCRIBE]
|
||||
Error logs: [IF ANY]
|
||||
|
||||
## For Code Understanding:
|
||||
Explain the [FEATURE] implementation in apps/web-clipper/[FILE].
|
||||
|
||||
I need to replicate this in MV3. What's the core logic and data flow?
|
||||
|
||||
## For Architecture Questions:
|
||||
[QUESTION ABOUT SYSTEM DESIGN]
|
||||
|
||||
See docs/ARCHITECTURE.md for context on logging/theme systems.
|
||||
438
apps/web-clipper-manifestv3/reference/copilot_task_templates.md
Normal file
438
apps/web-clipper-manifestv3/reference/copilot_task_templates.md
Normal file
@ -0,0 +1,438 @@
|
||||
# Copilot Task Templates
|
||||
|
||||
Quick copy-paste templates for common Copilot tasks. Fill in the blanks and paste into Copilot Agent mode.
|
||||
|
||||
---
|
||||
|
||||
## Template 1: Implement Feature from Checklist
|
||||
|
||||
```
|
||||
Implement [FEATURE_NAME] from docs/FEATURE-PARITY-CHECKLIST.md.
|
||||
|
||||
**Legacy Reference**: apps/web-clipper/[FILE]:[LINE_RANGE]
|
||||
|
||||
**Target Files**:
|
||||
- src/[FILE_1]
|
||||
- src/[FILE_2]
|
||||
|
||||
**Requirements**:
|
||||
- Use centralized logging (Logger.create)
|
||||
- Use theme system if UI component
|
||||
- Follow patterns from docs/MIGRATION-PATTERNS.md
|
||||
- Handle all errors gracefully
|
||||
|
||||
**Testing**:
|
||||
- Test on [SCENARIO_1]
|
||||
- Test on [SCENARIO_2]
|
||||
- Verify no console errors
|
||||
|
||||
**Update**:
|
||||
- Mark feature complete in docs/FEATURE-PARITY-CHECKLIST.md
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Implement screenshot cropping from docs/FEATURE-PARITY-CHECKLIST.md.
|
||||
|
||||
**Legacy Reference**: apps/web-clipper/background.js:393-427
|
||||
|
||||
**Target Files**:
|
||||
- src/background/index.ts (add cropImage function)
|
||||
- src/background/index.ts (update captureScreenshot handler)
|
||||
|
||||
**Requirements**:
|
||||
- Use OffscreenCanvas API (Pattern 3 from docs/MIGRATION-PATTERNS.md)
|
||||
- Use centralized logging (Logger.create)
|
||||
- Handle edge cases (crop outside bounds, zero-size crop)
|
||||
- Handle all errors gracefully
|
||||
|
||||
**Testing**:
|
||||
- Test small crop (100x100)
|
||||
- Test large crop (full page)
|
||||
- Test edge crops (near borders)
|
||||
- Verify cropped dimensions correct
|
||||
|
||||
**Update**:
|
||||
- Mark screenshot cropping complete in docs/FEATURE-PARITY-CHECKLIST.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 2: Fix Bug
|
||||
|
||||
```
|
||||
Fix [BUG_DESCRIPTION] in src/[FILE].
|
||||
|
||||
**Problem**: [WHAT'S BROKEN]
|
||||
|
||||
**Expected Behavior**: [WHAT SHOULD HAPPEN]
|
||||
|
||||
**Current Behavior**: [WHAT ACTUALLY HAPPENS]
|
||||
|
||||
**Error Logs** (if any):
|
||||
```
|
||||
[PASTE ERROR FROM LOGS]
|
||||
```
|
||||
|
||||
**Root Cause** (if known): [HYPOTHESIS]
|
||||
|
||||
**Solution Approach**: [HOW TO FIX]
|
||||
|
||||
**Testing**:
|
||||
- Reproduce bug before fix
|
||||
- Verify fix resolves issue
|
||||
- Test edge cases
|
||||
- Check for regressions
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Fix image processing not running on full page captures in src/background/index.ts.
|
||||
|
||||
**Problem**: Images not being downloaded and embedded for full-page saves
|
||||
|
||||
**Expected Behavior**: All images should be converted to base64 and embedded in the note
|
||||
|
||||
**Current Behavior**: Only works for selection saves, full page keeps external URLs
|
||||
|
||||
**Root Cause**: postProcessImages() only called in saveSelection handler, not in savePage handler
|
||||
|
||||
**Solution Approach**:
|
||||
1. Call postProcessImages() in processContent function (line ~608)
|
||||
2. Ensure it runs for all capture types
|
||||
3. Handle CORS errors gracefully
|
||||
|
||||
**Testing**:
|
||||
- Save full page with multiple images
|
||||
- Save page with CORS-restricted images
|
||||
- Verify embedded images display in Trilium
|
||||
- Check external images still work as fallback
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 3: Add UI Component
|
||||
|
||||
```
|
||||
Add [COMPONENT_NAME] to [PAGE].
|
||||
|
||||
**Purpose**: [WHAT IT DOES]
|
||||
|
||||
**Visual Design**:
|
||||
- [DESCRIBE LAYOUT]
|
||||
- [LIST UI ELEMENTS]
|
||||
|
||||
**Data Source**: [WHERE DATA COMES FROM]
|
||||
|
||||
**Interactions**:
|
||||
- [USER ACTION 1] → [RESULT]
|
||||
- [USER ACTION 2] → [RESULT]
|
||||
|
||||
**Files to Modify**:
|
||||
- src/[PAGE]/[PAGE].html (markup)
|
||||
- src/[PAGE]/[PAGE].css (styles with theme variables)
|
||||
- src/[PAGE]/index.ts (logic with logging)
|
||||
|
||||
**Requirements**:
|
||||
- Import and use theme.css
|
||||
- Initialize ThemeManager
|
||||
- Use centralized logging
|
||||
- Handle empty/error states
|
||||
|
||||
**Testing**:
|
||||
- Test in light mode
|
||||
- Test in dark mode
|
||||
- Test with no data
|
||||
- Test with error condition
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
Add "Recent Notes" section to popup.
|
||||
|
||||
**Purpose**: Show last 5 saved notes with links to open in Trilium
|
||||
|
||||
**Visual Design**:
|
||||
- Card/panel below main action buttons
|
||||
- Heading "Recently Saved"
|
||||
- List of note titles (clickable links)
|
||||
- If empty, show "No recent notes"
|
||||
|
||||
**Data Source**:
|
||||
- chrome.storage.local.recentNotes array
|
||||
- Populated by background when saving notes
|
||||
|
||||
**Interactions**:
|
||||
- Click note title → Opens note in Trilium (new tab)
|
||||
|
||||
**Files to Modify**:
|
||||
- src/popup/popup.html (add <div> for recent notes)
|
||||
- src/popup/popup.css (styles with theme variables)
|
||||
- src/popup/index.ts (load and display recent notes)
|
||||
- src/background/index.ts (store recent notes on save)
|
||||
|
||||
**Requirements**:
|
||||
- Import and use theme.css with CSS variables
|
||||
- Initialize ThemeManager
|
||||
- Use centralized logging
|
||||
- Handle empty state (no recent notes)
|
||||
- Escape HTML in note titles
|
||||
|
||||
**Testing**:
|
||||
- Test in light mode
|
||||
- Test in dark mode
|
||||
- Test with no recent notes
|
||||
- Test with 1 note, 5 notes, 10+ notes
|
||||
- Test note title with special characters
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 4: Refactor Code
|
||||
|
||||
```
|
||||
Refactor [FUNCTION/MODULE] in src/[FILE].
|
||||
|
||||
**Current Issues**:
|
||||
- [PROBLEM 1]
|
||||
- [PROBLEM 2]
|
||||
|
||||
**Goals**:
|
||||
- [IMPROVEMENT 1]
|
||||
- [IMPROVEMENT 2]
|
||||
|
||||
**Approach**:
|
||||
- [STEP 1]
|
||||
- [STEP 2]
|
||||
|
||||
**Requirements**:
|
||||
- Maintain existing functionality (no behavior changes)
|
||||
- Improve type safety
|
||||
- Add/improve logging
|
||||
- Add error handling if missing
|
||||
|
||||
**Testing**:
|
||||
- Verify all existing functionality still works
|
||||
- Check no regressions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 5: Investigate Issue
|
||||
|
||||
```
|
||||
Investigate [ISSUE_DESCRIPTION].
|
||||
|
||||
**Symptoms**:
|
||||
- [WHAT USER SEES]
|
||||
|
||||
**Context**:
|
||||
- Happens when [SCENARIO]
|
||||
- Doesn't happen when [SCENARIO]
|
||||
|
||||
**What to Check**:
|
||||
1. Review relevant code in [FILE]
|
||||
2. Check logs for errors
|
||||
3. Check storage state
|
||||
4. Compare with MV2 implementation (apps/web-clipper/[FILE])
|
||||
|
||||
**Expected Output**:
|
||||
- Root cause analysis
|
||||
- Proposed solution
|
||||
- Code changes needed (if applicable)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 6: Optimize Performance
|
||||
|
||||
```
|
||||
Optimize performance of [FEATURE] in src/[FILE].
|
||||
|
||||
**Current Performance**: [METRICS]
|
||||
|
||||
**Target Performance**: [GOAL]
|
||||
|
||||
**Bottlenecks** (if known):
|
||||
- [ISSUE 1]
|
||||
- [ISSUE 2]
|
||||
|
||||
**Approach**:
|
||||
- [OPTIMIZATION 1]
|
||||
- [OPTIMIZATION 2]
|
||||
|
||||
**Requirements**:
|
||||
- Measure before/after with performance.now()
|
||||
- Log performance metrics
|
||||
- Don't break existing functionality
|
||||
|
||||
**Testing**:
|
||||
- Test with small dataset
|
||||
- Test with large dataset
|
||||
- Verify functionality unchanged
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template 7: Update Documentation
|
||||
|
||||
```
|
||||
Update [DOCUMENTATION_FILE].
|
||||
|
||||
**Changes Needed**:
|
||||
- [CHANGE 1]
|
||||
- [CHANGE 2]
|
||||
|
||||
**Reason**: [WHY UPDATING]
|
||||
|
||||
**Files**:
|
||||
- docs/[FILE]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Copilot Commands
|
||||
|
||||
### For Understanding Legacy Code
|
||||
```
|
||||
Explain the [FEATURE] implementation in apps/web-clipper/[FILE]:[LINES].
|
||||
|
||||
Focus on:
|
||||
- Core logic and data flow
|
||||
- Key functions and their purpose
|
||||
- Data structures used
|
||||
- Edge cases handled
|
||||
|
||||
I need to replicate this in MV3 with modern patterns.
|
||||
```
|
||||
|
||||
### For Code Review
|
||||
```
|
||||
Review the implementation in src/[FILE].
|
||||
|
||||
Check for:
|
||||
- Proper error handling
|
||||
- Centralized logging usage
|
||||
- Theme system integration (if UI)
|
||||
- Type safety (no 'any' types)
|
||||
- Edge cases handled
|
||||
- Performance concerns
|
||||
|
||||
Suggest improvements if any.
|
||||
```
|
||||
|
||||
### For Pattern Guidance
|
||||
```
|
||||
What's the best MV3 pattern for [TASK]?
|
||||
|
||||
Constraints:
|
||||
- Must work in service worker (no DOM)
|
||||
- Need to handle [EDGE_CASE]
|
||||
- Should follow docs/MIGRATION-PATTERNS.md
|
||||
|
||||
Show example implementation.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Copilot Chat Shortcuts
|
||||
|
||||
### Quick Questions (Use Chat Pane - Free)
|
||||
|
||||
```
|
||||
# Understand code
|
||||
What does this function do?
|
||||
|
||||
# Check compatibility
|
||||
Is this MV3 compatible?
|
||||
|
||||
# Get suggestions
|
||||
How can I improve this?
|
||||
|
||||
# Find examples
|
||||
Show example of [PATTERN]
|
||||
|
||||
# Explain error
|
||||
Why is TypeScript showing this error?
|
||||
```
|
||||
|
||||
### Inline Fixes (Use Ctrl+I - Free)
|
||||
|
||||
```
|
||||
# Fix error
|
||||
Fix this TypeScript error
|
||||
|
||||
# Add types
|
||||
Add proper TypeScript types
|
||||
|
||||
# Improve logging
|
||||
Add centralized logging
|
||||
|
||||
# Format code
|
||||
Format this properly
|
||||
|
||||
# Add comments
|
||||
Add explanatory comment
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Tips
|
||||
|
||||
### When to Use Templates
|
||||
|
||||
1. **Use Template** when:
|
||||
- Implementing planned feature
|
||||
- Bug has clear reproduction steps
|
||||
- Adding designed UI component
|
||||
- Following established pattern
|
||||
|
||||
2. **Ask for Guidance First** when:
|
||||
- Unclear how to approach problem
|
||||
- Need to understand legacy code
|
||||
- Choosing between approaches
|
||||
- Architectural decision needed
|
||||
|
||||
3. **Use Inline Chat** when:
|
||||
- Fixing TypeScript errors
|
||||
- Adding missing imports
|
||||
- Formatting code
|
||||
- Quick refactoring
|
||||
|
||||
### Maximizing Copilot Efficiency
|
||||
|
||||
**Before Using Agent Mode (Task)**:
|
||||
1. Understand the problem clearly
|
||||
2. Review legacy code if migrating
|
||||
3. Check docs/MIGRATION-PATTERNS.md for relevant pattern
|
||||
4. Plan which files need changes
|
||||
5. Fill out template completely
|
||||
|
||||
**During Agent Mode**:
|
||||
1. Let it work uninterrupted
|
||||
2. Review generated code carefully
|
||||
3. Test immediately
|
||||
4. Use inline chat for small fixes
|
||||
|
||||
**After Task**:
|
||||
1. Update feature checklist
|
||||
2. Commit with good message
|
||||
3. Document any decisions
|
||||
|
||||
---
|
||||
|
||||
## Context File Quick Reference
|
||||
|
||||
Point Copilot to these when needed:
|
||||
|
||||
```
|
||||
See docs/ARCHITECTURE.md for system overview
|
||||
See docs/MIGRATION-PATTERNS.md for coding patterns
|
||||
See docs/DEVELOPMENT-GUIDE.md for workflow guidance
|
||||
See docs/FEATURE-PARITY-CHECKLIST.md for current status
|
||||
See apps/web-clipper/[FILE] for MV2 reference
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Well-prepared prompts = better results + fewer task retries = more efficient Copilot usage!
|
||||
2
apps/web-clipper-manifestv3/reference/end_of_session.md
Normal file
2
apps/web-clipper-manifestv3/reference/end_of_session.md
Normal file
@ -0,0 +1,2 @@
|
||||
git add .
|
||||
git commit -m "feat: [FEATURE_NAME] - [BRIEF_DESCRIPTION]"
|
||||
@ -0,0 +1,780 @@
|
||||
# Optimized Copilot Workflow Guide
|
||||
|
||||
Complete guide for efficient development with GitHub Copilot Basic tier.
|
||||
|
||||
---
|
||||
|
||||
## File Structure Overview
|
||||
|
||||
```
|
||||
apps/web-clipper-manifestv3/
|
||||
├── .github/
|
||||
│ └── copilot-instructions.md # Auto-loaded by Copilot (streamlined)
|
||||
├── .vscode/
|
||||
│ └── settings.json # VS Code + Copilot config
|
||||
├── docs/
|
||||
│ ├── ARCHITECTURE.md # One-time reference (systems)
|
||||
│ ├── FEATURE-PARITY-CHECKLIST.md # Working status + TODO
|
||||
│ ├── DEVELOPMENT-GUIDE.md # Common tasks + workflows
|
||||
│ └── MIGRATION-PATTERNS.md # MV2→MV3 code patterns
|
||||
├── COPILOT-TASK-TEMPLATES.md # Quick copy-paste prompts
|
||||
├── src/ # Source code
|
||||
├── reference/ # API documentation
|
||||
└── dist/ # Build output (gitignored)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step-by-Step Setup
|
||||
|
||||
### 1. Reorganize Your Documentation
|
||||
|
||||
```bash
|
||||
cd apps/web-clipper-manifestv3
|
||||
|
||||
# Create directory structure
|
||||
mkdir -p .github docs .vscode
|
||||
|
||||
# Move existing file
|
||||
mv WORKING-STATUS.md docs/FEATURE-PARITY-CHECKLIST.md
|
||||
|
||||
# Create new files from artifacts I provided
|
||||
# (Copy content from the artifacts above)
|
||||
```
|
||||
|
||||
**Files to create**:
|
||||
1. `.github/copilot-instructions.md` - Streamlined instructions
|
||||
2. `docs/ARCHITECTURE.md` - System overview
|
||||
3. `docs/MIGRATION-PATTERNS.md` - Code patterns
|
||||
4. `docs/DEVELOPMENT-GUIDE.md` - Practical workflows
|
||||
5. `COPILOT-TASK-TEMPLATES.md` - Quick prompts
|
||||
6. `.vscode/settings.json` - Editor config
|
||||
|
||||
### 2. Update Your Existing Files
|
||||
|
||||
**Keep but review**:
|
||||
- `BUILD-MIGRATION-SUMMARY.md` - Still useful reference
|
||||
- `reference/` directory - API documentation
|
||||
|
||||
**Archive** (move to `docs/archive/` if needed):
|
||||
- Old verbose documentation
|
||||
- Duplicate information
|
||||
- Outdated notes
|
||||
|
||||
---
|
||||
|
||||
## Three-Tier Copilot Usage Strategy
|
||||
|
||||
### Tier 1: Free Operations (Unlimited)
|
||||
|
||||
**Use For**: Quick fixes, small changes, understanding code
|
||||
|
||||
**Tools**:
|
||||
- **Inline Chat** (Ctrl+I): Fix errors, add types, format
|
||||
- **Chat Pane** (Ctrl+Alt+I): Ask questions, get explanations
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
# Inline Chat (Ctrl+I)
|
||||
"Fix this TypeScript error"
|
||||
"Add proper logging"
|
||||
"Extract this to a function"
|
||||
|
||||
# Chat Pane (Ctrl+Alt+I)
|
||||
"Explain this function"
|
||||
"What's the MV3 equivalent of chrome.webRequest?"
|
||||
"How should I structure this component?"
|
||||
```
|
||||
|
||||
**When to Use**:
|
||||
- Fixing TypeScript errors after implementation
|
||||
- Understanding unfamiliar code
|
||||
- Planning before using Agent mode
|
||||
- Quick refactoring
|
||||
|
||||
### Tier 2: Strategic Agent Mode (Limited - Use Wisely)
|
||||
|
||||
**Use For**: Multi-file changes, feature implementation, complex logic
|
||||
|
||||
**Tool**:
|
||||
- **Copilot Agent** (from chat pane): Cross-file coordination
|
||||
|
||||
**Examples**:
|
||||
```
|
||||
# Copy from COPILOT-TASK-TEMPLATES.md, fill in, paste:
|
||||
|
||||
Implement screenshot cropping from docs/FEATURE-PARITY-CHECKLIST.md.
|
||||
|
||||
Legacy Reference: apps/web-clipper/background.js:393-427
|
||||
Target Files: src/background/index.ts
|
||||
|
||||
Use OffscreenCanvas API (Pattern 3 from docs/MIGRATION-PATTERNS.md).
|
||||
Use centralized logging.
|
||||
Update checklist when done.
|
||||
```
|
||||
|
||||
**When to Use**:
|
||||
- Implementing features from checklist
|
||||
- Complex multi-file refactoring
|
||||
- Bug fixes requiring multiple changes
|
||||
|
||||
**How to Maximize Value**:
|
||||
1. **Prepare thoroughly** using Chat Pane first
|
||||
2. **Use templates** from COPILOT-TASK-TEMPLATES.md
|
||||
3. **Be specific** about files, patterns, requirements
|
||||
4. **Let it run** without interruption
|
||||
5. **Use Inline Chat** for cleanup after
|
||||
|
||||
### Tier 3: Manual Development (When Appropriate)
|
||||
|
||||
**Use For**: Simple changes, learning opportunities, debugging
|
||||
|
||||
**When to Use**:
|
||||
- Adding a single line of code
|
||||
- Fixing obvious typos
|
||||
- Adjusting CSS values
|
||||
- Learning the codebase
|
||||
- Quick experiments
|
||||
|
||||
---
|
||||
|
||||
## Optimal Daily Workflow
|
||||
|
||||
### Session Start (5 minutes)
|
||||
|
||||
```bash
|
||||
# 1. Navigate and start build
|
||||
cd apps/web-clipper-manifestv3
|
||||
npm run dev
|
||||
|
||||
# 2. Open VS Code
|
||||
code .
|
||||
|
||||
# 3. Check current task
|
||||
# Open: docs/FEATURE-PARITY-CHECKLIST.md
|
||||
# Find next priority item
|
||||
```
|
||||
|
||||
### Planning Phase (10-15 minutes - Free)
|
||||
|
||||
**Use Chat Pane** (Ctrl+Alt+I):
|
||||
|
||||
```
|
||||
1. "Looking at feature [X] in docs/FEATURE-PARITY-CHECKLIST.md,
|
||||
what's the implementation approach?"
|
||||
|
||||
2. "Review the MV2 code in apps/web-clipper/[FILE]:[LINES].
|
||||
What's the core logic?"
|
||||
|
||||
3. "What's the best MV3 pattern for this?
|
||||
See docs/MIGRATION-PATTERNS.md for our patterns."
|
||||
|
||||
4. "What files need to be modified?"
|
||||
```
|
||||
|
||||
**Output**: Clear plan before using Agent mode
|
||||
|
||||
### Implementation Phase (Uses 1 Task)
|
||||
|
||||
**Use Agent Mode**:
|
||||
|
||||
1. Open `COPILOT-TASK-TEMPLATES.md`
|
||||
2. Copy appropriate template
|
||||
3. Fill in all blanks
|
||||
4. Paste into Copilot Agent
|
||||
5. Let it work
|
||||
6. Review generated code
|
||||
|
||||
**Example Session**:
|
||||
```
|
||||
# You paste (from template):
|
||||
Implement screenshot cropping from docs/FEATURE-PARITY-CHECKLIST.md.
|
||||
|
||||
Legacy Reference: apps/web-clipper/background.js:393-427
|
||||
Target Files:
|
||||
- src/background/index.ts (add cropImage function)
|
||||
|
||||
Requirements:
|
||||
- Use OffscreenCanvas API (Pattern 3)
|
||||
- Use centralized logging
|
||||
- Handle edge cases
|
||||
|
||||
Testing:
|
||||
- Small crops, large crops, edge crops
|
||||
- Verify dimensions correct
|
||||
|
||||
Update: docs/FEATURE-PARITY-CHECKLIST.md
|
||||
```
|
||||
|
||||
### Cleanup Phase (Free)
|
||||
|
||||
**Use Inline Chat** (Ctrl+I):
|
||||
|
||||
1. Fix any TypeScript errors
|
||||
2. Add missing imports
|
||||
3. Improve logging
|
||||
4. Format code
|
||||
|
||||
```
|
||||
# Select code, press Ctrl+I:
|
||||
"Fix TypeScript errors"
|
||||
"Add better error handling"
|
||||
"Add logging statement"
|
||||
```
|
||||
|
||||
### Testing Phase (Manual)
|
||||
|
||||
```bash
|
||||
# 1. Reload extension in Chrome
|
||||
chrome://extensions/ → Reload button
|
||||
|
||||
# 2. Test functionality
|
||||
# - Happy path
|
||||
# - Error cases
|
||||
# - Edge cases
|
||||
|
||||
# 3. Check logs
|
||||
# - Open extension logs page
|
||||
# - Filter by component
|
||||
# - Verify no errors
|
||||
|
||||
# 4. Check consoles
|
||||
# - Service worker console
|
||||
# - Popup console (if UI)
|
||||
# - Page console (if content script)
|
||||
```
|
||||
|
||||
### Documentation Phase (Manual)
|
||||
|
||||
```bash
|
||||
# 1. Update checklist
|
||||
# Edit: docs/FEATURE-PARITY-CHECKLIST.md
|
||||
# Mark feature as ✅ complete
|
||||
|
||||
# 2. Commit changes
|
||||
git add .
|
||||
git commit -m "feat: implement screenshot cropping"
|
||||
|
||||
# 3. Push (when ready)
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Budgeting Strategy
|
||||
|
||||
**With Copilot Basic**: You have limited Agent mode tasks per month.
|
||||
|
||||
### Prioritize Tasks For:
|
||||
|
||||
**HIGH VALUE (Use Agent Mode)**:
|
||||
1. ✅ Implementing missing features from checklist
|
||||
2. ✅ Complex multi-file refactoring
|
||||
3. ✅ Bug fixes requiring investigation
|
||||
4. ✅ New component creation with UI
|
||||
|
||||
**LOW VALUE (Use Free Tools Instead)**:
|
||||
1. ❌ Fixing simple TypeScript errors → Use Inline Chat
|
||||
2. ❌ Understanding code → Use Chat Pane
|
||||
3. ❌ Small CSS adjustments → Do manually
|
||||
4. ❌ Adding comments → Use Inline Chat
|
||||
5. ❌ Renaming variables → Do manually or use VS Code refactor
|
||||
6. ❌ Formatting code → Use Prettier (Shift+Alt+F)
|
||||
|
||||
### Monthly Task Planning
|
||||
|
||||
**Estimate your tasks per month**: ~20-30 tasks (varies by plan)
|
||||
|
||||
**For this project** (Phase 2 - Screenshot Features):
|
||||
- Task 1: Screenshot cropping implementation
|
||||
- Task 2: Image processing for full page
|
||||
- Task 3: Screenshot selection UI improvements
|
||||
- **Total**: 3 tasks for Phase 2
|
||||
|
||||
**For Phase 3** (Image Processing):
|
||||
- Task 4: Apply image processing to all capture types
|
||||
- Task 5: CORS error handling improvements
|
||||
- **Total**: 2 tasks for Phase 3
|
||||
|
||||
**For Phase 4** (Quality of Life):
|
||||
- Task 6: Save tabs feature
|
||||
- Task 7: Already visited detection
|
||||
- Task 8: Custom note text for links
|
||||
- **Total**: 3 tasks for Phase 4
|
||||
|
||||
**Total for project completion**: ~8-10 Agent mode tasks
|
||||
|
||||
---
|
||||
|
||||
## Real-World Example: Implementing Screenshot Cropping
|
||||
|
||||
Let's walk through a complete feature implementation using the optimized workflow.
|
||||
|
||||
### Phase 1: Planning (Free - Chat Pane)
|
||||
|
||||
**You ask**:
|
||||
```
|
||||
I need to implement screenshot cropping for the extension. The current
|
||||
implementation captures full-page screenshots but doesn't apply the crop
|
||||
rectangle that's stored in metadata.
|
||||
|
||||
MV2 implementation: apps/web-clipper/background.js:393-427
|
||||
|
||||
Questions:
|
||||
1. Can I use regular Canvas in a service worker, or do I need OffscreenCanvas?
|
||||
2. What's the best way to crop the image?
|
||||
3. How should I handle errors?
|
||||
|
||||
See docs/MIGRATION-PATTERNS.md Pattern 3 for reference.
|
||||
```
|
||||
|
||||
**Copilot responds** (paraphrased):
|
||||
```
|
||||
1. Must use OffscreenCanvas - regular Canvas requires DOM
|
||||
2. Best approach:
|
||||
- Convert dataURL to Blob
|
||||
- Create ImageBitmap from Blob
|
||||
- Draw cropped section to OffscreenCanvas
|
||||
- Convert back to dataURL
|
||||
3. Handle errors:
|
||||
- Invalid crop dimensions (width/height <= 0)
|
||||
- Crop outside image bounds
|
||||
- Canvas context creation failure
|
||||
|
||||
Here's the basic structure:
|
||||
[Shows code structure]
|
||||
```
|
||||
|
||||
**Output**: Clear implementation plan, no task used.
|
||||
|
||||
### Phase 2: Implementation (Uses 1 Task)
|
||||
|
||||
**You prepare the prompt** (from template):
|
||||
```
|
||||
Implement screenshot cropping from docs/FEATURE-PARITY-CHECKLIST.md.
|
||||
|
||||
**Legacy Reference**: apps/web-clipper/background.js:393-427
|
||||
|
||||
**Target Files**:
|
||||
- src/background/index.ts (add cropImage function around line 500)
|
||||
- src/background/index.ts (update captureScreenshot handler to call cropImage)
|
||||
|
||||
**Requirements**:
|
||||
- Use OffscreenCanvas API (service worker compatible)
|
||||
- Follow Pattern 3 from docs/MIGRATION-PATTERNS.md
|
||||
- Use centralized logging (Logger.create('ScreenshotCrop', 'background'))
|
||||
- Handle edge cases:
|
||||
- Crop dimensions <= 0 (return error)
|
||||
- Crop outside image bounds (clamp to bounds)
|
||||
- Canvas context creation failure (log and throw)
|
||||
- Return cropped image as base64 dataURL
|
||||
|
||||
**Implementation Details**:
|
||||
1. Create async function `cropImage(dataUrl: string, cropRect: CropRect): Promise<string>`
|
||||
2. Convert dataURL to Blob using fetch
|
||||
3. Create ImageBitmap from Blob
|
||||
4. Create OffscreenCanvas with crop dimensions
|
||||
5. Draw cropped section using drawImage with source/dest rects
|
||||
6. Convert to Blob, then back to dataURL
|
||||
7. Log success with final dimensions
|
||||
|
||||
**Testing**:
|
||||
- Small crop (100x100px)
|
||||
- Large crop (full viewport)
|
||||
- Edge crop (near image borders)
|
||||
- Invalid crop (negative dimensions) - should error
|
||||
- Verify cropped image dimensions match crop rect
|
||||
|
||||
**Update**:
|
||||
- Mark "Screenshot cropping" as ✅ in docs/FEATURE-PARITY-CHECKLIST.md
|
||||
- Add comment about implementation in checklist
|
||||
```
|
||||
|
||||
**Copilot implements**: Multiple files, full feature.
|
||||
|
||||
### Phase 3: Cleanup (Free - Inline Chat)
|
||||
|
||||
**You notice**: Some TypeScript errors, missing null checks.
|
||||
|
||||
**You do** (Ctrl+I on error):
|
||||
```
|
||||
"Fix this TypeScript error"
|
||||
"Add null check for canvas context"
|
||||
"Improve error message"
|
||||
```
|
||||
|
||||
**Result**: Clean, type-safe code.
|
||||
|
||||
### Phase 4: Testing (Manual)
|
||||
|
||||
```bash
|
||||
# Reload extension
|
||||
chrome://extensions/ → Reload
|
||||
|
||||
# Test cases
|
||||
1. Visit any webpage
|
||||
2. Press Ctrl+Shift+A (screenshot shortcut)
|
||||
3. Drag to select small area
|
||||
4. Save to Trilium
|
||||
5. Check image in Trilium - should be cropped
|
||||
|
||||
# Check logs
|
||||
- Open extension Logs page
|
||||
- Search "crop"
|
||||
- Should see "Screenshot cropped" with dimensions
|
||||
- Should see "Screenshot captured" with dimensions
|
||||
- No errors
|
||||
|
||||
# Test edge cases
|
||||
- Try very small crop (10x10)
|
||||
- Try very large crop (full page)
|
||||
- Try crop at page edge
|
||||
```
|
||||
|
||||
### Phase 5: Documentation (Manual)
|
||||
|
||||
```bash
|
||||
# Update checklist
|
||||
# In docs/FEATURE-PARITY-CHECKLIST.md:
|
||||
## Content Processing
|
||||
| Screenshot cropping | ✅ | Using OffscreenCanvas | - |
|
||||
|
||||
# Commit
|
||||
git add docs/FEATURE-PARITY-CHECKLIST.md src/background/index.ts
|
||||
git commit -m "feat: implement screenshot cropping with OffscreenCanvas
|
||||
|
||||
- Add cropImage function using OffscreenCanvas API
|
||||
- Update captureScreenshot handler to apply crop
|
||||
- Handle edge cases (invalid dimensions, out of bounds)
|
||||
- Add comprehensive logging and error handling
|
||||
- Tested with various crop sizes and positions
|
||||
|
||||
Closes #XX (if issue exists)"
|
||||
|
||||
# Push when ready
|
||||
git push origin feature/screenshot-cropping
|
||||
```
|
||||
|
||||
**Total Time**:
|
||||
- Planning: 10 min (free)
|
||||
- Implementation: 5 min (1 task)
|
||||
- Cleanup: 5 min (free)
|
||||
- Testing: 15 min (manual)
|
||||
- Documentation: 5 min (manual)
|
||||
- **Total**: ~40 minutes, 1 task used
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Copilot Issues
|
||||
|
||||
### Issue: Copilot Not Using copilot-instructions.md
|
||||
|
||||
**Check**:
|
||||
1. File must be at `.github/copilot-instructions.md`
|
||||
2. VS Code setting must reference it
|
||||
3. Restart VS Code after creating file
|
||||
|
||||
**Fix**:
|
||||
```json
|
||||
// In .vscode/settings.json
|
||||
{
|
||||
"github.copilot.chat.codeGeneration.instructions": [
|
||||
{
|
||||
"file": ".github/copilot-instructions.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Issue: Copilot Suggests Wrong Patterns
|
||||
|
||||
**Cause**: Instructions too vague or missing context
|
||||
|
||||
**Fix**: Be more specific in prompts
|
||||
```
|
||||
# ❌ Vague
|
||||
"Add screenshot feature"
|
||||
|
||||
# ✅ Specific
|
||||
"Implement screenshot cropping using OffscreenCanvas API.
|
||||
See Pattern 3 in docs/MIGRATION-PATTERNS.md.
|
||||
Target file: src/background/index.ts around line 500."
|
||||
```
|
||||
|
||||
### Issue: Copilot Runs Out of Context
|
||||
|
||||
**Cause**: Trying to process too many files at once
|
||||
|
||||
**Fix**: Break into smaller tasks
|
||||
```
|
||||
# ❌ Too broad
|
||||
"Implement all screenshot features"
|
||||
|
||||
# ✅ Focused
|
||||
"Implement screenshot cropping in src/background/index.ts"
|
||||
[Then in next task]
|
||||
"Add screenshot selection UI improvements in src/content/screenshot.ts"
|
||||
```
|
||||
|
||||
### Issue: Generated Code Doesn't Follow Project Patterns
|
||||
|
||||
**Cause**: Copilot didn't read migration patterns
|
||||
|
||||
**Fix**: Reference specific patterns
|
||||
```
|
||||
"Implement X using Pattern Y from docs/MIGRATION-PATTERNS.md.
|
||||
Use centralized logging (Logger.create).
|
||||
Use theme system for UI."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Tips
|
||||
|
||||
### Tip 1: Pre-Load Context in Chat
|
||||
|
||||
Before using Agent mode, load context in Chat Pane:
|
||||
|
||||
```
|
||||
# In Chat Pane (free):
|
||||
"Review docs/MIGRATION-PATTERNS.md Pattern 3"
|
||||
"Review apps/web-clipper/background.js:393-427"
|
||||
"Review docs/FEATURE-PARITY-CHECKLIST.md screenshot section"
|
||||
|
||||
# Then use Agent mode with:
|
||||
"Now implement screenshot cropping as discussed"
|
||||
```
|
||||
|
||||
**Benefit**: Copilot has context loaded, better results.
|
||||
|
||||
### Tip 2: Use Multi-Turn Conversations
|
||||
|
||||
Instead of one complex prompt, break into conversation:
|
||||
|
||||
```
|
||||
# Turn 1 (Chat Pane):
|
||||
"What's the best way to crop screenshots in MV3 service worker?"
|
||||
|
||||
# Turn 2:
|
||||
"Show me example code using OffscreenCanvas"
|
||||
|
||||
# Turn 3:
|
||||
"Now adapt that for our project structure.
|
||||
Target: src/background/index.ts, use our Logger"
|
||||
|
||||
# Turn 4 (Agent Mode):
|
||||
"Implement this in the project"
|
||||
```
|
||||
|
||||
**Benefit**: Iterative refinement, only uses 1 task at the end.
|
||||
|
||||
### Tip 3: Create Code Snippets for Common Patterns
|
||||
|
||||
In VS Code, create snippets (File → Preferences → User Snippets):
|
||||
|
||||
```json
|
||||
{
|
||||
"Message Handler": {
|
||||
"prefix": "msg-handler",
|
||||
"body": [
|
||||
"chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {",
|
||||
" (async () => {",
|
||||
" try {",
|
||||
" const result = await handle${1:Action}(message);",
|
||||
" sendResponse({ success: true, data: result });",
|
||||
" } catch (error) {",
|
||||
" logger.error('${1:Action} handler error', error);",
|
||||
" sendResponse({ success: false, error: error.message });",
|
||||
" }",
|
||||
" })();",
|
||||
" return true;",
|
||||
"});"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Benefit**: Common patterns without using any Copilot resources.
|
||||
|
||||
### Tip 4: Batch Similar Tasks
|
||||
|
||||
When implementing multiple similar features:
|
||||
|
||||
```
|
||||
# Instead of 3 separate Agent tasks:
|
||||
Task 1: Add "Save Tabs" context menu
|
||||
Task 2: Add "Save Tabs" handler
|
||||
Task 3: Add "Save Tabs" to manifest
|
||||
|
||||
# Do in 1 Agent task:
|
||||
"Implement complete 'Save Tabs' feature:
|
||||
- Add context menu item
|
||||
- Add message handler in background
|
||||
- Update manifest permissions
|
||||
- Add to docs/FEATURE-PARITY-CHECKLIST.md"
|
||||
```
|
||||
|
||||
**Benefit**: 3x fewer tasks used.
|
||||
|
||||
### Tip 5: Use Git Diffs for Review
|
||||
|
||||
Before committing, review with Copilot:
|
||||
|
||||
```
|
||||
# In Chat Pane (free):
|
||||
"Review my changes in src/background/index.ts.
|
||||
Check for:
|
||||
- Proper error handling
|
||||
- Centralized logging
|
||||
- Type safety
|
||||
- Edge cases"
|
||||
```
|
||||
|
||||
**Benefit**: Code review without using a task.
|
||||
|
||||
---
|
||||
|
||||
## Measuring Success
|
||||
|
||||
Track these metrics to optimize your workflow:
|
||||
|
||||
### Time Metrics
|
||||
- **Planning time**: How long to prepare a good prompt
|
||||
- **Implementation time**: How long Copilot takes
|
||||
- **Cleanup time**: How much fixing needed after
|
||||
- **Testing time**: How long to verify functionality
|
||||
|
||||
**Goal**: Minimize cleanup time through better prompts.
|
||||
|
||||
### Quality Metrics
|
||||
- **First-time success rate**: Does implementation work immediately?
|
||||
- **Error count**: How many TypeScript/runtime errors?
|
||||
- **Test pass rate**: Does it work in all test scenarios?
|
||||
|
||||
**Goal**: >80% first-time success rate.
|
||||
|
||||
### Efficiency Metrics
|
||||
- **Tasks used per feature**: How many Agent mode tasks?
|
||||
- **Rework count**: How many times did you need to fix?
|
||||
- **Documentation accuracy**: Are docs up to date?
|
||||
|
||||
**Goal**: <2 tasks per feature on average.
|
||||
|
||||
---
|
||||
|
||||
## Project Completion Roadmap
|
||||
|
||||
Using this workflow, here's your path to completion:
|
||||
|
||||
### Phase 2: Screenshot Features (Current)
|
||||
- [ ] Task 1: Implement screenshot cropping (~40 min, 1 task)
|
||||
- [ ] Task 2: Verify/improve screenshot selection UI (~30 min, 1 task)
|
||||
- [ ] Manual: Update documentation and testing (~20 min)
|
||||
- **Total**: ~90 minutes, 2 tasks
|
||||
|
||||
### Phase 3: Image Processing
|
||||
- [ ] Task 3: Apply image processing to all captures (~45 min, 1 task)
|
||||
- [ ] Manual: Test with various image types (~30 min)
|
||||
- [ ] Manual: Update documentation (~15 min)
|
||||
- **Total**: ~90 minutes, 1 task
|
||||
|
||||
### Phase 4: Quality of Life Features
|
||||
- [ ] Task 4: Implement "Save Tabs" (~40 min, 1 task)
|
||||
- [ ] Task 5: Add "Already Visited" detection (~35 min, 1 task)
|
||||
- [ ] Task 6: Add custom note text for links (~30 min, 1 task)
|
||||
- [ ] Manual: Comprehensive testing (~60 min)
|
||||
- [ ] Manual: Final documentation (~30 min)
|
||||
- **Total**: ~3 hours, 3 tasks
|
||||
|
||||
### Phase 5: Polish & PR
|
||||
- [ ] Manual: Full feature testing (~2 hours)
|
||||
- [ ] Task 7: Final refactoring (if needed) (~30 min, 1 task)
|
||||
- [ ] Manual: Write PR description (~30 min)
|
||||
- [ ] Manual: Address review comments (varies)
|
||||
- **Total**: ~3+ hours, 1 task
|
||||
|
||||
**Grand Total**:
|
||||
- ~7-8 hours of development
|
||||
- ~8 Agent mode tasks
|
||||
- Ready for production PR
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Card
|
||||
|
||||
Print or keep open while developing:
|
||||
|
||||
```
|
||||
╔════════════════════════════════════════════════════╗
|
||||
║ COPILOT WORKFLOW QUICK REFERENCE ║
|
||||
╠════════════════════════════════════════════════════╣
|
||||
║ PLANNING (Free) ║
|
||||
║ • Ctrl+Alt+I → Ask questions ║
|
||||
║ • Review legacy code in chat ║
|
||||
║ • Check docs/MIGRATION-PATTERNS.md ║
|
||||
║ • Plan which files to modify ║
|
||||
╠════════════════════════════════════════════════════╣
|
||||
║ IMPLEMENTING (Uses Task) ║
|
||||
║ • Copy template from COPILOT-TASK-TEMPLATES.md ║
|
||||
║ • Fill in all blanks ║
|
||||
║ • Paste to Agent mode ║
|
||||
║ • Let it work ║
|
||||
╠════════════════════════════════════════════════════╣
|
||||
║ CLEANUP (Free) ║
|
||||
║ • Ctrl+I → Fix TypeScript errors ║
|
||||
║ • Ctrl+I → Add logging/types ║
|
||||
║ • Shift+Alt+F → Format code ║
|
||||
╠════════════════════════════════════════════════════╣
|
||||
║ TESTING (Manual) ║
|
||||
║ • chrome://extensions/ → Reload ║
|
||||
║ • Test happy path + edge cases ║
|
||||
║ • Check Logs page ║
|
||||
║ • Verify consoles (SW, popup, content) ║
|
||||
╠════════════════════════════════════════════════════╣
|
||||
║ DOCUMENTING (Manual) ║
|
||||
║ • Update docs/FEATURE-PARITY-CHECKLIST.md ║
|
||||
║ • git commit -m "feat: description" ║
|
||||
╠════════════════════════════════════════════════════╣
|
||||
║ KEY FILES ║
|
||||
║ • .github/copilot-instructions.md (auto-loaded) ║
|
||||
║ • docs/FEATURE-PARITY-CHECKLIST.md (status) ║
|
||||
║ • docs/MIGRATION-PATTERNS.md (code patterns) ║
|
||||
║ • COPILOT-TASK-TEMPLATES.md (copy-paste) ║
|
||||
╠════════════════════════════════════════════════════╣
|
||||
║ ALWAYS INCLUDE IN PROMPTS ║
|
||||
║ • Target files with line numbers ║
|
||||
║ • Reference to relevant pattern/docs ║
|
||||
║ • "Use centralized logging" ║
|
||||
║ • "Update FEATURE-PARITY-CHECKLIST.md" ║
|
||||
╚════════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Right Now**:
|
||||
- Create the new file structure
|
||||
- Copy content from artifacts to new files
|
||||
- Review and understand the workflow
|
||||
|
||||
2. **Today**:
|
||||
- Implement one small feature using the workflow
|
||||
- Get comfortable with the templates
|
||||
- Measure your time and task usage
|
||||
|
||||
3. **This Week**:
|
||||
- Complete Phase 2 (Screenshot Features)
|
||||
- Refine your prompts based on results
|
||||
- Update templates if needed
|
||||
|
||||
4. **This Month**:
|
||||
- Complete Phases 3-4
|
||||
- Prepare pull request
|
||||
- Document any workflow improvements
|
||||
|
||||
---
|
||||
|
||||
**Remember**: The goal is to work smarter, not harder. Good preparation = better results = fewer tasks used = faster completion!
|
||||
|
||||
Ready to implement! 🚀
|
||||
Loading…
x
Reference in New Issue
Block a user