# pattern-placement Specification

## Purpose
Lets users select a Game of Life pattern, preview it under the mouse cursor, rotate it, and place copies on the grid with a click.

## Requirements

### Requirement: Selecting a pattern arms a placement tool
The system SHALL activate a placement tool for the selected pattern when a `select:<pattern>` action is triggered, and show a preview following the cursor.

#### Scenario: Tool activation
- **WHEN** the user triggers `select:glider`
- **THEN** a glider preview appears at the current cursor position
- **AND** the placement tool remains active

### Requirement: Preview follows cursor motion
The system SHALL update the preview position to track the current mouse cursor cell while a tool is active.

#### Scenario: Mouse moves
- **WHEN** the user moves the mouse while a tool is active
- **THEN** the preview moves to the cell under the cursor

### Requirement: Tool can be rotated in 90-degree steps
The system SHALL rotate the active preview by 90 degrees each time the rotate action is triggered.

#### Scenario: Rotate preview
- **WHEN** the user triggers the rotate action while a tool is active
- **THEN** the preview rotates 90 degrees clockwise
- **AND** remains at the same anchor cell

### Requirement: Left click places the pattern when valid
The system SHALL write the active pattern's alive cells into the grid at the preview position when the user left-clicks and the pattern fits entirely within the grid.

#### Scenario: Valid placement
- **WHEN** the user left-clicks while a tool is active and the preview fits in the grid
- **THEN** the pattern's cells become alive in the grid
- **AND** the tool remains active for further placement

### Requirement: Invalid placement is rejected
The system SHALL not modify the grid when a left click occurs while the preview extends outside the grid.

#### Scenario: Out of bounds
- **WHEN** the user left-clicks while the preview extends outside the grid
- **THEN** no cells are changed
- **AND** the tool remains active

### Requirement: Escape cancels the active tool
The system SHALL deactivate the placement tool and remove the preview when the cancel action is triggered.

#### Scenario: Cancel placement
- **WHEN** the user triggers the cancel action while a tool is active
- **THEN** the preview disappears
- **AND** no further clicks place a pattern until a tool is selected again

### Requirement: Click without active tool does nothing
The system SHALL ignore left clicks when no placement tool is active.

#### Scenario: No tool
- **WHEN** the user left-clicks while no tool is active
- **THEN** the grid is unchanged

### Requirement: Additional built-in patterns are available
The system SHALL provide additional built-in patterns (Beacon, Loaf, Boat, Tub, R-pentomino, Acorn) selectable via keys 5-0.

#### Scenario: Select beacon
- **WHEN** the user triggers `select:beacon`
- **THEN** a beacon preview is shown

### Requirement: New patterns support rotation
The system SHALL support 90-degree rotation for all new patterns.

#### Scenario: Rotate new pattern
- **WHEN** the user rotates a new pattern preview
- **THEN** its cells rotate accordingly