# VibeGuard

VibeGuard is a local-first browser extension that hides toxic social-media posts. Content is classified on-device; post text is never sent to a classification service.

## Development

```sh
npm install
npm run typecheck
npm test
npm run build:firefox
npm run build:chromium
```

Each build writes a browser-specific package under `dist/<mode>/`. The packaged Apache 2.0 model is committed through Git LFS. Use the pinned-revision workflow below when updating it:

```sh
python3 -m venv .model-venv
. .model-venv/bin/activate
python3 -m pip install -r tools/requirements-model.txt

# Inspect architecture, labels, tokenizer, and resolved source revision.
python3 tools/convert_model.py inspect \
  --model wagesj45/toxic-comment-classifier

# Use the immutable commit printed by inspection for a release artifact.
python3 tools/convert_model.py prepare \
  --model wagesj45/toxic-comment-classifier \
  --revision <resolved-huggingface-commit>
python3 tools/convert_model.py validate
```

Preparation writes the Transformers.js-compatible files and `model-manifest.json` under `public/models/toxicity/`. The manifest records the source revision, Apache 2.0 license, toxic/non-toxic label indices, maximum sequence length, and int8 quantization format. Source PyTorch/safetensors weights are never copied into the extension.

If the model uses generic labels such as `LABEL_0` and `LABEL_1`, pass `--toxic-index` and `--non-toxic-index` to `prepare`; the command refuses to guess an ambiguous mapping.

The first release targets Reddit, X/Twitter, and Facebook. Site selectors are isolated under `src/content/parsers/` because these sites frequently change their DOM structures.

## Runtime architecture

Firefox uses a persistent MV2 background page and inference worker. Chromium uses an MV3 service worker as a router, an offscreen document, and a worker-backed classifier. Both builds share one bounded, prioritized inference queue and in-memory text-result cache.