docs: add input-and-placement OpenSpec change and update AGENTS.md

Plan input handling and pattern placement before Game of Life mechanics: keyboard bindings config, mouse placement with preview/rotation, HiDPI scaling, and cell grid. Update AGENTS.md project notes.
2026-11-08 14:30:09 +01:00
parent 403bcbbfdf
commit 5e7abfb56b
12 changed files with 436 additions and 40 deletions
@@ -0,0 +1,60 @@
+# Spec Delta
+
+## Purpose
+
+Allows users to configure keyboard shortcuts that map key combinations to application actions, with sensible built-in defaults when no configuration file exists.
+
+## ADDED 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