# Styrene TUI Keymap Design

This document defines the keybinding hierarchy and conventions for Styrene TUI, following Textual framework best practices.

## Design Principles

Based on [Textual's input handling](https://textual.textualize.io/guide/input/):

1. **DOM-based resolution**: Bindings resolve from focused widget → parent → screen → app
2. **Priority bindings**: Critical app-level bindings use `priority=True` to bypass widget bindings
3. **Context-specific bindings**: Screens/widgets define their own contextual bindings
4. **Consistency**: Same key = same semantic action across contexts where possible

## Binding Hierarchy

```
┌─────────────────────────────────────────────────────────────┐
│ PRIORITY BINDINGS (always work, bypass focus)               │
│   ctrl+q    Quit (emergency exit)                           │
│   ctrl+c    Quit (standard interrupt)                       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ APP-LEVEL BINDINGS (work when no widget overrides)          │
│   q         Quit                                            │
│   ?         Help                                            │
│   ,         Settings (comma - common convention)            │
│   escape    Back / Cancel / Close                           │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ SCREEN-LEVEL BINDINGS (context-specific)                    │
│   Dashboard: p=Provision, s=Status, c=Chat, r=Refresh       │
│   Device:    s=Shell, l=Logs, r=Reboot, u=Update            │
│   Settings:  ctrl+s=Save, escape=Cancel                     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ WIDGET-LEVEL BINDINGS (focused widget only)                 │
│   DataTable: enter=Select, up/down=Navigate                 │
│   Input:     enter=Submit, escape=Cancel                    │
│   TextArea:  Standard text editing keys                     │
└─────────────────────────────────────────────────────────────┘
```

## Key Categories

### Universal Keys (Priority)
These bindings use `priority=True` and work regardless of focus state.

| Key | Action | Description |
|-----|--------|-------------|
| `ctrl+c` | `quit` | Quit application (only way to exit) |

### Global Navigation
App-level bindings that work from any screen unless overridden.

| Key | Action | Description |
|-----|--------|-------------|
| `escape` | `pop_screen` | Go back / cancel |
| `?` | `toggle_help` | Show help overlay |
| `` ` `` | `push_screen_settings` | Open settings (grave accent) |

### Screen-Specific Actions
These keys have different meanings depending on context.

#### Dashboard Screen
| Key | Action | Description |
|-----|--------|-------------|
| `p` | `push_screen('provision')` | Open provision screen |
| `s` | `request_status` | Request device status |
| `c` | `open_chat` | Open chat with selected device |
| `r` | `refresh` | Refresh device list |
| `h` | `toggle_hardware` | Toggle hardware panel |
| `enter` | `select_device` | Select/view device details |

#### Device Detail Screen
| Key | Action | Description |
|-----|--------|-------------|
| `s` | `action_shell` | Open remote shell |
| `l` | `action_logs` | View device logs |
| `r` | `action_reboot` | Reboot device |
| `u` | `action_update` | Update device |

#### Provision Screen
| Key | Action | Description |
|-----|--------|-------------|
| `escape` | `pop_screen` | Cancel and go back |
| `tab` | Focus next field | Standard form navigation |

#### Settings Screen
| Key | Action | Description |
|-----|--------|-------------|
| `ctrl+s` | `save` | Save settings |
| `escape` | `cancel` | Cancel without saving |

#### Inbox Screen
| Key | Action | Description |
|-----|--------|-------------|
| `enter` | `open_conversation` | Open selected conversation |
| `escape` | `pop_screen` | Go back |

#### Conversation Screen
| Key | Action | Description |
|-----|--------|-------------|
| `escape` | `pop_screen` | Go back to inbox |
| `enter` | `send_message` | Send current message |

## Key Allocation Strategy

### Reserved Keys
| Key | Reserved For |
|-----|-------------|
| `ctrl+c` | Quit (only exit method) |
| `?` | Help (global) |
| `` ` `` | Settings (global, grave accent) |
| `escape` | Back/Cancel (universal) |
| `enter` | Select/Confirm (context) |
| `tab/shift+tab` | Focus navigation (system) |

### Context-Reusable Keys
These keys can be reused across screens with different meanings:

| Key | Semantic Meaning |
|-----|-----------------|
| `s` | **S**tatus / **S**hell / **S**ave (context-dependent) |
| `r` | **R**efresh / **R**eboot (context-dependent) |
| `c` | **C**hat / **C**ommand (context-dependent) |
| `l` | **L**ogs / **L**ist (context-dependent) |
| `p` | **P**rovision / **P**rofile (context-dependent) |

### Modifier Conventions
| Modifier | Usage |
|----------|-------|
| `ctrl+` | System actions (quit, save, clear) |
| `shift+` | Alternative/extended actions |
| `alt+` | Reserved for future use |

## Implementation Notes

### Textual Binding Resolution
From [Textual documentation](https://textual.textualize.io/guide/input/):

> "When you press a key, Textual will first check for a matching binding in the BINDINGS list of the currently focused widget. If no match is found, it will search upwards through the DOM all the way up to the App looking for a match."

### Priority Bindings
For critical bindings that must always work:

```python
BINDINGS = [
    Binding("ctrl+q", "quit", "Quit", show=False, priority=True),
]
```

### Hiding System Bindings
System bindings should use `show=False` to avoid cluttering the footer:

```python
Binding("ctrl+c", "quit", show=False, priority=True),
```

## Sources

- [Textual Input Guide](https://textual.textualize.io/guide/input/)
- [Textual Binding API](https://textual.textualize.io/api/binding/)
- [Posting Keymap Documentation](https://posting.sh/guide/keymap)
- [GitHub: Textual Contextual Key-Bindings Discussion](https://github.com/Textualize/textual/discussions/409)
