npm install          # Install dependencies
npm run build        # Build the extension

npm run dev          # Start Vite dev server with HMR
npm run lint         # Run ESLint
npm run typecheck    # TypeScript type checking

┌─────────────────────────────────────────────────────────────────────┐
│                        Chrome Browser                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │  Web Page 1  │  │  Web Page 2  │  │  Web Page 3  │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘              │
│         │                 │                 │                       │
│         └─────────────────┴─────────────────┘                       │
│                      │                                               │
│                      ▼ (content extraction)                         │
│         ┌────────────────────────────┐                              │
│         │  Content Script (Turndown) │                              │
│         │   - HTML → Markdown        │                              │
│         │   - Message-based API      │                              │
│         └────────────┬───────────────┘                              │
│                      │                                               │
│                      ▼ (chrome.runtime.sendMessage)                 │
│  ┌──────────────────────────────────────────────┐                  │
│  │   Background Service Worker                  │                  │
│  │   - Message routing                          │                  │
│  │   - Context menu management                  │                  │
│  │   - Content extraction coordination          │                  │
│  └──────────────────┬───────────────────────────┘                  │
│                     │                                                │
│                     ▼ (message passing)                             │
│  ┌──────────────────────────────────────────────┐                  │
│  │   Side Panel UI                              │                  │
│  │   - Notebook management                      │                  │
│  │   - Source management                        │                  │
│  │   - Chat interface with streaming            │                  │
│  │   - Transformations                          │                  │
│  │   - Settings (API keys, AI providers)        │                  │
│  │                                              │                  │
│  │  ┌──────────────────────────────────────┐   │                  │
│  │  │ Sandboxed Iframe                     │   │                  │
│  │  │ - Renders AI-generated content       │   │                  │
│  │  │ - Defense-in-depth security          │   │                  │
│  │  └──────────────────────────────────────┘   │                  │
│  └──────────────────┬───────────────────────────┘                  │
│                     │                                                │
│                     ▼ (IndexedDB)                                   │
│  ┌──────────────────────────────────────────────┐                  │
│  │   Storage Layer                              │                  │
│  │   - Notebooks & Sources                      │                  │
│  │   - Chat history                             │                  │
│  │   - AI settings & API keys                   │                  │
│  │   - Response cache                           │                  │
│  └──────────────────────────────────────────────┘                  │
│                                                                      │
│                     ▼ (HTTPS)                                       │
│         ┌─────────────────────────────┐                             │
│         │  AI Providers (16+)         │                             │
│         │  - Anthropic, OpenAI        │                             │
│         │  - Google, OpenRouter       │                             │
│         │  - Groq, Mistral, and more  │                             │
│         │  - Chrome Built-in AI       │                             │
│         └─────────────────────────────┘                             │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

src/
├── background/          # Background service worker
│   └── index.ts         # Message handling, context menus, extraction coordination
├── content/             # Content script
│   └── index.ts         # HTML→Markdown extraction using Turndown
├── lib/                 # Shared utilities
│   ├── ai.ts            # AI provider abstraction (Vercel AI SDK)
│   ├── credentials.ts   # Named API key management
│   ├── db.ts            # IndexedDB schema and helpers (v3)
│   ├── markdown-renderer.ts  # Markdown to HTML conversion
│   ├── model-configs.ts # Model configuration management
│   ├── permissions.ts   # Chrome permissions management
│   ├── provider-registry.ts  # Centralized provider configuration with pricing
│   ├── sandbox-renderer.ts   # Secure iframe rendering
│   ├── settings.ts      # AI settings persistence
│   ├── storage.ts       # Storage adapter implementation
│   ├── transform-config.ts   # Transform config storage and UI metadata
│   ├── transforms/      # 19 transformation generation functions
│   │   └── *.ts         # podcast-script.ts, quiz.ts, etc.
│   └── usage.ts         # Usage tracking and cost calculation
├── sandbox/             # Sandboxed iframe for AI content
│   ├── sandbox.html             # In-panel sandbox (embedded in side panel)
│   ├── sandbox.ts
│   ├── fullscreen-wrapper.html  # Bridge page for fullscreen (NOT sandboxed)
│   ├── fullscreen-wrapper.ts    # BroadcastChannel to postMessage bridge
│   ├── fullscreen-sandbox.html  # Fullscreen sandbox (embedded in wrapper)
│   └── fullscreen-sandbox.ts
├── sidepanel/           # Main UI (Preact components)
│   ├── index.html
│   ├── main.tsx         # Preact render entry point
│   ├── App.tsx          # Root component
│   ├── index.ts         # Re-exports hooks and services
│   ├── hooks/           # Custom Preact hooks for state management
│   │   ├── index.ts     # Hooks barrel export
│   │   ├── useNavigation.ts    # Tab navigation state
│   │   ├── useNotification.ts  # Toast notifications
│   │   ├── useDialog.ts        # Modal dialogs (confirm, notebook)
│   │   ├── useNotebook.ts      # Notebook CRUD operations
│   │   ├── useSources.ts       # Source management
│   │   ├── useChat.ts          # Chat interface with streaming
│   │   ├── usePermissions.ts   # Chrome permissions state
│   │   ├── useToolPermissions.ts # AI tool permission requests
│   │   ├── useTransform.ts     # AI transformations
│   │   ├── usePickerModal.ts   # Source picker modal
│   │   └── useOnboarding.ts    # First-run onboarding
│   ├── services/        # Business logic layer
│   │   ├── notebooks.ts # Notebook CRUD
│   │   ├── permissions.ts # Chrome permissions helpers
│   │   ├── sources.ts    # Source import (tabs, bookmarks, history)
│   │   └── ui.ts        # UI helpers (notifications, dialogs)
│   ├── components/      # Preact UI components
│   │   ├── Header.tsx, AddTab.tsx, ChatTab.tsx, etc.
│   │   ├── TransformConfigPopover.tsx
│   │   ├── DropZone.tsx  # Drag-and-drop overlay for adding sources
│   │   └── AboutTab.tsx  # About page with contact and support info
│   └── styles.css       # UI styling
└── types/               # TypeScript interfaces
    └── index.ts         # Notebook, Source, ChatMessage, Credential, ModelConfig, etc.

Side Panel ──BroadcastChannel──> Wrapper (bridge page) ──postMessage──> Sandbox (iframe)

// Core entities (from src/types/index.ts)
interface Notebook {
  id: string;
  name: string;
  syncStatus: 'local' | 'synced' | 'pending' | 'conflict';
  modelConfigId?: string;  // Optional per-notebook model override
  createdAt: number;
  updatedAt: number;
}
interface Source {
  id: string;
  notebookId: string;
  type: 'tab' | 'bookmark' | 'history' | 'manual' | 'text' | 'note' | 'image';
  url: string;
  title: string;
  content: string;  // Extracted markdown content
  metadata?: {
    favicon?: string;
    description?: string;
    wordCount?: number;
    // Image-specific metadata (for type: 'image')
    imageUrl?: string;
    thumbnailUrl?: string;
    dimensions?: { width: number; height: number };
    altText?: string;
    sourcePageUrl?: string;
  };
  // ... timestamps, sync fields
}
interface ChatMessage {
  id: string;
  notebookId: string;
  role: 'user' | 'assistant';
  content: string;
  citations?: Citation[];
  timestamp: number;
}
interface Citation {
  sourceId: string;
  sourceTitle: string;
  excerpt: string;
}
// AI Configuration (from src/types/index.ts)
interface Credential {
  id: string;
  name: string;           // User-defined name (e.g., "Work OpenAI")
  apiKey: string;
  createdAt: number;
  updatedAt: number;
}
interface ModelConfig {
  id: string;
  name: string;           // Profile name (e.g., "Fast Responses")
  credentialId: string;   // References a Credential
  providerId: string;     // Provider from registry
  modelId: string;        // Model identifier
  temperature?: number;
  maxTokens?: number;
  createdAt: number;
  updatedAt: number;
}
// Transform State (from src/sidepanel/store/signals.ts)
interface PendingTransform {
  id: string;             // Unique ID for tracking
  type: TransformationType;  // Transform type being generated
  notebookId: string;     // Notebook this transform belongs to
  sourceIds: string[];    // Source IDs being transformed
  startTime: number;      // When the transform started
}
// Background Transform (from src/types/transform.ts)
// Executes in service worker, persists to IndexedDB
type BackgroundTransformStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
interface BackgroundTransform {
  id: string;
  type: TransformationType;
  notebookId: string;
  sourceIds: string[];
  status: BackgroundTransformStatus;
  createdAt: number;
  startedAt?: number;
  completedAt?: number;
  content?: string;       // Generated content (if completed)
  error?: string;         // Error message (if failed)
}