# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ReadMD is a Chrome extension that extracts webpage content and exports it as Markdown files. Built with React, TypeScript, and Vite using Chrome Extension Manifest V3.

## Commands

```bash
# Install dependencies
npm install

# Development server (with HMR)
npm run dev

# Build extension for production
npm run build

# The dist/ folder is loaded in Chrome via chrome://extensions/
```

## Architecture

### Chrome Extension Components

- **Content Script** (`src/content/index.ts`): Injected into web pages to extract content
  - Uses `@mozilla/readability` to parse page content (runs on cloned DOM to avoid modifying original page)
  - Uses `turndown` to convert HTML to Markdown
  - Handles messages from popup via `chrome.runtime.onMessage`
  - Injects highlight styles dynamically (not via CSS import) to avoid affecting page styles

- **Popup** (`src/popup/Popup.tsx`): Extension's main UI
  - Triggers content extraction via `chrome.tabs.sendMessage`
  - Shows preview, copy to clipboard, download options
  - Auto-closes after copy/download operations

- **Background Service Worker** (`src/background/index.ts`): Handles extension events

### Content Script Communication

```typescript
// Popup sends message to content script
chrome.tabs.sendMessage(tabId, { action: 'extract' | 'extractSelection' | 'preview' | 'cleanup' })

// Content script responds
chrome.runtime.sendMessage({ success: true, data: ExtractedContent })
```

### Key Types (`src/types/index.ts`)

- `ExtractedContent`: Contains title, url, content (HTML), markdown, excerpt
- `ChromeMessage`: Actions: extract, extractSelection, preview, cleanup, copy, download
- `ContentScriptResponse`: Response structure from content script

### Important Implementation Details

1. **DOM Preservation**: Always use `document.cloneNode(true)` before passing to Readability - Readability's `parse()` modifies the DOM directly, so operating on a clone prevents page modification.

2. **Style Isolation**: Content script styles are injected via JavaScript (`document.createElement('style')`) not imported CSS files. Always call `cleanupHighlightStyles()` after extraction.

3. **Extension Loading**: Uses crxjs/vite-plugin which handles manifest generation. Content script uses loader pattern - `assets/index.ts-loader-*.js` loads the actual content script dynamically.