docs: Add local and HF deployment options and Firefox extension instructions

README.md

@@ -36,7 +36,13 @@ We chose **Gemma 2B** because it offers an incredible balance of deep semantic u
 * **Frontend:** Pure HTML/JS/CSS with a minimalist, distraction-free "academic paper" aesthetic.
 * **Database:** SQLite for storing A/B test results.
 
-## How to Run Locally
+## How to Deploy and Run
+
+FlowRead AI can be run locally on your machine or deployed directly to Hugging Face Spaces.
+
+### Option 1: Run Locally (Recommended for Development)
+
+Running locally allows you to use your own GPU (like Apple Silicon MPS or Nvidia CUDA) for significantly faster processing.
 
 1. **Install Dependencies:**
    ```bash
@@ -48,11 +54,40 @@ We chose **Gemma 2B** because it offers an incredible balance of deep semantic u
    huggingface-cli login
    ```
 3. **Start the Server:**
+   You can start the FastAPI server using Uvicorn:
    ```bash
-   python main.py
+   uvicorn main:app --reload --host 0.0.0.0 --port 8000
    ```
 4. **Open the Web App:**
-   Navigate to `http://localhost:7860/static/index.html` in your browser.
+   Navigate to `http://localhost:8000` in your browser.
+
+### Option 2: Deploy to Hugging Face Spaces (Docker)
+
+This repository is already configured with a `Dockerfile` and the correct YAML frontmatter to be deployed directly as a Hugging Face Docker Space.
+
+1. Create a new **Docker Space** on Hugging Face.
+2. Add your Hugging Face Token as a Repository Secret named `HF_TOKEN`. This is required to download the gated Gemma 2B model.
+3. Push this repository to your Space.
+4. The Space will automatically build the Docker image and start the FastAPI server. The SQLite database (`study.db`) is safely written to the `/tmp` or `/data` directory to avoid read-only filesystem errors.
+
+## FlowRead Firefox Extension
+
+You can use FlowRead directly on any website using the included Firefox Extension! The extension communicates with your FlowRead backend (either Local or Hugging Face) to highlight text directly on the page.
+
+### How to Install the Extension:
+1. Locate the `flowread-extension.zip` file in this repository (or the `firefox-extension` folder).
+2. Open Firefox and navigate to `about:debugging`.
+3. Click **"This Firefox"** on the left sidebar.
+4. Click **"Load Temporary Add-on..."**.
+5. Select the `manifest.json` file inside the `firefox-extension` folder (or select the `.zip` file).
+
+### How to Configure and Use:
+1. **Set your Backend URL:** Click the FlowRead icon in your Firefox toolbar. In the settings popup, set the **Backend API URL**:
+   - If running locally: Enter `http://127.0.0.1:8000`
+   - If using Hugging Face: Enter your Space URL (e.g., `https://your-username-flowread.hf.space`)
+2. **Read:** Highlight any paragraph of text on any website.
+3. **FlowRead It:** Right-click the highlighted text and select **"FlowRead Highlight"**.
+4. The text on the page will dynamically transform using Gemma's attention vectors!
 
 ## The User Study (Help Us Prove It Works!)
-When you deploy this project to Hugging Face Spaces, users can take the built-in **2-Minute Study**. The system randomly assigns users to read plain text vs. FlowRead text, times their reading speed, and tests their comprehension. The global statistics dashboard proves the real-world impact of Gemma-powered saliency!
+The web application includes a built-in **3-Minute Study**. The system randomly assigns users to read plain text, FlowRead (bolding), or FlowRead (gradient) text. It times their reading speed, tests their comprehension, and asks for their preference. The global statistics dashboard proves the real-world impact of Gemma-powered saliency!

firefox-extension/background.js

@@ -0,0 +1,22 @@
+// For cross-browser compatibility (Firefox uses browser, Chrome uses chrome)
+if (typeof browser === "undefined") {
+  var browser = chrome;
+}
+
+browser.runtime.onInstalled.addListener(() => {
+  browser.contextMenus.create({
+    id: "flowread-selection",
+    title: "FlowRead Highlight",
+    contexts: ["selection"]
+  });
+});
+
+browser.contextMenus.onClicked.addListener((info, tab) => {
+  if (info.menuItemId === "flowread-selection") {
+    // We send a message to the content script asking it to grab the selection and replace it
+    browser.tabs.sendMessage(tab.id, {
+      action: "flowread_selection",
+      text: info.selectionText
+    });
+  }
+});

firefox-extension/content.css

@@ -0,0 +1,37 @@
+.flowread-token {
+    transition: font-weight 0.2s;
+    font-family: inherit;
+    color: inherit;
+}
+
+.flowread-highlighted {
+    font-weight: 800; /* Extra bold */
+    color: inherit;
+}
+
+.flowread-semi-highlighted {
+    font-weight: 600;
+    color: inherit;
+}
+
+/* A small toast/loading indicator */
+#flowread-toast {
+    position: fixed;
+    bottom: 20px;
+    right: 20px;
+    background: #292524;
+    color: #fdfbf7;
+    padding: 12px 24px;
+    border-radius: 8px;
+    font-family: system-ui, sans-serif;
+    font-weight: bold;
+    z-index: 999999;
+    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    opacity: 0;
+    transition: opacity 0.3s;
+    pointer-events: none;
+}
+
+#flowread-toast.show {
+    opacity: 1;
+}

firefox-extension/content.js

@@ -0,0 +1,139 @@
+if (typeof browser === "undefined") {
+  var browser = chrome;
+}
+
+// Ensure the toast element exists
+function ensureToast() {
+  let toast = document.getElementById('flowread-toast');
+  if (!toast) {
+    toast = document.createElement('div');
+    toast.id = 'flowread-toast';
+    document.body.appendChild(toast);
+  }
+  return toast;
+}
+
+function showToast(message, duration = 3000) {
+  const toast = ensureToast();
+  toast.textContent = message;
+  toast.classList.add('show');
+  if (duration > 0) {
+    setTimeout(() => {
+      toast.classList.remove('show');
+    }, duration);
+  }
+}
+
+browser.runtime.onMessage.addListener(async (request, sender, sendResponse) => {
+  if (request.action === "flowread_selection") {
+    const selectedText = window.getSelection().toString();
+    if (!selectedText.trim()) return;
+
+    showToast("Analyzing text with FlowRead AI...", 0);
+
+    // Save the selection range so we can replace it later
+    const selection = window.getSelection();
+    if (selection.rangeCount === 0) return;
+    const range = selection.getRangeAt(0);
+
+    // Get user settings
+    const settings = await browser.storage.local.get(['threshold', 'gradientMode', 'preprompt', 'apiUrl']);
+    const threshold = settings.threshold !== undefined ? settings.threshold : 0.35;
+    const useGradient = settings.gradientMode || false;
+    const preprompt = settings.preprompt || "";
+    const apiUrl = settings.apiUrl || "http://127.0.0.1:8000";
+    // Default to middle layers just like the playground
+    const checkedLayers = [4, 5, 6, 7, 8, 9, 10, 11, 12, 13];
+
+    try {
+      // Connect to the configured API Space
+      const response = await fetch(`${apiUrl}/analyze`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ 
+          text: selectedText, 
+          preprompt: preprompt, 
+          layers: checkedLayers 
+        })
+      });
+
+      if (!response.ok) throw new Error('API error');
+      
+      const data = await response.json();
+      const currentTokens = data.words || [];
+
+      // Reconstruct the HTML
+      const htmlString = generateFlowReadHTML(currentTokens, threshold, useGradient);
+      
+      // Replace text
+      range.deleteContents();
+      
+      const container = document.createElement('span');
+      container.className = 'flowread-container';
+      container.innerHTML = htmlString;
+      range.insertNode(container);
+      
+      showToast("Done!", 1500);
+
+    } catch (err) {
+      console.error(err);
+      showToast("Error: Could not reach FlowRead API", 3000);
+    }
+  }
+});
+
+// Grouping logic extracted from your frontend code
+function generateFlowReadHTML(currentTokens, threshold, useGradient) {
+  let html = "";
+  
+  let words = [];
+  let currentWordTokens = [];
+  let currentWordMaxScore = 0;
+
+  currentTokens.forEach((item, index) => {
+      if (index === 0 && (item.token.includes('<bos>') || item.word.includes('<bos>'))) return;
+
+      const isWhitespace = item.token.trim() === '';
+      const prevIsWhitespace = currentWordTokens.length > 0 && currentWordTokens[currentWordTokens.length - 1].token.trim() === '';
+
+      if (item.token.startsWith(' ') || (currentWordTokens.length > 0 && isWhitespace !== prevIsWhitespace)) {
+          if (currentWordTokens.length > 0) {
+              words.push({ tokens: currentWordTokens, maxScore: currentWordMaxScore });
+          }
+          currentWordTokens = [item];
+          currentWordMaxScore = item.score;
+      } else {
+          currentWordTokens.push(item);
+          currentWordMaxScore = Math.max(currentWordMaxScore, item.score);
+      }
+  });
+  if (currentWordTokens.length > 0) {
+      words.push({ tokens: currentWordTokens, maxScore: currentWordMaxScore });
+  }
+
+  // Render words
+  words.forEach(wordObj => {
+      const isWordHighlighted = wordObj.maxScore >= threshold;
+
+      wordObj.tokens.forEach(item => {
+          let styleAttr = '';
+          let classNames = 'flowread-token';
+          
+          if (useGradient) {
+              const opacity = 0.4 + (item.score * 0.6);
+              const weight = 400 + Math.round(item.score * 400);
+              styleAttr = `opacity: ${opacity}; font-weight: ${weight}; color: inherit;`;
+          } else {
+              if (isWordHighlighted) {
+                  classNames += ' flowread-highlighted';
+              }
+          }
+          
+          const safeText = String(item.token || "").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\n/g, "<br>");
+          
+          html += `<span class="${classNames}" ${styleAttr ? `style="${styleAttr}"` : ''}>${safeText}</span>`;
+      });
+  });
+  
+  return html;
+}

firefox-extension/manifest.json

@@ -0,0 +1,30 @@
+{
+  "manifest_version": 3,
+  "name": "FlowRead AI",
+  "version": "1.0",
+  "description": "Accelerate reading comprehension using LLM attention vectors.",
+  "permissions": [
+    "contextMenus",
+    "storage",
+    "activeTab",
+    "scripting"
+  ],
+  "host_permissions": [
+    "https://jobbler-flowread.hf.space/*",
+    "<all_urls>"
+  ],
+  "background": {
+    "scripts": ["background.js"]
+  },
+  "action": {
+    "default_popup": "popup.html",
+    "default_title": "FlowRead AI Settings"
+  },
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["content.js"],
+      "css": ["content.css"]
+    }
+  ]
+}

firefox-extension/popup.html

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>FlowRead Settings</title>
+  <style>
+    body {
+      font-family: system-ui, sans-serif;
+      width: 300px;
+      padding: 15px;
+      color: #292524;
+      background: #fdfbf7;
+      margin: 0;
+    }
+    h2 {
+      font-size: 1.25rem;
+      margin-top: 0;
+      margin-bottom: 15px;
+      color: #1c1917;
+    }
+    label {
+      display: block;
+      margin-bottom: 5px;
+      font-weight: 600;
+      color: #44403c;
+      font-size: 0.9rem;
+    }
+    input[type="range"] {
+      width: 100%;
+      margin-bottom: 15px;
+    }
+    input[type="text"] {
+      width: 100%;
+      padding: 8px;
+      box-sizing: border-box;
+      margin-bottom: 15px;
+      border: 1px solid #d6d3d1;
+      border-radius: 4px;
+      font-family: inherit;
+    }
+    .checkbox-group {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      margin-bottom: 15px;
+    }
+    .checkbox-group input {
+      margin: 0;
+      width: 16px;
+      height: 16px;
+      cursor: pointer;
+    }
+    .checkbox-group label {
+      margin: 0;
+      cursor: pointer;
+    }
+    p.help {
+      font-size: 0.8rem;
+      color: #78716c;
+      margin-top: -10px;
+      margin-bottom: 15px;
+    }
+    button {
+      width: 100%;
+      padding: 10px;
+      background: #292524;
+      color: #fff;
+      border: none;
+      border-radius: 4px;
+      font-weight: bold;
+      cursor: pointer;
+    }
+    button:hover {
+      background: #44403c;
+    }
+  </style>
+</head>
+<body>
+  <h2>FlowRead Settings</h2>
+  
+  <label for="threshold">Threshold: <span id="threshold-val">0.35</span></label>
+  <input type="range" id="threshold" min="0" max="1" step="0.01" value="0.35">
+
+  <div class="checkbox-group">
+    <input type="checkbox" id="gradient-mode">
+    <label for="gradient-mode">Gradient Mode</label>
+  </div>
+  <p class="help">Maps attention scores to visual contrast dynamically.</p>
+
+  <label for="preprompt">Intent-Driven Reading</label>
+  <input type="text" id="preprompt" placeholder="e.g., Focus on numbers and dates">
+  <p class="help">Instruct the AI what to focus on before generating saliency.</p>
+
+  <label for="api-url">Backend API URL</label>
+  <input type="text" id="api-url" placeholder="http://127.0.0.1:8000">
+  <p class="help">URL of your FlowRead backend (Local or Hugging Face).</p>
+
+  <button id="save-btn">Save Settings</button>
+
+  <script src="popup.js"></script>
+</body>
+</html>

firefox-extension/popup.js

@@ -0,0 +1,43 @@
+document.addEventListener('DOMContentLoaded', () => {
+  const thresholdInput = document.getElementById('threshold');
+  const thresholdVal = document.getElementById('threshold-val');
+  const gradientModeInput = document.getElementById('gradient-mode');
+  const prepromptInput = document.getElementById('preprompt');
+  const apiUrlInput = document.getElementById('api-url');
+  const saveBtn = document.getElementById('save-btn');
+
+  // Load existing settings
+  browser.storage.local.get(['threshold', 'gradientMode', 'preprompt', 'apiUrl'], (res) => {
+    if (res.threshold !== undefined) {
+      thresholdInput.value = res.threshold;
+      thresholdVal.textContent = parseFloat(res.threshold).toFixed(2);
+    }
+    if (res.gradientMode !== undefined) {
+      gradientModeInput.checked = res.gradientMode;
+    }
+    if (res.preprompt !== undefined) {
+      prepromptInput.value = res.preprompt;
+    }
+    apiUrlInput.value = res.apiUrl || "http://127.0.0.1:8000";
+  });
+
+  // Update threshold label
+  thresholdInput.addEventListener('input', (e) => {
+    thresholdVal.textContent = parseFloat(e.target.value).toFixed(2);
+  });
+
+  // Save settings
+  saveBtn.addEventListener('click', () => {
+    const settings = {
+      threshold: parseFloat(thresholdInput.value),
+      gradientMode: gradientModeInput.checked,
+      preprompt: prepromptInput.value.trim(),
+      apiUrl: apiUrlInput.value.trim().replace(/\/$/, '') // Remove trailing slash
+    };
+    
+    browser.storage.local.set(settings).then(() => {
+      saveBtn.textContent = 'Saved!';
+      setTimeout(() => saveBtn.textContent = 'Save Settings', 1500);
+    });
+  });
+});