🎯 Focus

Stay in the flow. Instant word definitions — no new tab, no distraction.

---

✨ What is Focus?

Focus is a Chrome Extension built on Manifest V3 that empowers readers to look up word definitions instantly — directly within the page. No context switching, no new tabs. Just highlight a word, get the definition, and keep reading.

Philosophy: Minimum Distraction. Maximum Context.

---

🚀 Key Features

• 📖 Inline Definitions — Highlight any word to reveal an elegant floating definition card, rendered directly on the page.
• ⚡ Local-First Lookup — Uses a bundled Webster-based dictionary_compact.json loaded into IndexedDB for near-instant lookups — no internet required.
• 🌐 API Fallback — Automatically queries the Free Dictionary API for words not found in the local store.
• 🧠 Smart Caching — An in-memory cache layer sits on top of IndexedDB to eliminate redundant disk reads during a session.
• 🎨 Glassmorphic UI — A polished, dark-mode aware popup and definition card with smooth animations.
• 🔒 Privacy-First — All local lookups are fully offline. No user data is ever transmitted unless an API fallback is triggered.
• ⚙️ Settings Popup — A dedicated popup UI accessible from the Chrome toolbar for extension controls.

---

📸 How to Use — Step by Step

✅ This repository includes a ready-to-use dist/ folder for quick install without any build steps.

The following screenshots walk you through the full experience.

Step 1 — Load in Chrome Navigate to chrome://extensions, enable Developer Mode, and click Load unpacked → select the dist/ folder.	Step 2 — (Contributors) Build the Extension Only needed if you changed source code. Run npm run build to regenerate dist/.
Step 3 — Extension is Active Focus appears in your Chrome toolbar. Click the icon to open the settings popup.	Step 4 — Select a Word Highlight any word on any webpage. A definition button will appear near your selection.
Step 5 — See the Definition The definition card appears inline — rich, clean, and fully non-intrusive.

---

🛠️ Installation & Development

Option A — Easy Setup (No Build Required)

• Direct dist/ folder download: Download dist folder
• If that link is blocked in your network, download the repo ZIP and use its dist/ folder.

1. Download or clone this repository
2. Open Chrome and go to chrome://extensions
3. Enable Developer Mode (top-right toggle)
4. Click "Load unpacked"
5. Select the dist/ folder from this repository

✅ You can use the extension immediately. No Node.js, npm, or build step required.

Option B — Contributor Setup (Build from Source)

Prerequisites

• Node.js >=18
• npm >=9
• Google Chrome (latest)

1. Clone & Install Dependencies

git clone https://github.com/<your-username>/focus-extension.git
cd focus-extension
npm install

2. Build the Extension

npm run build

This uses tsc + Vite to compile TypeScript and bundle all three entry points (popup, background, content) into the dist/ folder.

3. Load into Chrome

1. Open Chrome and go to chrome://extensions
2. Enable Developer Mode (top-right toggle)
3. Click "Load unpacked"
4. Select the dist/ folder inside the project root

✅ The extension will now appear in your toolbar and be active on all pages.

4. Development Mode (Hot Reload)

npm run dev

Note: Vite's dev server powers the popup UI. For content script and background changes, you must rebuild and reload the extension in Chrome manually.

---

🏗️ Tech Stack

Layer	Technology
Build Tool	Vite 8.x
Language	TypeScript 5.9
UI Framework	React 19
Styling	Tailwind CSS 4.x
Extension API	Chrome Manifest V3
Local Data	IndexedDB + In-Memory Cache
Dictionary Source	Webster's English (Compact JSON) + dictionaryapi.dev

---

📁 Project Structure

focus/
├── public/
│   ├── manifest.json          # Chrome Extension manifest (MV3)
│   ├── dictionary_compact.json # Bundled Webster's dictionary (~22MB)
│   ├── favicon.svg
│   └── icons.svg
├── src/
│   ├── background.ts          # Service Worker: dictionary load, lookup, API fallback
│   ├── content.tsx            # Content Script: highlight detection, definition card UI
│   ├── App.tsx                # Popup UI: settings and status
│   ├── main.tsx               # Popup entry point
│   └── index.css              # Global styles
├── images/                    # Step-by-step screenshots
├── index.html                 # Popup HTML entry
├── vite.config.ts             # Multi-entry Vite configuration
└── package.json

---

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

---

📄 License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later) — see the LICENSE.md file for details.

---

🙏 Credits & Acknowledgments

Dictionary data and related resources are credited to the following sources:

• Matthew Reagan — WebstersEnglishDictionary
• Project Gutenberg — gutenberg.org
• Adam Isaacs — adambom/dictionary

Focus uses bundled Webster-derived local dictionary data as the primary source, and the Free Dictionary API as a secondary fallback for terms not present in local storage.

---

_{Built with ❤️ to keep you in the flow.}