TV Console

A console replacement for TV apps where browser console is not accessible. This package provides an on-screen console overlay that captures and displays console output in real-time.

Features

• 🖥️ On-screen console overlay - View console output directly on your TV app
• 🔄 Real-time logging - Automatically captures all console methods (log, info, warn, error, debug)
• 🎨 Customizable styling - Configure colors, position, size, and appearance
• 📱 TV-optimized - Designed for smart TV applications and set-top boxes
• 🔧 Flexible configuration - Enable/disable, filter log levels, custom formatting
• 📊 Log management - Export logs, clear console, show/hide overlay

Installation

npm install tv-console

CDN Usage

You can also use TV Console directly from CDN:

<!-- Using unpkg -->
<script src="https://unpkg.com/[email protected]/dist/index.umd.min.js"></script>

<!-- Using jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.umd.min.js"></script>

<!-- Using CDNJS (once approved) -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/tv-console/1.0.2/index.umd.min.js"></script>

When using CDN, the library is available globally as TVConsole:

<script>
  const tvConsole = new TVConsole();
  console.log('Hello from CDN!');
</script>

Quick Start

import { TVConsole } from 'tv-console';

// Initialize with default settings
const tvConsole = new TVConsole();

// Your existing console calls will now appear on screen
console.log('Hello TV World!');
console.error('Something went wrong');
console.warn('Warning message');

Configuration

import { TVConsole } from 'tv-console';

const tvConsole = new TVConsole({
  enabled: true,
  position: 'bottom-right',
  backgroundColor: 'rgba(0, 0, 0, 0.9)',
  textColor: '#00ff00',
  fontSize: '16px',
  maxEntries: 200,
  showTimestamp: true,
  showLogLevel: true,
  logLevels: ['log', 'error', 'warn'], // Only show these levels
  zIndex: 10000
});

API Reference

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable/disable the TV console | | maxEntries | number | 100 | Maximum number of log entries to keep | | position | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | 'top-right' | Position of the console overlay | | width | string | '400px' | Width of the console overlay | | height | string | '300px' | Height of the console overlay | | backgroundColor | string | 'rgba(0, 0, 0, 0.8)' | Background color of the overlay | | textColor | string | '#ffffff' | Text color | | fontSize | string | '14px' | Font size | | opacity | number | 0.9 | Opacity of the overlay | | showTimestamp | boolean | true | Show timestamp with each log entry | | className | string | 'tv-console' | CSS class for styling | | zIndex | number | 9999 | Z-index of the overlay | | showLogLevel | boolean | true | Show log level indicators | | logLevels | LogLevel[] | ['log', 'info', 'warn', 'error', 'debug'] | Filter which log levels to display | | formatter | (entry: LogEntry) => string | Default formatter | Custom formatter for log messages | | focusKey | string | '12345' | Key combination to focus the console | | unfocusKey | string | 'Escape' | Key to unfocus the console | | onFocus | () => void | () => {} | Callback when console gains focus | | onUnfocus | () => void | () => {} | Callback when console loses focus | | enableKeyboardNav | boolean | true | Enable keyboard navigation for scrolling | | showFocusIndicator | boolean | true | Show focus indicator when console is focused |

Instance Methods

Logging Methods

• log(...args: any[]) - Log a message
• info(...args: any[]) - Log an info message
• warn(...args: any[]) - Log a warning message
• error(...args: any[]) - Log an error message
• debug(...args: any[]) - Log a debug message

Console Control

• show() - Show the console overlay
• hide() - Hide the console overlay
• toggle() - Toggle visibility
• clear() - Clear all log entries
• destroy() - Remove the console overlay and restore original console

Focus Management

• focus() - Focus the console for keyboard navigation
• unfocus() - Unfocus the console
• isFocused(): boolean - Check if console is currently focused

Data Management

• getLogs(): LogEntry[] - Get all current log entries
• setConfig(config: Partial<TVConsoleConfig>) - Update configuration
• exportLogs(): string - Export logs as formatted text

Usage Examples

Basic Usage

import { TVConsole } from 'tv-console';

// Initialize
const tvConsole = new TVConsole();

// Your app code
function handleUserAction() {
  console.log('User clicked button');
  console.info('Processing request...');
  
  try {
    // Some operation
    console.log('Operation successful');
  } catch (error) {
    console.error('Operation failed:', error);
  }
}

Advanced Configuration

import { TVConsole } from 'tv-console';

const tvConsole = new TVConsole({
  position: 'bottom-left',
  backgroundColor: 'rgba(0, 20, 40, 0.95)',
  textColor: '#00ff88',
  fontSize: '18px',
  maxEntries: 50,
  logLevels: ['error', 'warn'], // Only show errors and warnings
  formatter: (entry) => {
    return `[${entry.timestamp.toLocaleTimeString()}] ${entry.message}`;
  }
});

// Show console when app starts
tvConsole.show();

TV Remote Control Support

The TV Console includes built-in support for TV remote controls and keyboard navigation:

const tvConsole = new TVConsole({
  focusKey: '12345',        // Key combination to focus console
  unfocusKey: 'Escape',     // Key to unfocus console
  enableKeyboardNav: true,  // Enable arrow key scrolling
  showFocusIndicator: true, // Show green border when focused
  onFocus: () => {
    console.log('Console gained focus - pausing app functionality');
    // Handle focus gain (e.g., pause app, show instructions)
  },
  onUnfocus: () => {
    console.log('Console lost focus - returning to app');
    // Handle focus loss (e.g., resume app functionality)
  }
});

Keyboard Navigation (when focused):

• Arrow Up/Down - Scroll up/down by 20px
• Page Up/Down - Scroll up/down by one page
• Home - Scroll to top
• End - Scroll to bottom
• Escape - Unfocus console

Focus Management:

• Type 12345 (or your custom key combination) to focus the console
• When focused, the console shows a green border indicator
• Use arrow keys to scroll through log history
• Press Escape to unfocus and return to your app

Conditional Console

import { TVConsole } from 'tv-console';

// Only enable in development
const isDevelopment = process.env.NODE_ENV === 'development';
const tvConsole = new TVConsole({
  enabled: isDevelopment,
  position: 'top-right'
});

// Conditionally show console
if (isDevelopment) {
  tvConsole.show();
}

Custom Styling

/* Custom CSS for the console overlay */
.tv-console {
  border: 2px solid #00ff00;
  border-radius: 8px;
  font-family: 'Courier New', monospace;
}

.tv-console-error {
  color: #ff4444;
  font-weight: bold;
}

.tv-console-warn {
  color: #ffaa00;
}

.tv-console-info {
  color: #44aaff;
}

Browser Support

This package works in all modern browsers that support:

• ES2020 features
• DOM manipulation
• CSS Grid/Flexbox

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Changelog

1.0.0

• Initial release
• Basic console overlay functionality
• Configurable styling and positioning
• Log level filtering
• Export functionality