Smart TVs (Tizen, WebOS, Fire TV, Bravia) have no accessible browser
devtools, so when the player misbehaves on those platforms we previously
had zero visibility. This adds two paths to fix that:
- Visible debug overlay rendered on the TV screen for phone-photo capture
- Automatic server-side telemetry sink for hands-off error reporting
Client side (server/player/):
- Inline ES5 error trap as first script in index.html captures errors
even from parse-time failures in later scripts. Captures into
window.__debugLog with 200-entry cap.
- debug-overlay.js renders a fixed-position overlay covering the top 40%
of the screen. Activates via ?debug=1, d-e-b-u-g key sequence, Samsung
red button (keyCode 403), or smart-TV UA + ?autodebug=1. Freeze toggle
(F key or Samsung green) with visible FROZEN badge for phone capture.
pointer-events: none so touches pass through to the player underneath.
- Reporter machinery posts captured errors to /api/player-debug with
5-second debounce batching, sendBeacon on unload (with payload size
capping to stay under 64KB), 5-minute backoff after 429 responses.
UA-gated: smart-TV allow-list first (handles Tizen-with-Chrome/108),
modern-desktop deny-list second, default-report for unknown UAs.
- Two-pass djb2 fingerprint (16 hex chars) per error for future grouping.
- Absolute script src (/player/debug-overlay.js) so the script loads
regardless of trailing-slash on the player URL.
Server side:
- New player_debug_logs table (10000-row FIFO cap, indexed on
fingerprint + created_at). Schema in schema.sql, idempotent via
CREATE TABLE IF NOT EXISTS.
- POST /api/player-debug unauthenticated (so unpaired players can also
report), rate-limited 10/min/IP, per-field length caps to prevent abuse.
- Dynamic /player HTML route injects window.__playerConfig.debugReporting
based on PLAYER_DEBUG_REPORTING env var (defaults on; =off suppresses
all client telemetry traffic). Other player assets still served static.
- Admin routes (requireAuth + requireSuperAdmin):
GET /api/player-debug/list with pagination and filters
GET /api/player-debug/summary for UA family counts
DELETE /api/player-debug/older-than for manual purge
Admin view (#/admin/player-debug):
- UA family summary at top (Tizen/WebOS/Fire TV/Bravia/Edge/Chrome/etc)
- Filter row: UA contains, date range, has-error checkbox
- Paginated table with expand-row JSON viewer for error_data and context
- device_id labeled (self-reported) since field is unauthenticated input
- Manual delete-older-than button with confirmation dialog
Verified end-to-end with Playwright + Chromium (17/17 checks pass) plus
manual real-browser verification including UA-spoofed Tizen flow landing
rows in the admin view.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
