NebulaBrowser/documentation/BIG_PICTURE_MODE.md

# Big Picture Mode - Steam Deck & Controller UI

Nebula Browser includes a **Big Picture Mode** - a controller-friendly, console-style interface designed for Steam Deck, handheld devices, and living room setups.

## 🚀 Single Window Architecture

Big Picture Mode now opens **in the main window** instead of a separate window. This design:
- **Keeps resources low** - No extra Electron window process
- **Prevents SteamOS conflicts** - When auto-launching in Gaming Mode, Steam won't create a desktop mode alongside, preventing Steam from overriding controls to emulate keyboard/mouse
- **Seamless switching** - Navigate between Desktop and Big Picture modes smoothly

## ⚠️ Steam Deck: Disabling Mouse Emulation

If Steam is emulating mouse/keyboard input with the joysticks (overriding native controller support), you need to configure Steam Input:

### Quick Fix - Steam Launch Options

Add this to your Steam launch options (Right-click → Properties → Launch Options):

```bash
SDL_GAMECONTROLLER_ALLOW_STEAM_VIRTUAL_GAMEPAD=0 STEAM_INPUT_ENABLE_VIRTUAL_GAMEPAD=0 %command% --big-picture
```

### Recommended Fix - Disable Steam Input Per-Game

1. In Steam, right-click **Nebula** → **Properties** → **Controller**
2. Set **"Override for Nebula"** to **"Disable Steam Input"**
3. This completely disables Steam's input emulation for this app

### Using the Steam Deck Launcher Script

For the easiest setup, use the included launcher script:

1. Set Steam launch options to: `./start-steamdeck.sh`

The script automatically sets all necessary environment variables.

See [README-STEAM.md](../README-STEAM.md) for detailed troubleshooting.

---

## Features

### 🎮 Controller Support
- **Full gamepad navigation** - Use D-pad or left stick to navigate
- **Button mapping**:
  - **A / Cross** - Select/Activate
  - **B / Circle** - Go Back
  - **Y / Triangle** - Quick Search
  - **Start** - Toggle Settings
- **Audio feedback** for navigation

### 📱 Optimized for Steam Deck
- **1280x800 native resolution** support
- Automatic detection of Steam Deck screens
- Large touch-friendly UI elements
- Fullscreen immersive experience

### 🎨 Modern Console-Style UI
- Inspired by Steam OS Big Picture and Xbox Dashboard
- Smooth animations and transitions
- Glowing focus indicators
- Dark theme optimized for OLED displays

### ⌨️ On-Screen Keyboard
- Built-in virtual keyboard for controller input
- URL and search input support
- Special keys for common domains (.com, .org, etc.)

## How to Access

### From Desktop Mode
1. **Menu Button (☰)** → Click **"🎮 Big Picture Mode"**
2. **Settings** → **General** → Click **"Launch Big Picture Mode"**

### Keyboard Shortcut
- Press `F11` while in Big Picture Mode to toggle fullscreen

### Automatic Detection
If Nebula detects a Steam Deck-sized display (1280x800), it will suggest Big Picture Mode in settings.

### Auto-start in SteamOS Gaming Mode
When Nebula is launched from SteamOS **Gaming Mode** (gamescope / Steam gamepad UI), it will automatically start in **Big Picture Mode**.

You can override this behavior:
- Force Big Picture at launch: launch options `--big-picture` (or `--bigpicture`)
- Disable Big Picture auto-start: launch options `--no-big-picture` (or `--no-bigpicture`)
- Environment overrides: `NEBULA_BIG_PICTURE=1` / `NEBULA_NO_BIG_PICTURE=1`

## Navigation Sections

| Section | Description |
|---------|-------------|
| **Home** | Quick access sites, search, and recent browsing |
| **Bookmarks** | Your saved websites in a tile grid |
| **History** | Recently visited sites |
| **Downloads** | Downloaded files |
| **NeBot AI** | Launch the AI assistant |
| **Settings** | Theme, privacy, and display options |

## Controller Button Reference

| Button | Action |
|--------|--------|
| D-Pad / Left Stick | Navigate between elements |
| A / Cross | Select focused element |
| B / Circle | Go back / Close menu |
| Y / Triangle | Open search (on-screen keyboard) |
| Start | Open/Close settings |
| LB/RB | Scroll horizontally |

## Exiting Big Picture Mode

- Press the **Exit** button in the top-right corner
- Go to **Settings** → **Desktop Mode**
- Press `Escape` key multiple times

## Technical Details

### Files
- `renderer/bigpicture.html` - Main HTML structure
- `renderer/bigpicture.css` - Console-optimized styles
- `renderer/bigpicture.js` - Controller handling and navigation

### Screen Detection
Big Picture Mode is suggested for displays matching:
- Steam Deck resolution: 1280×800
- Screens smaller than 1366px width
- 16:10 or 16:9 aspect ratios

### API
```javascript
// Check if Big Picture Mode is recommended
const suggested = await window.bigPictureAPI.isSuggested();

// Get screen information
const info = await window.bigPictureAPI.getScreenInfo();

// Check if currently in Big Picture Mode
const isActive = await window.bigPictureAPI.isActive();

// Launch Big Picture Mode (navigates main window)
await window.bigPictureAPI.launch();

// Exit Big Picture Mode (navigates back to desktop UI)
await window.bigPictureAPI.exit();
```

## Customization

The Big Picture Mode respects your theme settings. Colors are applied from your selected theme:
- Background colors
- Accent and primary colors  
- Text colors

## Known Limitations

- Some complex web forms may be difficult to navigate with controller only
- Video players use native controls
- Right-click context menus require mouse/touch

## Future Improvements

- [ ] Rumble/haptic feedback for compatible controllers
- [ ] Voice search integration with NeBot
- [ ] Picture-in-picture mode for videos
- [ ] Game overlay mode
- [ ] Custom controller mappings