# keyboard-bindings Specification

## Purpose
Allows users to configure keyboard shortcuts that map key combinations to application actions, with sensible built-in defaults when no configuration file exists.

## Requirements

### Requirement: Default bindings are available without configuration
The system SHALL provide built-in default bindings for all documented actions, including digits 1-4 selecting the Glider, Blinker, Block, and Toad patterns, Space rotating, Escape cancelling, and Ctrl+Q quitting.

#### Scenario: No config file present
- **WHEN** the application starts and `~/.config/wlgol/keys.conf` does not exist
- **THEN** the application uses the built-in default bindings
- **AND** creates the config file with the default contents

### Requirement: Configuration file overrides defaults by merge
The system SHALL read `~/.config/wlgol/keys.conf` as TOML when it exists and merge its entries over the built-in defaults, so only specified keys change.

#### Scenario: Partial override
- **WHEN** the config file defines a binding for key "1" only
- **THEN** key "1" uses the configured action
- **AND** all other keys keep their default bindings

#### Scenario: Full replacement of a key
- **WHEN** the config file defines a binding for a key that has a default
- **THEN** the configured action replaces the default for that key

### Requirement: Key combinations are modifier-aware
The system SHALL match a binding only when the modifiers required by the binding are active, supporting Ctrl, Shift, Alt, and Super.

#### Scenario: Modifier required
- **WHEN** the user presses Q while Ctrl is held and a `ctrl+q = quit` binding exists
- **THEN** the quit action is triggered

#### Scenario: Modifier not held
- **WHEN** the user presses Q without Ctrl while a `ctrl+q = quit` binding exists
- **THEN** the quit action is not triggered by that binding

### Requirement: Readable key aliases are supported
The system SHALL accept human-readable key names such as space, escape, enter, and arrow names in binding keys.

#### Scenario: Alias binding
- **WHEN** the config file contains `space = rotate`
- **THEN** pressing the space bar triggers the rotate action

### Requirement: Malformed entries are ignored
The system SHALL ignore malformed or unrecognized binding entries and continue using defaults for the affected keys.

#### Scenario: Invalid entry
- **WHEN** the config file contains an entry with an unknown action
- **THEN** that entry is ignored
- **AND** the application still starts successfully

### Requirement: Actions trigger on key press
The system SHALL dispatch a bound action when the corresponding key is pressed, not on release.

#### Scenario: Press triggers action
- **WHEN** the user presses a key with a valid binding
- **THEN** the bound action is invoked once for that press