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
• 🎯 Focus memory - Captures and restores the host application's focused element when the console gains/releases focus
• 🖱️ Safe keyboard takeover - Focus only activates when the console is visible; all event listeners are removed on destroy

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.3/index.umd.min.js"></script>

When using CDN, the library is available globally. You may need to access it in one of these ways:

<script>
	// Method 1: Direct access (most common)
	const tvConsole = new TVConsole()

	// Method 2: If the above doesn't work, try:
	const TVConsoleConstructor =
		window.TVConsole && window.TVConsole.TVConsole
			? window.TVConsole.TVConsole
			: window.TVConsole && window.TVConsole.default
				? window.TVConsole.default
				: window.TVConsole
	const tvConsole = new TVConsoleConstructor()

	// Test it
	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 a subtle outline on the console when focused (no layout shift) |

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() - Unfocus (restoring previously focused element), remove all event listeners, and remove the overlay

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 sequence to focus console (ignored when hidden)
	unfocusKey: 'Escape', // Key to unfocus console
	enableKeyboardNav: true, // Enable arrow key scrolling
	showFocusIndicator: true, // Show subtle outline when focused
	onFocus: () => {
		// Handle focus gain (e.g., pause app, show instructions)
	},
	onUnfocus: () => {
		// Handle focus loss (e.g., resume app functionality)
		// Previously focused host element is restored automatically
	},
})

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 — only works when the console is visible
• When focused, the console shows a subtle outline indicator (no layout shift)
• On focus, the library captures the host application's currently focused element
• Use arrow keys to scroll through log history
• Press Escape to unfocus — the previously focused host element regains focus automatically

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.3

• Focus memory: host application's focused element is captured on console focus and restored on unfocus or destroy
• Focus visibility guard: focus key sequence is ignored when the console is hidden
• Outline-based focus indicator: replaced green border/glow with outline: 2px solid currentColor (no layout shift)
• Lifecycle cleanup: destroy() now restores focus memory and removes all document event listeners
• setConfig({ enabled }) transitions: switching enabled from true→false calls destroy(); false→true calls initialize()

1.0.0

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