# VGMdb Collection Manager — Browser Extension (!vgmdb-collection)

> **Status:** Active
> **Category:** Browser Extensions
> **Language:** JavaScript (Chrome Extension, Manifest V3)
> **Script files:** `manifest.json`, `content.js`, `background.js`, `style.css`

## Purpose

A Chrome browser extension that overlays a management panel on VGMdb album pages, allowing you to check whether an album is in your Google Sheet collection and add, update, or remove it inline. This is the current working version of the extension.

> **Note on folder name:** The source folder for this extension is named `!vgmdb-collection` — the leading `!` is unusual and likely causes it to sort to the top of the directory listing in Windows Explorer. This is a naming convention choice, not a technical requirement. When loading the extension in Chrome, browse to this folder directly.

A `WORKS.txt` file is included in the folder, indicating this version has been verified as functional.

## Requirements

### Browser
- Google Chrome (or any Chromium-based browser supporting Manifest V3)

### External Services
- A Google account with access to the configured Google Spreadsheet
- OAuth2 via Chrome Identity API — no manual token management

### Installation

1. Open Chrome and navigate to `chrome://extensions`
2. Enable **Developer mode** (toggle in top-right)
3. Click **Load unpacked**
4. Select the `!vgmdb-collection/` folder
5. On first use, Chrome will prompt you to sign in with Google to grant Sheets access

## How It Works

| Component | Role |
|-----------|------|
| `content.js` | Injected into every `vgmdb.net/album/*` page; creates the floating panel with a close button |
| `background.js` | Service worker; handles OAuth2 and all Google Sheets API calls |
| `style.css` | Styles the injected panel |

### Workflow

1. When you open a VGMdb album page, `content.js` injects a panel and sends a `checkUrl` message to the background worker.
2. The background worker fetches columns A:B from the linked Google Sheet and searches for the current URL.
3. If found: shows the album's current folder name with options to **Update** the folder or **Remove** the entry.
4. If not found: shows an **Add to Collection** form.
5. A close button (`×`) is present in the top corner of the panel to dismiss it without navigating away.

### Differences from the `vgmdb-chrome-script` version

| Feature | `vgmdb-chrome-script` | `!vgmdb-collection` |
|---------|----------------------|---------------------|
| Close button | No | Yes — panel can be dismissed |
| OAuth2 Client ID | `...0naq9o2l314...` | `...fnidrk602451...` (different Google Cloud project) |
| Folder name | Normal | Starts with `!` (sorts to top) |
| Verified working | Unknown | Yes (`WORKS.txt`) |

## Input

| Item | Description | Example |
|------|-------------|---------|
| Current page URL | Automatically captured from the browser tab | `https://vgmdb.net/album/1234` |
| Folder name | User-entered label for organising albums | `"Soundtracks"` |

## Output

| Item | Description |
|------|-------------|
| Google Sheet row | URL + folder name written to the configured spreadsheet |
| Panel status | Inline feedback message with auto-refresh on success |

## Notes

- **Hardcoded Spreadsheet ID:** `1Gz2A_xn2JSvENJH20aCEUXR1i01rrCvM3P2_NXyU-vs` — baked into `background.js`. Edit and reload to use a different sheet.
- **Hardcoded Sheet name:** `Sheet1` — change in `background.js` if your tab is named differently.
- **Hardcoded OAuth2 Client ID:** `624876005500-fnidrk602451tl08ao8v3nqub9h2cjng.apps.googleusercontent.com` — this is different from the `vgmdb-chrome-script` version and is tied to a separate Google Cloud project.
- URL query parameters are stripped before matching, so `album/1234?ref=search` is treated the same as `album/1234`.
- After a successful add/update/remove, the page automatically reloads after 1.5 seconds.

## Related Scripts

- [VGMdb Collection Manager (Chrome)](vgmdb-chrome-script.md) — earlier version without the close button; different OAuth2 client ID
- [VGMdb Firefox Script](vgmdb-firefox-script.md) — packaged Firefox equivalent (.xpi)