v0.7.0 · Chrome extension · English & Greek · free, bring your own key

BlankStare

A free Chrome side panel that rewrites developer docs, error messages and terminal output into plain English or Greek, as you read. Bring your own free Groq key.

Install ·Full guide ·Source ·Privacy

What it does

Translates, not explains

Select a paragraph of docs or an error and read a plain rewrite of it instead. No "this means…".

Four reading levels

ELI5, Newbie, Standard or Vibecoder. Switch and re-run in one click.

English or Greek

The whole panel, the answers and the read-aloud voice, in either language.

Jargon list

Every technical term on the selection, each with a two-to-ten word definition.

Free, your own key

Runs on Groq's free tier with your key. Nine models, and it hops to the next when one is busy.

Asks for little

Talks to Groq and, if you want, YouTube. Your private search server is asked for by name, only when you test it.

Showcase

A TypeError, in plain English

Select the error on any page and the panel rewrites it as you watch.

The same, in Greek

Panel, answers and read-aloud voice switch to Greek with one button.

Your last 20 answers

Open any earlier answer again without asking twice.

Ready when you are

The panel waits in the side of the browser. Select text, or press Alt+Shift+E.

Settings

One free key, a test button, and everything else folded away until you need it.

Dev

BlankStare is a Manifest V3 Chrome extension with no build step. Load the folder unpacked and it runs; npm test exists only for the Node test suite.

Architecture

Part	File	Job
Service worker	`background.js`	Context menu, keyboard commands, opens the side panel. `chrome.sidePanel.open()` must run synchronously inside the user gesture, so nothing is awaited before it.
Content script	`utils/pure.js`, `content.js`	Tracks the selection and draws the floating button inside a closed shadow root. The host element pins its own layout inline at `!important`, because the page’s CSS beats `:host` by spec.
Side panel	`sidepanel/*`	Streaming UI, i18n (EN/EL), history, TTS, glossary, follow-ups.
Settings	`settings/*`	Keys, model, voice, search provider, triggers, exclude list.
API layer	`utils/api.js`	Groq chat (SSE), Groq TTS (Orpheus), YouTube Data v3, SearXNG with DuckDuckGo fallback.
Pure logic	`utils/pure.js`	SSE reassembly, URL filtering, domain exclusion, Greek detection, prompt building. Never touches `chrome`, `document`, `window` or `fetch`.

Streaming

explainWithGroq({ apiKey, model, systemPrompt, userPrompt, maxTokens, autoFallback, signal, onChunk, onDone, onError, onStatus }).

Frames, not chunks. createSSEParser() buffers the incomplete tail of each network read. Splitting each chunk on \n on its own silently drops any data: line that straddles two reads.
Cancellation. Three independent AbortController lanes in the panel (translation, glossary, follow-up question), so a new request replaces its own predecessor only.
Failure mid-stream returns the partial text through onDone with a notice, never a hung cursor.
Token budget per mode: 700 for normal and rephrase, 1400 for “go deeper” and full-page.
Auto-fallback walks a nine-model registry on HTTP 429.

Permissions

host_permissions: https://api.groq.com/*, https://www.googleapis.com/*.
optional_host_permissions: http://*/*, https://*/*, used for one origin only: the user’s SearXNG server, requested by chrome.permissions.request from the settings Test button (it needs a gesture). searchWeb() checks chrome.permissions.contains first.
content_scripts.matches is <all_urls>, which alone causes Chrome’s “read and change all your data” warning. It stays, because the button must already exist when a selection happens.
Every remote string that becomes an href or src passes safeUrl() (http/https only).

Storage

chrome.storage.sync for settings, chrome.storage.session for the last 20 results (survives the panel closing, cleared with the browser). The panel listens with storage.session.onChanged; no polling.

Look

Deco Noir, vendored in vendor/. Panel data-dress="working", settings plain. Display face per glyph via unicode-range: Poiret One (Latin) and GFS Didot (Greek), all self-hosted in fonts/.

Test and preview

npm test                          # node --test, pure logic
npx http-server . -p 8123 -c-1    # then open lab/preview.html

In plain English

BlankStare is a free add-on for Google Chrome. It opens a panel at the side of your browser. When you read something written for programmers, like an error message, a setup guide or a page of documentation, you select it, and the panel rewrites it in plain English or Greek.

It does not add notes on top of the original. It gives you a version you can read instead of the original.

What you need

Google Chrome (or Edge, Brave, or another browser built on Chrome).
A free key from Groq, the company whose computers write the answers. It takes about three minutes to get one and costs nothing.

How you use it

Open the panel with the toolbar button or Alt + Shift + B.
Select the confusing text on any web page.
Press the small brass button that appears, or right-click and choose Explain with BlankStare.
Read the answer as it appears.

From there you can:

Change the reading level, from “explain it to a child” up to “I build things with AI tools”, and ask again.
Go deeper for more detail, or Rephrase for a different wording.
See the jargon list: every technical word, with a short meaning.
Hear it read aloud, in English or Greek.
Summarise the whole page in a few points.
Ask your own question about what you selected.
Look through your last 20 answers.

Your privacy

The text you select goes to Groq to be rewritten, or the whole page if you ask for a summary.
Video and web searches go to YouTube or your search engine, only when you use them.
Your keys are kept in your own browser.
If you use your own search server, Chrome asks you to allow that one address, once. Say no and BlankStare uses DuckDuckGo instead.
You can switch BlankStare off completely for any website you choose.

Cost

Nothing. Groq’s free allowance covers normal use. If one of its models is busy, BlankStare can move to the next one by itself.

Like I’m five

Some grown-ups write in a secret language full of strange words. Programmers do this a lot.

BlankStare is a helper that lives at the side of your web browser. When you see words you don’t understand, you colour them in with your mouse, press a little button, and the helper says the same thing again in easy words.

If it’s still too hard, you can ask it to make it even easier.
If you want to know more, you can ask it to say more.
It can speak English or Greek, and it can read the words out loud to you.

To work, it borrows a very clever computer from a company called Groq. They let you use it for free. You just need your own ticket, which is called a key.

It only reads the words you colour in, unless you ask it to read the whole page.

Walkthrough: your first translation

Install. Download the code, open chrome://extensions, switch on Developer mode, press Load unpacked and pick the folder. Settings opens by itself.
Get a free key. Sign in at console.groq.com, make an API key, paste it into AI Engine and press Test, then Save.
Open the panel. Click the toolbar icon, or press Alt+Shift+B.
Select something confusing on any page: an error, a README paragraph, a line of terminal output. Press the small brass button that appears, or right-click → Explain with BlankStare.
Read the translation as it streams in. Too hard? Change the level and press Re-explain. Want more? Go deeper.
Optional: add a YouTube key for videos on the topic, or your own SearXNG server for search. Chrome asks you to allow that one server when you press Test.

Playground: the extension's own logicCtrl + Enter

// Scroll to the bottom and press Run (or Ctrl + Enter).
// Everything above the demo is BlankStare's utils/pure.js, unchanged:
// the same code the extension runs and the test suite checks.

// utils/pure.js — BlankStare
//
// Side-effect-free logic, kept separate so it can be tested outside Chrome.
// Loads as a classic <script> in the extension AND as a CommonJS module under
// `node --test` (see the export guard at the bottom). No build step.
//
// Nothing in this file may touch `chrome`, `document`, `window` or `fetch`.

// ══ SSE FRAME REASSEMBLY ══════════════════════════════════════════════════════
// A network chunk is not a message frame. Reading `data:` lines out of each
// chunk independently drops any frame that straddles a chunk boundary — the
// half-line fails JSON.parse and the tokens vanish silently.
//
// The parser holds the incomplete tail back until the rest of it arrives.

function createSSEParser() {
  let buffer = '';

  function extract(lines) {
    const deltas = [];
    for (const line of lines) {
      const trimmed = line.trim();
      if (!trimmed.startsWith('data:')) continue;      // comments, blanks, keep-alives

      const payload = trimmed.slice(5).trim();
      if (!payload || payload === '[DONE]') continue;

      try {
        const delta = JSON.parse(payload)?.choices?.[0]?.delta?.content;
        if (delta) deltas.push(delta);
      } catch (_) {
        // A frame that is complete but malformed. Skipping it is correct —
        // killing the stream over one bad frame would lose the rest.
      }
    }
    return deltas;
  }

  return {
    // Feed a decoded network chunk; returns the deltas that completed with it.
    push(chunk) {
      buffer += chunk;
      const lines = buffer.split('\n');
      buffer = lines.pop() ?? '';   // last element is incomplete until proven otherwise
      return extract(lines);
    },

    // Call once the stream ends, in case the final frame arrived without a
    // trailing newline.
    flush() {
      const tail = buffer;
      buffer = '';
      return tail.trim() ? extract([tail]) : [];
    },
  };
}

// ══ URL SCHEME FILTERING ══════════════════════════════════════════════════════
// Search results are remote strings that become href/src attributes inside a
// document with extension privileges. Only http(s) may make that journey.
// Returns '' for anything else, so the caller renders an inert element.

function safeUrl(raw) {
  if (typeof raw !== 'string') return '';
  try {
    const url = new URL(raw.trim());
    return (url.protocol === 'http:' || url.protocol === 'https:') ? url.href : '';
  } catch (_) {
    return '';   // relative, protocol-relative, or malformed
  }
}

// ══ OPTIONAL-PERMISSION ORIGIN PATTERN ════════════════════════════════════════
// The SearXNG instance is user-supplied, so its origin cannot be declared in the
// manifest ahead of time. It is requested at runtime instead, which needs a
// match pattern rather than a URL: "https://search.example.com/*".
//
// Scoped to the single origin the user typed — never a broad "https://*/*", so
// granting SearXNG access does not hand the extension the whole web. Returns ''
// for anything that is not an http(s) URL, so the caller can refuse to ask.

function searxngOriginPattern(raw) {
  const url = safeUrl(raw);
  if (!url) return '';
  try {
    const { protocol, host } = new URL(url);
    if (!host) return '';

    // `new URL("https://*/*")` parses happily, with host "*". Echoing that back
    // would turn a request for one server into a request for the entire web, so
    // the host has to look like a real host: letters, digits, dots, hyphens,
    // a port, or bracketed IPv6. Anything else is refused.
    if (!/^[a-z0-9.\-]+(:\d+)?$/i.test(host) && !/^\[[0-9a-f:]+\](:\d+)?$/i.test(host)) {
      return '';
    }

    return `${protocol}//${host}/*`;
  } catch (_) {
    return '';
  }
}

// ══ SHARED LIMITS ═════════════════════════════════════════════════════════════
// The page-content budget was hardcoded as 4000 in both content.js and
// sidepanel.js, so changing it meant changing it twice.
const MAX_PAGE_CHARS = 4000;

// ══ DOMAIN EXCLUSION ══════════════════════════════════════════════════════════
// Entries may be pasted as full URLs; normalise to a bare hostname first.
// Matching is exact or a true subdomain — 'example.com' must not silence
// 'notexample.com'.

function isDomainExcluded(hostname, list) {
  if (!Array.isArray(list) || !list.length) return false;
  const host = String(hostname || '').toLowerCase();
  if (!host) return false;

  return list.some(entry => {
    if (typeof entry !== 'string') return false;
    const pattern = entry
      .trim()
      .toLowerCase()
      .replace(/^[a-z][a-z0-9+.-]*:\/\//, '')   // scheme
      .replace(/\/.*$/, '');                    // path
    if (!pattern) return false;
    return host === pattern || host.endsWith('.' + pattern);
  });
}

// ══ GREEK HEURISTIC ═══════════════════════════════════════════════════════════
// BlankStare translates English dev text. Greek input is almost always a user
// mistake, so it is caught before a request is spent on it. A stray λ in an
// English sentence must not trip the guard — hence a ratio, not a flag.

const GREEK_RATIO_THRESHOLD = 0.2;

function isLikelyGreek(text) {
  const str = String(text || '').trim();
  if (!str.length) return false;
  const greek = (str.match(/[Ͱ-Ͽἀ-῿]/g) || []).length;
  return greek / str.length > GREEK_RATIO_THRESHOLD;
}

// ══ READING LEVELS ════════════════════════════════════════════════════════════
// Standard reaches for everyday analogies; Vibecoder uses AI/API concepts as
// bridges, because that reader already has them.

const VALID_LEVELS = ['eli5', 'newbie', 'standard', 'vibecoder'];

const LEVEL_DESC = {
  eli5: {
    en: 'a 5-year-old child — use the simplest possible words, the shortest sentences, and playful everyday analogies. Zero jargon.',
    el: 'παιδί 5 ετών — απλούστατες λέξεις, κοντές προτάσεις, παιχνιδιάρικες αναλογίες. Μηδέν ορολογία.',
  },
  newbie: {
    en: 'a curious adult who has heard of coding but never done it — use friendly analogies from everyday life, be encouraging, assume nothing technical.',
    el: 'αρχάριο που γνωρίζει ότι υπάρχει κώδικας αλλά δεν έχει ασχοληθεί — φιλικές αναλογίες από καθημερινή ζωή.',
  },
  standard: {
    en: 'an intelligent non-developer who works with developers — smart, works in product/design/marketing/management, uses tools like Notion/Figma/Slack but has never written code. Use analogies from work life (documents, folders, processes, phone calls).',
    el: 'έξυπνο μη-προγραμματιστή που δουλεύει με developers — χρησιμοποιεί Notion/Figma/Slack αλλά δεν γράφει κώδικα. Αναλογίες από εργασιακή ζωή.',
  },
  vibecoder: {
    en: 'a vibecoder who builds software using AI tools (Claude, Cursor, Copilot, ChatGPT) but does not write traditional code. They ALREADY KNOW: what an API is, what a model/token/prompt is, what git roughly does, what a server is, what "running locally" means. Use these as bridge concepts — do NOT over-explain them. They do NOT know: compiler errors, syntax rules, package manager internals, algorithm complexity, low-level architecture.',
    el: 'vibecoder που φτιάχνει με AI (Claude, Cursor) αλλά δεν γράφει παραδοσιακό κώδικα. ΞΕΡΕΙ ήδη: API, model, token, prompt, git βασικά, server. ΔΕΝ ΞΕΡΕΙ: compiler errors, syntax, package managers σε βάθος.',
  },
};

// ══ SYSTEM PROMPT — TRANSLATION, NOT EXPLANATION ══════════════════════════════
// The output replaces the original. The reader should never need to go back and
// read the dev text.

function buildSystemPrompt(lang, level, userContext) {
  const who = LEVEL_DESC[level]?.[lang] || LEVEL_DESC.standard[lang] || LEVEL_DESC.standard.en;

  const langInstr = lang === 'el'
    ? 'Write your translation in Greek (Ελληνικά). All output must be Greek.'
    : 'Write in plain English.';

  const ctx = userContext ? `\nReader context: "${userContext}"` : '';

  return `You are a translator from Dev English (technical developer jargon) into plain language. Your reader is: ${who.replace(/\.$/, '')}.${ctx}

TRANSLATION RULES — follow these exactly:
1. REWRITE the content in plain language so the reader can fully understand it WITHOUT ever seeing the original. Write a TRANSLATION, not a footnote or a dictionary entry.
2. Start with 1-2 plain sentences that capture the COMPLETE meaning. Your reader should be able to act on those 2 sentences alone.
3. NEVER say "This means..." or "This is a..." or "In developer terms..." — just state it directly as if you wrote the original in plain language.
4. Translate jargon within your sentences, not as separate bullet definitions.
5. If the content requires action, state that action in plain terms: what to do, not what the error is called.
6. Use analogies naturally inside sentences, not as separate "think of it like..." paragraphs.
7. No code unless the reader specifically asks.
8. ${langInstr}`;
}

// ══ EXPORT GUARD ══════════════════════════════════════════════════════════════
// Present for `node --test`, absent in the browser. Keeps this file loadable by
// a plain <script> tag with no bundler and no module type.
if (typeof module !== 'undefined' && module.exports) {
  module.exports = {
    createSSEParser,
    safeUrl,
    searxngOriginPattern,
    isDomainExcluded,
    isLikelyGreek,
    buildSystemPrompt,
    VALID_LEVELS,
    LEVEL_DESC,
    GREEK_RATIO_THRESHOLD,
    MAX_PAGE_CHARS,
  };
}

// ── Try it ──────────────────────────────────────────────────────────────
// 1. A reply streamed in pieces that split a message in half. The parser
//    keeps the half until the rest arrives, so no word goes missing.
const parser = createSSEParser();
const words = [
  ...parser.push('data: {"choices":[{"delta":{"content":"Your code "}}]}\n\ndata: {"choi'),
  ...parser.push('ces":[{"delta":{"content":"tried to use something that is not there."}}]}\n\n'),
  ...parser.flush(),
];
console.log(words.join(''));

// 2. Is this Greek? Decides which language to answer in.
console.log(isLikelyGreek('Το αρχείο δεν βρέθηκε'), isLikelyGreek('File not found'));

// 3. Only http(s) links from search results are allowed to become links.
console.log(safeUrl('https://developer.mozilla.org/'), JSON.stringify(safeUrl('javascript:alert(1)')));

// 4. The instructions sent to the AI for Greek, beginner level.
console.log(buildSystemPrompt('el', 'newbie', ''));