# Hugging Bay Overlay

The Hugging Bay Overlay is a Manifest V3 browser extension for public Hugging Face model, dataset, and Space pages.

It adds a small panel with:

- Hugging Bay catalog resolution status.
- Links to the verified artifact page, trust bundle, review summary, model card, and hosted download rows.
- One-click Save to Library and Watch repo actions using a Hugging Bay reader token stored only in extension storage.
- A mirror-request action when the artifact is indexed but not hosted.
- A source-indexing request action when the Hugging Face artifact is public but not indexed yet.
- Human review, artifact-file, and verified-download paths first; raw JSON APIs are available as secondary links.

## Install Locally

1. Download `https://huggingbay.xyz/browser-extension/hugging-bay-overlay.zip`.
2. Unzip it.
3. Open `chrome://extensions`.
4. Enable Developer mode.
5. Choose Load unpacked.
6. Select the unzipped `hugging-bay-overlay` folder.
7. Open a Hugging Face artifact page such as `https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2`.

The machine-readable release manifest is available at `https://huggingbay.xyz/browser-extension/release.json`. It includes the ZIP SHA-256, ZIP ETag, Manifest V3 version, file hashes, install flow, and supported overlay capabilities.

The machine-readable store kit is available at `https://huggingbay.xyz/browser-extension/store-kit.json`. It includes listing copy, privacy notes, permission rationale, screenshot guidance, release ZIP metadata, and safe claims for AI agents or extension-directory reviewers. Chrome Web Store and Edge Add-ons should be described as available only when the install manifest links to a public listing.

For extension-directory uploads, use `https://huggingbay.xyz/browser-extension/hugging-bay-overlay-store.zip`. That ZIP keeps `manifest.json` at the ZIP root for Chrome Web Store and Edge Add-ons upload. The regular `hugging-bay-overlay.zip` keeps files inside a `hugging-bay-overlay/` folder because it is optimized for local unzip and Load unpacked installs.

Verify the ZIP before loading it:

```sh
curl -fsSL "https://huggingbay.xyz/browser-extension/release.json" -o hugging-bay-overlay.release.json
curl -fsSL "https://huggingbay.xyz/browser-extension/hugging-bay-overlay.zip" -o hugging-bay-overlay.zip
node -e 'const fs=require("node:fs"),crypto=require("node:crypto"); const r=JSON.parse(fs.readFileSync("hugging-bay-overlay.release.json","utf8")); const b=fs.readFileSync("hugging-bay-overlay.zip"); const got=crypto.createHash("sha256").update(b).digest("hex"); if (got!==r.zipSha256) { console.error("sha256 mismatch: expected "+r.zipSha256+" got "+got); process.exit(1); } if (b.length!==r.zipSizeBytes) { console.error("size mismatch: expected "+r.zipSizeBytes+" got "+b.length); process.exit(1); } console.log("zip ok "+got);'
```

## Production Origin

The production overlay calls `https://huggingbay.xyz` only. Non-production builds should use a separate unpacked manifest instead of adding test origins to the public release.

## Privacy

The content script reads only the current Hugging Face URL and asks the extension background worker to call Hugging Bay APIs. It does not read model files, page contents, cookies, or private Hugging Face data.

If you use Save to Library or Watch repo, the extension creates or reuses a Hugging Bay reader token and stores it as `huggingBayReaderToken` in extension-local storage. The token is sent only to Hugging Bay API endpoints with a bearer `Authorization` header. Reader tokens cannot publish artifacts or approve mirrors, and they can be revoked from the Hugging Bay Account page. If a saved token is revoked, the overlay clears it and retries once with a newly issued reader token.

If you close the overlay, the hidden state is scoped to that specific Hugging Face repo. Closing one model, dataset, or Space overlay does not hide Hugging Bay on every other Hugging Face page.

## APIs Used

- `GET https://huggingbay.xyz/api/resolve?repo=<hugging-face-url>`
- `POST https://huggingbay.xyz/api/account/reader-token`
- `PUT https://huggingbay.xyz/api/library/{id}`
- `PUT https://huggingbay.xyz/api/saved-searches/{id}`
- `POST https://huggingbay.xyz/api/artifacts/{id}/mirror-request`
- `POST https://huggingbay.xyz/api/source-requests`
- `GET https://huggingbay.xyz/artifact/{id}/files`
- `GET https://huggingbay.xyz/artifact/{id}/community`
- `GET https://huggingbay.xyz/api/trust-bundles/{id}`
- `GET https://huggingbay.xyz/api/artifacts/{id}/reviews`
- `GET https://huggingbay.xyz/api/downloadable-files?artifactId={id}`