Debug Mode

Debug Mode is an on-device diagnostic overlay for operators troubleshooting a remote viewer or Samsung TV kiosk without access to browser devtools. It exposes live transport state, connection info, build identity, service worker status, and a rolling 200-entry console log tail.

How to activate

  1. Append ?debug=1 to any room URL (for example /r/your-room-id/viewer?debug=1).
  2. A red warning banner appears at the top of the page. Click I understand to acknowledge the safety warning.
  3. The overlay renders in the bottom-right corner and stays there until the tab is closed or ?debug=1 is removed from the URL.
Per-tab scope: Acknowledgement is per browser tab. Opening the same URL in a new tab re-prompts the warning banner. This is intentional — it keeps audience-facing TVs safe from accidental exposure if a URL is reused.

What you see

The overlay contains five panels:

  • Transport — current timer state (stopped / running / paused), active timer id, and anchor fields used to diagnose drift between devices.
  • Connection — total number of connected devices, your own connection id and connection type, and the full list of connected devices in the room.
  • Build — git SHA, build timestamp, and app version. Use this to confirm a remote TV is running the expected bundle after a deploy.
  • Service Worker — whether a new bundle is waiting to activate. Useful for verifying that a TV picked up the latest update.
  • Console — the last 200 console.log, console.warn, console.error, uncaught errors, and unhandled promise rejections. Refreshes once per second. Newest entries appear at the top.

Safety warning

Warning: Debug content may include internal identifiers such as Firebase project ids, connection ids, and UIDs. Do NOT screen-share, record, or post screenshots of a debug-active session publicly. Close the tab when done — that clears the acknowledgement.

Send Debug Report

Below the Console panel you'll find a Send Debug Report button. Clicking it captures a single snapshot of everything the overlay currently shows — transport state, connection info, build identity, service worker status, and the last 200 console entries — and writes it to a room-scoped Firestore subcollection at rooms/{roomId}/debugReports/{id}. The room owner or an admin can then read the report later from the Firebase console for post-mortem review.

After a successful upload the button shows Sent ✓ for three seconds, then enters a 30-second cooldown so accidental double-taps cannot flood the subcollection. The button label counts down ("Send (24s)") until it unlocks.

Access: Only the room owner or a tenant admin can read uploaded reports. Plain room members and viewers cannot. Reports auto-expire after 30 days via Firestore TTL — no manual cleanup required.

What Debug Mode does not do

  • Debug Mode does not upload anything automatically. The Console panel only writes to Firestore when you explicitly click Send Debug Report.
  • Debug Mode does not alter timer behavior, audience-visible output, or other live Firestore documents. The overlay is read-only; the Send button writes exactly one diagnostic document per click.
  • Debug Mode does not persist between tabs or page reloads. Every new tab starts fresh and requires a new acknowledgement.