Sports Box

Introduction

Sports Box is a multiview dashboard for a slate of live games. The UI is React. It ships inside a Manifest V3 extension, so game day does not depend on a local dev server. One to sixteen panels, four matrix presets, per-panel mute, Fill video, scorebugs, and a phone keypad on the same Wi-Fi.

Source: github.com/mitchelldawkinsjr/sports-box. The story is in A TV Wall in One Browser Window.

Status: Active — v1.7.0. Load unpacked from extension/ after npm run build:ext.

Problem & Solution

The Problem

• Tabs fight for audio. Unmuting one game rarely mutes the others, and embed pages set muted back themselves.
• Frame headers blank the panel. X-Frame-Options and CSP frame-ancestors stop a second site from rendering inside the dashboard.
• Login sites do not work in an iframe. Session cookies are not sent, so ESPN and the subscription apps sit on a spinner.
• The score is in another tab. Leaving the picture to check a ticker means you miss the play you opened the wall to see.
• The wall is full screen. Changing audio from the laptop means getting up.

The Solution

1. Bundle the dashboard in the extension and open it from the toolbar icon
2. Strip frame-blocking response headers with declarativeNetRequest so pasted pages can render in panels
3. Own mute in the page world, scoped per panel, with solo as the default unmute
4. Dock login-gated sites as real Chrome windows and mirror the picture into the panel
5. Read public scoreboards in the page, link a game to a panel, and alert on close games
6. Run a LAN hub when you want the phone as a keypad

Architecture

Message flow

Dashboard  --postMessage-->  bridge.js  --runtime.sendMessage-->  background.js
                                                                  │
                                    scripting.executeScript  <----┤
                                    (one panel's frame tree)      │
                                                                  │
Login-gated URL  -->  chrome.windows.create (snapped to the panel)
                      tabCapture stream id  -->  muted <video> in the panel

The dashboard never holds extension privileges. It asks. The service worker does the Chrome work.

Embed routing

resolveEmbed in src/utils/embedUrl.ts decides before a panel mounts:

YouTube and Twitch mute through their player APIs. The iframe URL stays stable so a mute click does not remount the stream.

Audio

Solo writes muted: false on one slot and muted: true on the rest. The panel button, ⌘/Ctrl+1…9 (0 for channel 10, Shift for 11–16), a ticker click on an already-linked game, and the phone solo command all call it. A plain mute toggle still changes one slot, for the times you want two feeds. Volume 0 counts as muted. Unmuting a slot whose volume is stuck at 0 restores it to 1.

mute-main.js is registered with "world": "MAIN" and "all_frames": true. Isolated content scripts cannot patch HTMLMediaElement.prototype.play, and player bundles call play() on their own timer. The page-world script remembers the last mute and volume, reapplies them on every media node it can see (including open shadow roots), and relays the same payload into child iframes.

Each panel iframe is named sb-${slotId}. Audio injection is targeted at that frame tree. A command for channel 3 does not walk channel 4.

Docked sessions use chrome.tabs.update({ muted }) on the popup tab. attachTabMirror plays the tab-capture stream into the panel with the element muted. Sound stays on the source tab, so panel mute is not applied twice.

Fill video

focusPanel resolves frames in two passes:

1. chrome.webNavigation.getAllFrames for URLs that loosely match the panel URL
2. An isolated probe for window.name === "sb-${panelId}"

collectFrameTree then grows the set by parent id until the nested player frames are included. There is no fallback to "every frame." If nothing matches, Fill video no-ops instead of cropping the wall.

content.js picks a target by scoring videos (playing, readyState, pixel area) and iframes (area, plus a bonus for player-like URLs, minus a penalty for ad URLs). focus.css sets visibility: hidden on the page and position: fixed; inset: 0 on .sports-box-target. Spectrum URLs get ?sportsbox=1 so the crop can arm from the query string as well as from an explicit Fill click.

Scoreboard

src/utils/scoreboard.ts polls ESPN's site scoreboard for nfl, cfb, nba, and wnba. (site.api.espn.com is often blocked; site.web.api.espn.com returns the same scoreboard JSON.)

A panel stores an optional gameId. The scorebug reads that game. The ticker can filter to any non-empty subset of the four leagues.

CFBD is enrichment, not the live feed:

isCloseGameWorthWatching is period-aware. Football: margin ≤ 3 late in the third, ≤ 8 in the fourth or overtime. Basketball: margin ≤ 5 late in the third, ≤ 8 in the fourth or overtime. The banner is deduped per game id in sessionStorage and names the linked channel when there is one.

Remote hub

scripts/remote-hub.mjs listens on 0.0.0.0:8787.

A wrong PIN is a 403. Commands are a closed union in parseRemoteCommand: solo, select, volume, mute, mute-all, layout, count, swap, move, showtime, watch, edit, focus. Unknown shapes are dropped before they touch React state.

Layouts and storage

layoutGridStyle maps four modes onto CSS grid. Hero (1+N) gives panel 0 column 1, spanning count - 1 rows, and stacks the rest in column 2. Equal, 3-col, and wide set column counts and even rows.

localStorage keys:

Run it

git clone https://github.com/mitchelldawkinsjr/sports-box.git
cd sports-box
npm install
npm run build:ext

Chrome → chrome://extensions → Developer mode → Load unpacked → the extension/ folder. Click the toolbar icon.

Phone keypad, same Wi-Fi, hub left running:

npm run remote

Open Sports Box → Remote → scan the QR. Optional TV networks: copy .env.example to .env.local and set VITE_CFBD_API_KEY, then rebuild the extension.