Lucid — AI Article Summariser

A Chrome extension (Manifest V3) that reads the article in your current tab and summarises it with the Gemini API — streaming output, three lengths, side panel, and one-click PDF / Markdown export.

• Screenshots
• Features
• Quick Start
• Usage
• Project Structure
• Architecture
• Configuration
• Permissions & Privacy
• Scripts
• Troubleshooting
• Contributing

Popup — streaming summary	Side panel — finished summary	Settings — key, model, length, theme

• Three summary lengths — Brief (2–3 sentences), Short (~120–180 words), Bullets (5–8 key points).
• Streaming output — tokens render as the model produces them, with Stop/Regenerate.
• Popup + side panel — quick popup for fast reads, persistent side panel for long articles.
• Summarise a selection — highlight any passage, right-click → Summarise selection with Lucid.
• Exports — styled A4 PDF, Markdown download, and Copy to clipboard.
• Resilient Gemini client — SSE streaming with thought-part filtering, plain-generateContent fallback, and clear per-error messages.
• Survives popup closes — in-flight state is mirrored to chrome.storage.session; reopen anywhere to resume.
• Light / dark / system themes — applied across popup, side panel, and settings.
• Safe rendering — model output goes through react-markdown with HTML skipped, so summaries can't inject markup.

npm install
npm run build

This typechecks, builds the extension pages with CRXJS into dist/, then bundles the standalone Readability extractor (dist/content-extract.js).

1. Open chrome://extensions.
2. Enable Developer mode (top right).
3. Click Load unpacked and select the dist/ folder.
4. Pin Lucid to the toolbar.

1. Click the Lucid icon → gear icon (Settings).
2. Paste your Gemini key → Verify & save (it is validated against the API before saving).
3. Pick a model (Gemini 3.5 Flash-Lite is the safest default for free-tier quota), a default length, and a theme.

Your key is stored in chrome.storage.local (this browser profile only — never synced) and is only ever sent to generativelanguage.googleapis.com in an x-goog-api-key header. See Permissions & Privacy.

1. Open any article (news, blog, docs, Wikipedia…).
2. Click the Lucid toolbar icon.
3. Choose Brief / Short / Bullets and hit Summarise.
4. While streaming you can Stop; after finishing you can Regenerate, Export PDF, Copy, or save Markdown.
5. For long reads, click the panel icon in the popup header to move into the side panel.
6. To summarise just a passage: select text → right-click → Summarise selection with Lucid.

• src/lib/* — framework-free modules (no React, no Chrome UI); unit-testable in Node.
• src/ui/* — shared presentational code used by all three surfaces.
• src/{popup,sidepanel,options}/* — thin per-surface entries (index.html + main.tsx).
• Path alias @/* maps to src/* (see tsconfig.json + vite.config.ts).

flowchart LR
    A[Popup / Side panel] -- Port: START/CANCEL --> B[Service worker]
    B -- chrome.scripting.executeScript --> C[Readability extractor]
    C -- article text --> B
    B -- SSE stream --> D[Gemini API]
    D -- text deltas --> B
    B -- CHUNK messages --> A
    A --> E[PDF / Markdown / Clipboard]

• The service worker owns the API key and all network calls; UI surfaces only ever receive text deltas.
• Article extraction uses Mozilla Readability on a cloned document, with a main/article fallback; text is capped at 100,000 chars and the UI flags truncation.
• The extractor is a separate IIFE bundle (vite.content.config.ts → dist/content-extract.js) because chrome.scripting.executeScript({ files }) loads classic scripts. It parks its result on __LUCID_EXTRACT__ for a follow-up call to collect.
• The Gemini client (src/lib/gemini.ts) streams via :streamGenerateContent?alt=sse, skips 3.x thought parts, tolerates non-SSE JSON-array bodies, and retries once via plain :generateContent if the stream is empty.
• In-flight jobs live in chrome.storage.session, so closing the popup mid-stream loses nothing.

Note (Sept 2026 Google change): fresh API keys are blocked from gemini-2.5-* (404 … no longer available to new users) even though models.list still advertises them. This project targets the 3.x models above. Stored 2.5 values from older installs auto-migrate to the new default via normaliseSettings().

Prompts force source-language matching, plain-Markdown-only output, and treat page content as data (prompt-injection resistant).

• Page text is sent to Google's Gemini API to produce the summary. Nothing is sent anywhere else, nothing is stored off your machine.
• Extension local storage is not encrypted. Anyone with access to this computer profile could read the key — treat it like any local credential and revoke it in AI Studio if exposed.

Still stuck? Open the service-worker console (chrome://extensions → Lucid → Inspect views: service worker) and look for [Lucid] empty Gemini stream — it logs { model, mode, state } (event count, candidates seen, block reason), which pinpoints the failure class.

1. npm install → npm run dev for UI work; npm run build:content after extractor changes.
2. npm run typecheck must pass; npm run build must produce a loadable dist/.
3. Keep secrets out of the repo — the API key lives only in your browser profile, never in code.
4. Small, focused commits; don't commit dist/, node_modules/, or exported *-summary.pdf/md files (all git-ignored).

Private project — all rights reserved. Dependencies retain their own licenses (see package.json).