, bottom drawer, FAB │ ├── chat-drawer.js # reads chat DOM, opens WS hook, swaps a panel in │ └── icons/ # 16/32/48/128 PNGs └── README.md ``` ### 3.2 Run-time flow ``` [beat-battle.net page] │ ▼ [MATCH chrome:// extension loaded on this URL] │ inject.css applied ←────────────────────────────┐ │ │ ▼ │ [detector.js] ── MutationObserver on document.body │ detects: │ • .bb-room-overlay (in-game) │ • .bb-footer-nav-main-fade (home menu) │ • route change (pushState via patchHistoryState) │ │ │ ▼ │ [layout.js] runs: │ 1. Hide desktop-only side panels (display:none) │ 2. Re-flow main grid to 1 column │ 3. Inject FAB ("💬") bottom-right for chat │ 4. Mount at body end │ │ │ ▼ │ [chat-drawer.js] only when in-game: │ 1. Snapshot DOM of chat list (clone, don't move) │ 2. Wrap WebSocket to intercept {type:"room.chat.send"} messages and re-emit through the site's own React reducer (proxy.send) 3. Render in , swipe-up to expand │ │ │ └──── re-attach on every route change ───────┘ ``` ### 3.3 Selector strategy (defensive) Beat-battle uses Tailwind — class names are stable but utility-built. We don't rely on those. We rely on: 1. **Stable semantic hooks** the dev used: - `bb-room-overlay` (their own naming, low-renaming risk) - `bb-menu-item`, `bb-login-chip`, `bb-footer-nav-main-fade` - `data-` attributes when we find them (they use very few — we'll add some via `MutationObserver` for the bits we need) 2. **Text fingerprinting** as a fallback (DOM nodes containing exact i18n strings like `"PLAY"` / `"CREATE ROOM"` / `"LOG IN WITH DISCORD"`) 3. **Structural position** as last resort (`body > div:nth-child(N) > …`) Every selector has a fallback chain: ```js const chatInput = document.querySelector('.bb-chat-input') || document.querySelector('textarea[placeholder*="chat" i]') || document.querySelector('[aria-label*="message" i]') || [...document.querySelectorAll('textarea')].find(t => /chat|message|comment/i.test(t.placeholder)); ``` --- ## 4. V1 scope (the actual mobile pain) | Screen | What we do | |---|---| | **Home (`/`)** | Single-column menu. Big thumb-sized buttons. Login chip pinned top-right (already in their nav, just unstick it for mobile). Hide desktop leaderboard sidebar on `< 768px`. | | **Lobby list** | Card per lobby, full-width, drag-to-refresh. | | **In-game room** | Player list at the top (horizontal scroll on mobile). Score/timer pinned to top-safe. Kit / upload / vote actions always visible (sticky bottom action bar). | | **Chat drawer** | New: a **bottom sheet**, hidden by default, pulls up over the game when the FAB is tapped. States: closed → peeking (last message preview) → expanded (full scrollback + input). Sends through the site’s WS so messages count. | | **Settings/profile/events/shop** | Out of scope for V1. Desktop-equivalent — link the user to the original page in the same tab and don't restyle. | Things we explicitly **don't** do in V1: - Affective style matching (their site is a "brutalist" red-grid; we keep it) - Native push, voice chat, anything requiring permissions - A settings page (no point until V2) - iOS Safari — Chromium only for V1 --- ## 5. Chat drawer — how sending works (the tricky bit) Their chat send is React-internal: an action `LOBBY_CHAT_SEND_OPTIMISTIC` that fires before the WebSocket round-trip. We can't reach into React's state, but we **can** make the existing textarea + send button work in the drawer's expanded mode: 1. **Read:** the existing chat scrollback is a DOM node we can either: - **(a) Clone** its contents into our drawer (read-only display), OR - **(b) Move** the node into our drawer (write-through). We do (a) — it's less invasive and the original UI still works if the user closes the drawer. 2. **Send:** instead of cloning the React send flow, we - Place a `

` inside our drawer
   - On submit, **dispatch a real keyboard event** on the original site's
     chat textarea + a click on its submit button (or `Enter` keydown). This
     keeps every server-side guard intact (rate limit, mute, profanity filter).
3. As a backup, we'll **wrap `WebSocket.prototype.send`** at the page level
   and **proxy the `room.chat.send` message type** — if the UI send fails we
   can fall back to direct socket write. Only enable this if the dispatch-
   event path doesn't fire.

The drawer closes if the user navigates to another route (history change).

---

## 6. Tech choices

- **Vanilla TS + esbuild**, no React. A browser extension content script
  with React in it is doable but pointless overhead — DOM widgets only.
- **No external CDN deps.** Self-contained. SFX, fonts, icons bundled.
- **Build pipeline:** `esbuild extension/content/*.ts → dist/*.js`, then
  zip the dist for `.zip` upload to Chrome Web Store.
- **Manifest V3** for Chromium. Firefox accepts MV3 too (Manifest V3 is
  fully supported in FF 109+), so a single manifest works for both.
- **`chrome.storage.sync`** for any tiny per-user prefs (chat drawer collapsed
  by default, etc.) — no remote config.
- **Permissions:** `storage`, `*://beat-battle.net/*` host permission. No
  `tabs`, no `webRequest`, no `scripting` for any domain other than the one
  we explicitly match. (Web Store review will appreciate this minimal
  surface.)

---

## 7. Files & approximate LOC

```
extension/manifest.json            30 lines
extension/background.js            25  (very little — reload on update)
extension/content/inject.css      200  (mobile overrides)
extension/content/detector.ts      90  (route + overlay observer)
extension/content/layout.ts       220  (menu reflow, in-game shell restructure)
extension/content/chat-drawer.ts  280  (drawer + send-bridge)
extension/content/util/selectors.ts 80
extension/content/util/ws-proxy.ts 60
────────────────────────────────────
                                   ~985 LOC total
                                   1 weekend for V1
```

---

## 8. V2 / future (NOT in V1)

- Spotify/YouTube kit import (if their beat-making flow accepts URL refs)
- Theme matching their `bb-accent` (read CSS vars, mirror into drawer)
- iOS Safari port (uses WebExtension API subset)
- Native app wrapper for Play Store
- Friend-list integration (if they expose one)

---

## 9. Risks & open questions

1. **Their WS auth.** A browser extension on a `.net` origin shares cookies.
   If chat requires the WS session cookie, our send-event will work because
   **the same browser session is making the WS call from the page, not from
   our extension code**. If they bind WS to a per-tab token (we couldn't
   confirm either way in the JS dump), we'd need to extract that token via a
   `MutationObserver` on the WS handshake. **Action:** log everything the
   page sends on first send, verify it's cookie-auth-only.

2. **Class name churn.** Tailwind classes change on every commit. Mitigation:
   selectors prioritize text content, structural position, semantic
   attributes — not utility classes.

3. **CWS review.** Naming: "Beat Pocket", tiny description. Privacy
   disclosures: we don't collect any data (only `chrome.storage.sync`,
   none of it leaves the device). Should be a smooth pass.

4. **ToS.** "No reverse engineering, no automated scraping" — we're not
   doing either. We restyle what the user is already viewing. Will add a
   short statement in the privacy tab of the CWS listing making this clear.

5. **Server action drift.** If they change `LOBBY_CHAT_SEND_OPTIMISTIC`'s
   contract, our event-dispatch send breaks. Mitigation: the WS-proxy
   fallback in §5.

6. **iOS Safari.** Not in V1; revisit after V1 ships and we have users.

---

## 10. After you approve

I'll spin up:

1. The directory tree (already done — `/root/.openclaw/workspace/projects/beat-pocket/`)
2. `extension/manifest.json`
3. The five content scripts in TS
4. A README with **install-from-source** instructions (load unpacked) so you
   can try it before CWS submission
5. A small `dev-server` esbuild watch task + a `package.json`
6. Smoke-test on `load unpacked` using Chromium DevTools mobile emulation

Then we can decide together whether V1 covers the real pain or whether we
still need [specific thing you tell me when you test it].

No code written yet — waiting on your go.