Skip to content

README.md

Latest commit

 

History

History
323 lines (220 loc) · 7.11 KB

README.md

File metadata and controls

323 lines (220 loc) · 7.11 KB
Raw

Synapse Capture - Chrome Extension

Version Manifest

Your second brain, now in your browser. Capture any idea, highlight, or image directly to your Synapse knowledge base.

Features

  • Quick Capture: Save selected text with Alt+S keyboard shortcut
  • Inline Highlighting: Floating "Save to Synapse" button appears when you select text
  • Page Capture: Save entire articles with metadata extraction
  • Image Capture: Right-click images to save them
  • Link Capture: Save links with automatic metadata
  • Beautiful Popup: Quick note taking and page capture
  • Offline Support: Queues captures when backend is offline
  • Notifications: Visual feedback for successful captures
  • Context Menu: Right-click anywhere to access capture options

Installation

Prerequisites

  • Node.js 18+ installed
  • Synapse backend running on http://localhost:3000
  • Chrome browser (or Chromium-based browser)

Step 1: Install Dependencies

cd Extension
npm install

Step 2: Build the Extension

Development build (with file watching):

npm run watch

Production build:

npm run build

This creates a dist/ folder with the compiled extension.

Step 3: Load in Chrome

  1. Open Chrome and navigate to chrome://extensions/
  2. Enable "Developer mode" (toggle in top right)
  3. Click "Load unpacked"
  4. Select the Extension folder (not the dist folder)
  5. The Synapse Capture icon should appear in your toolbar

Step 4: Add Icons (Optional)

Place your icon files in the assets/ folder:

  • icon16.png
  • icon32.png
  • icon48.png
  • icon128.png

See assets/README.md for icon design guidelines.

Authentication

First Time Setup

  1. Click the Synapse extension icon
  2. Click "Open Dashboard & Login"
  3. Register or login to your Synapse account
  4. The extension will automatically detect your authentication

The extension stores your JWT token locally and uses it for all API calls.

Usage

Quick Note (Popup)

  1. Click the Synapse icon in toolbar
  2. Type your note in the textarea
  3. Click "Save Note"

Capture Selected Text

Method 1: Inline Button

  1. Select any text on a webpage
  2. A floating "Save to Synapse" button appears
  3. Click it to save

Method 2: Keyboard Shortcut

  1. Select any text
  2. Press Alt+S (Windows/Linux) or Cmd+Shift+S (Mac)

Method 3: Context Menu

  1. Select text
  2. Right-click → "Save to Synapse"

Capture Current Page

From Popup:

  • Click "Save Current Page" button

From Context Menu:

  • Right-click anywhere → "Save Page to Synapse"

Capture Links & Images

Links:

  • Right-click any link → "Save Link to Synapse"

Images:

  • Right-click any image → "Save Image to Synapse"

Backend Integration

The extension connects to your local Synapse backend:

POST http://localhost:3000/api/ingest

Request Format

{
  text?: string;           // Content to save
  url?: string;            // URL being captured
  type?: string;           // 'note' | 'article' | 'image' | 'video' | 'product'
  sourceApp: "Chrome Extension";
  context?: {
    pageTitle?: string;    // Page title
    selection?: string;    // Selected text
    favicon?: string;      // Page favicon URL
  }
}

Authentication

Includes JWT token in Authorization header:

Authorization: Bearer <your_token>

Offline Mode

When the backend is unavailable:

  • Captures are queued locally
  • Badge shows number of queued items (red)
  • Auto-retries every 10 minutes
  • Manual retry with "Sync" button in popup

Configuration

Extension settings are stored in Chrome's local storage:

{
  token: string; // JWT auth token
  backendUrl: string; // Backend API URL
  captureQueue: Array; // Offline queue
}

To change backend URL (for custom deployments), modify:

// src/utils.ts
export const BACKEND_URL = "http://localhost:5000";

Project Structure

Extension/
├── src/
│   ├── background.ts          # Service worker - handles captures
│   ├── content.ts             # Content script - inline UI
│   ├── content.css            # Content script styles
│   ├── types.ts               # TypeScript types
│   ├── utils.ts               # API utilities
│   └── popup/
│       ├── index.tsx          # Popup entry point
│       ├── Popup.tsx          # Main popup component
│       └── popup.css          # Popup styles
├── assets/
│   └── icon*.png              # Extension icons
├── manifest.json              # Extension manifest (MV3)
├── popup.html                 # Popup HTML
├── package.json
├── tsconfig.json
├── vite.config.ts
└── tailwind.config.js

🛠️ Development

Watch Mode

Run this for hot-reload during development:

npm run watch

After code changes:

  1. Go to chrome://extensions/
  2. Click the reload icon on your extension

Build for Production

npm run build

Debugging

Background Script:

  • Go to chrome://extensions/
  • Click "Service worker" under Synapse Capture
  • Opens DevTools for background script

Content Script:

  • Right-click on any webpage → Inspect
  • Check Console for content script logs

Popup:

  • Right-click extension icon → Inspect popup
  • Opens DevTools for popup

Publishing (Future)

To publish to Chrome Web Store:

  1. Create a developer account
  2. Zip the dist/ folder
  3. Upload to Chrome Web Store
  4. Submit for review

Tech Stack

  • Framework: React 18 + TypeScript
  • Build Tool: Vite
  • Styling: Tailwind CSS
  • Icons: Lucide React
  • Manifest: V3 (Service Worker)

Roadmap

Current: Phase 3 - Advanced Capture

  • Phase 1: Basic extension setup
  • Phase 2: Context menu + popup capture
  • Phase 3: Inline highlighting + shortcuts
  • Phase 4: Dashboard integration
  • Phase 5: Auto-capture intelligence
  • Phase 6: Offline support improvements
  • Phase 7: Screenshot capture
  • Phase 8: Settings page

Troubleshooting

Extension not loading?

  • Make sure you ran npm run build
  • Load the main Extension folder, not dist/
  • Check for TypeScript errors in build output

"Not authenticated" error?

  • Login through the dashboard first
  • Token is stored after successful login
  • Check Chrome DevTools → Application → Storage

Captures not saving?

  • Verify backend is running on port 3000
  • Check http://localhost:3000/health
  • Look for errors in extension console

Floating button not appearing?

  • Try selecting more text (minimum 10 characters)
  • Check content script is injected (DevTools → Elements)
  • Reload the page

Integration with Synapse

This extension is part of the Project Synapse ecosystem:

  • Backend API: Node.js + Express + MongoDB
  • Web Dashboard: Next.js (coming soon)
  • Chrome Extension: This project
  • Native App: Electron (future)

All components share the same authentication and data layer.

License

MIT

Built with love for capturing knowledge effortlessly