# Casino.org Inspector

An **unpacked, developer-mode** Chrome extension that observes
[casino.org](https://www.casino.org) traffic — focused on the Replay Poker
product — and surfaces it as a **Game History** view. Read-only on the
casino site (no request blocking or modification). Captured data lives
locally in `chrome.storage.local`; it never leaves your machine unless
you opt in by clicking **Flush now** or **Export** in the History page.

## What it does

- Captures HTTP and WebSocket traffic from `*.casino.org` while you play.
- Groups WebSocket frames by Phoenix `table:<id>` topic into per-table
  rounds (one row per finished hand in the History view).
- Stores everything in `chrome.storage.local`; capped buffers.
- **Auto-flush on every `finishHand`** to the companion website
  (`statisticasino`), plus a manual `Flush now` button and a
  `.casinodump` export you can drop on the site's `/contribute`
  page. Auto-flush is on by default; turn it off in extension
  Settings → Sync.
- **Auto-delete after flush** (off by default): once a hand has
  been successfully uploaded, the extension drops its captured
  frames from local storage so the buffer doesn't grow without
  bound on long sessions. The audit row in the sync index
  survives, but the round disappears from History.

Clicking the toolbar icon opens **`history.html`** as a full browser tab
showing one expandable row per table session. (The old popup with
Messages / Network / Page Data tabs has been removed.)

## Install (Developer Mode, unpacked)

1. Clone or download this repo.
2. Open `chrome://extensions` in Chrome (or any Chromium browser).
3. Toggle **Developer mode** on (top-right).
4. Click **Load unpacked** and select this repo's root folder
   (`casinoMalwareExtension`).
5. Pin the extension from the puzzle-piece menu so the icon is visible.
6. Open any `https://www.casino.org/replaypoker/...` page and play a hand.
7. Click the extension icon — the **Game History** tab opens, listing every
   captured table session newest-first. Click a row to expand it to a list
   of rounds (hands); click a round to drop down an inline replay panel
   with a felt diagram, scrubber, and Prev/Next step controls.

The icon focuses an existing History tab if one is already open, instead of
stacking duplicates.

Because it is unpacked, the extension exists **only in your developer
profile** — it is not in the Chrome Web Store and will not be installed
for any other user.

## File layout

```
manifest.json     MV3 manifest (host_permissions limited to *.casino.org)
background.js     service worker: capture pipeline + opens history.html on action click
inject.js         MAIN-world patches for fetch/XHR/WebSocket/SSE/beacon/postMessage
bridge.js         ISOLATED-world bridge that forwards captures to the worker
content.js        DOM scrape (review-style listing pages)
classify.js       shared meaningful/noise classifier
tableize.js       groups stored ws messages by tableId (permanent, no time gap) + hand boundaries
serialize.js      canonical hand envelope + gzip codec used by both flush + export
flush.js          per-hand sync state machine (pending/flushing/flushed/needs-reflush) for Flush now + on-finish autoflush; honours opts.autoDelete
replay.js         per-hand step extraction + Replay state machine for the scrubber
readable.js       transforms a round into the JSON shape used by Export readable
cards.js          SVG card renderer (60x78 regular deck; PNG faces for J/Q/K)
users.js          userId -> displayName / avatar index scraped from stored payloads
history.html      Game History page shell + inline replay template
history.css       History page styling (navy palette, rounded cards, felt + scrubber)
history.js        loads + renders tables, inline replay panels, live-updates
DATA_FORMAT.md    protocol-only reference for interpreting captured traffic
RELEASE_CHECKLIST.md  end-to-end smoke test you should run pre-release
assets/           card portraits (Jx/Qx/Kx PNG), card back (X.png), holdem logo
icons/            16 / 32 / 48 / 128 px PNG icons
```

## Permissions, explained

| Permission         | Why                                                                     |
| ------------------ | ----------------------------------------------------------------------- |
| `webRequest`       | Observe network requests on casino.org (no blocking, no modification)   |
| `storage`          | Persist captured data locally in `chrome.storage.local`                 |
| `tabs`             | Associate captures with their source tab; open History as a full tab   |
| `unlimitedStorage` | Allow large rolling buffers without eviction                            |
| `alarms`           | Periodic in-process index reconciliation; keeps service worker awake   |
| `downloads`        | Trigger the `.casinodump` / readable-JSON file downloads on Export      |
| `host_permissions` | Limited to `https://*.casino.org/*` plus the configured flush endpoint  |

The extension is **completely inert on every other site** — it does not
inject, observe, or store anything outside the listed origins.

## Non-goals

- No request blocking or modification.
- No automatic uploads, no telemetry, no analytics. Network egress
  happens **only** when you click `Flush now` or upload a `.casinodump`
  yourself.
- No multi-account / cloud sync — all state is per-profile local storage.

## Reloading after edits

Edit any file, then go to `chrome://extensions` and click the circular
**Reload** button on the extension card. Hard-refresh (`Ctrl/Cmd+Shift+R`)
the casino.org tab to re-run the content script. The History tab will pick
up new captures live via `chrome.storage.onChanged`.
