playbooks

home / skills / dbobkov245-source / pwa-torserve / debug-remote

debug-remote skill

/skills/debug-remote

This skill helps you debug TV apps remotely by collecting logs and telemetry from the TV environment for faster fixes.

npx playbooks add skill dbobkov245-source/pwa-torserve --skill debug-remote

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.9 KB
---
name: debug-remote
description: Specialist in debugging TV apps remotely (logs, telemetry).
---

# Remote Debugging for TV

Debugging a TV app is hard. `console.log` is invisible on the TV screen.
Use this skill to capture logs and errors from the TV environment.

## 📡 Remote Logging Strategy

### 1. The "On-Screen Console" Overlay
For quick debugging without a laptop connection.
- **Trigger:** Konami Code (Up, Up, Down, Down, Left, Right, Left, Right, B, A) or hidden button.
- **UI:** A simple fixed-position `<div>` with `overflow-y: scroll`, semi-transparent background, high contrast text.

```javascript
/* Simple Logger Utility */
const originalLog = console.log;
console.log = (...args) => {
  originalLog(...args);
  if (window.debugOverlay) {
    window.debugOverlay.innerHTML += `<div>${args.join(' ')}</div>`;
  }
};
```

### 2. Network Logging (Remote Spy)
Send logs to a remote server or simple webhook (e.g., `webhook.site` for temp debugging).

```javascript
const LOG_ENDPOINT = 'https://your-log-drain.com/ingest';

function remoteLog(level, message) {
  fetch(LOG_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify({ level, message, timestamp: Date.now() })
  }).catch(() => {}); // Fire and forget
}
```

### 3. ADB Logcat (The Gold Standard)
If you have ADB access:
- **Command:** `adb logcat | grep "Chromium"`
- **Filter:** Use a unique prefix in your logs: `console.log("[PWA]", ...)` -> `grep "\[PWA\]"`

## 🐛 Common TV Bugs to Watch
- **Focus Traps:** Focus goes to an invisible element or gets stuck.
- **Memory Leaks:** Large images not being garbage collected. Monitor heap size if possible.
- **Network Timeouts:** TV WiFi is often worse than phone WiFi.
- **Clock Skew:** TV system time might be wrong (SSL errors).

## 🛠 Usage
Implements a global `window.__DEBUG__` object to toggle modes:
- `window.__DEBUG__.enableOverlay()`
- `window.__DEBUG__.disableOverlay()`
- `window.__DEBUG__.setRemoteServer(url)`

Overview

This skill helps you capture and inspect logs, errors, and telemetry from TV apps remotely. It focuses on practical tools for on-screen logging, network-forwarding of logs, and leveraging ADB logcat when available. The goal is fast reproduction and diagnosis of platform-specific issues that are invisible on TV screens.

How this skill works

It injects a lightweight on-screen console overlay that surfaces console output directly on the TV and provides a remote logging option to forward events to a webhook or log drain. When ADB is available, it recommends filtered logcat usage and a unique log prefix to extract relevant lines. A global debug object lets you toggle overlay and configure the remote endpoint at runtime.

When to use it

  • When console.log output is not visible on the TV screen.
  • When you need live observation of runtime errors during manual QA on a TV device.
  • For remote teams to capture logs from testers who cannot run ADB.
  • When intermittent issues require persistent, timestamped telemetry for later analysis.

Best practices

  • Use a unique log prefix (e.g., [APP]) so ADB or server-side filters can extract only your app logs.
  • Keep the overlay lightweight and toggleable to avoid UI interference during normal use.
  • Send logs fire-and-forget to a secure endpoint; avoid blocking UI with large synchronous requests.
  • Redact or avoid sending sensitive user data in remote logs; use sampling for high-volume events.
  • Fallback to ADB logcat for full system context when you can connect a device physically.

Example use cases

  • Enable the on-screen console with the Konami code during a QA session to reveal hidden errors without a laptop.
  • Configure the remote server URL in the debug object to collect logs from remote testers via a webhook.
  • Use adb logcat | grep "[APP]" to capture crash traces and Chromium network errors when debugging playback failures.
  • Capture focus and input events on TV to diagnose focus traps that break navigation with the remote control.
  • Add lightweight telemetry for image loading and memory hints to detect leaks or heavy memory usage on TVs.

FAQ

How do I enable the overlay without changing production code?

Expose a runtime toggle in the global debug object and ship the overlay code behind a feature flag so it can be activated via a remote config or hidden input sequence.

Is remote log forwarding secure?

Use HTTPS endpoints, authenticate log drains when possible, and avoid sending PII. For temporary debugging, use ephemeral webhooks but rotate or disable them afterward.