# Web Clipper

Save web content directly into your OpenCharts notes — via the Chrome extension or the in-editor `/clip` command. Clip full pages, selections, highlights, screenshots, or images, then let AI summarize or extract action items automatically.

## Installing the Chrome Extension

1. Download the extension from the Chrome Web Store (or load it unpacked from `extensions/opencharts-clipper/` for development).
2. Click the extension icon and log in with your OpenCharts account.
3. Pin the extension to your toolbar for quick access, or use the keyboard shortcut `Ctrl+Shift+O`.

The extension uses Manifest V3 with Vite + React. Auth is handled via Appwrite Web SDK — your session JWT is stored securely in `chrome.storage.session`.

## 5 Clip Modes

- **Full Page**: Captures the entire page using Readability, stripping ads and navigation for clean content.
- **Selection**: Clip only the text you've selected on the page.
- **Multi-Passage Highlights**: Highlight multiple passages across the page. Highlights persist via XPath anchoring, even after reload.
- **Screenshot**: Capture a viewport screenshot or draw a region to clip a specific area as an image.
- **Image Grab**: Right-click any image on a page to clip it directly into your notes.

## AI Actions

After clipping, you can run AI actions on the content before it lands in your note. These are processed server-side via `/api/notes/clip-ai` with Theo's clip engine (with automatic fallback engines).

- **Summarize**: Condense the clipped content into a brief summary.
- **Key Takeaways**: Extract the most important points as a bullet list.
- **Extract Actions**: Pull out action items and to-dos from the content.
- **Classify**: Auto-tag the clip based on its content type.
- **Custom Prompt**: Write your own AI instruction to process the clip.

## Destination Picker & Insert Position

Choose which note receives the clip with **fuzzy search** powered by `/api/notes/search`.

Pick where the clip is inserted:
- **Append**: add to the end of the note.
- **Prepend**: insert at the top.
- **After Heading**: pick a specific heading (fetched from `/api/notes/[projectId]/headings`).

## Clip Templates & Auto-Matching

The template engine supports **14 variables** (title, URL, date, selection, etc.) and auto-matches templates based on:
- **URL patterns**: match domains or path patterns.
- **Schema.org type**: detect articles, recipes, products, etc.

5 default templates are included. You can create custom templates in the extension's options page.

## The `/clip` Slash Command

You don't need the extension to clip web content. Type `/clip` in the notes editor, paste a URL, and OpenCharts fetches and parses the page server-side using Readability.

The result is inserted as a **webClip block** — the same collapsible card you get from the extension. The slash command is great for quick clips without switching to the browser extension. It supports the same AI actions after insertion.

## Web Clip Block in Notes

Clipped content appears as a custom **webClip** block in OpenCharts Notes with:
- **Collapsible card**: expand/collapse the clipped content.
- **Metadata header**: source URL, favicon, clip date.
- **Hover actions**: open source, re-clip, delete.
- **Outline sidebar**: a dedicated "Clips" section lists all clips with source titles, favicons, click-to-jump navigation, and a count badge.
- **Status bar**: clip count and clipped word count.

## AI Panel Clip Awareness

The Notes AI side panel automatically detects clips in your document. Two built-in AI templates are available:
- **"Summarize my clips"**: generates a synthesis of all clipped content.
- **"Extract action items from clips"**: pulls tasks from clipped pages.

Clip-related queries are automatically scoped to clip sources via the intent classifier's `clipScoped` flag.

## Offline Queue

If you're offline or the server is unreachable, clips are queued in **IndexedDB** and automatically retried every 30 seconds. The extension badge shows the number of pending clips. Once connectivity is restored, queued clips are delivered in order.

## Keyboard Shortcuts

- `Ctrl Shift O`: Open clipper popup
- `Ctrl Shift H`: Toggle highlights mode
- `Ctrl Shift S`: Screenshot capture
- `Ctrl Shift L`: Open clip history

## Batch & Team Clipping

- **Batch clip**: select multiple tabs and clip them all at once into the same note.
- **Team clipping**: when working in a team workspace, clips can include an `orgId` so they land in the correct organization project. Collaborators receive a real-time toast notification when a clip is inserted.

## Export Awareness

Web clips are export-aware across all formats: DOCX and PDF render a left-border card with a source footer, Markdown uses blockquotes with source links, and plain text outputs footnotes. Version history tracks clips with the `add_clip` change type.