trilium/apps/web-clipper-manifestv3/.github/copilot-instructions.md

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

// 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

// 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

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

// 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

// 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

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.