openpencil/openspec/specs/selection-manipulation/spec.md

# selection-manipulation Specification

## Purpose
Node selection and direct manipulation. Click/shift/marquee select, move by drag, resize handles, rotation with snapping, duplicate, nudge, delete, and select-all.
## Requirements
### Requirement: Click to select
Clicking on a node SHALL select it (deselecting all others). Clicking empty canvas SHALL deselect all.

#### Scenario: Select a single node
- **WHEN** user clicks on a rectangle
- **THEN** the rectangle is selected and all other nodes are deselected

### Requirement: Multi-select with shift
Shift+clicking a node SHALL toggle it in the current selection.

#### Scenario: Add to selection
- **WHEN** user shift+clicks a second node while one is already selected
- **THEN** both nodes are in the selection

### Requirement: Marquee selection
Dragging on empty canvas SHALL create a selection rectangle. All nodes intersecting the rectangle SHALL be selected on release.

#### Scenario: Marquee drag
- **WHEN** user drags from empty canvas across three nodes
- **THEN** all three nodes are selected when the drag ends

### Requirement: Move by dragging
Dragging a selected node SHALL move it (and all other selected nodes) by the drag delta.

#### Scenario: Drag to move
- **WHEN** user drags a selected node by 50px right
- **THEN** the node's X position increases by 50

### Requirement: Resize handles
Selected nodes SHALL display 8 resize handles (4 corners + 4 edge midpoints). Dragging a handle SHALL resize the node. Shift constrains proportions.

#### Scenario: Resize from corner
- **WHEN** user drags the bottom-right corner handle outward
- **THEN** the node's width and height increase

### Requirement: Rotation
Hovering just outside a corner handle SHALL show a rotation cursor. Dragging SHALL rotate the node. Shift SHALL snap to 15° increments.

#### Scenario: Rotate with snap
- **WHEN** user drags the rotation handle while holding shift
- **THEN** the rotation snaps to the nearest 15° increment

### Requirement: Duplicate
Alt+drag SHALL duplicate the selected node and move the duplicate. ⌘D SHALL duplicate in place.

#### Scenario: Alt+drag duplicate
- **WHEN** user alt+drags a selected rectangle
- **THEN** a copy of the rectangle is created at the drag position

### Requirement: Constrained drawing
Holding shift while drawing a shape SHALL constrain to square/circle.

#### Scenario: Shift+drag rectangle
- **WHEN** user draws a rectangle while holding shift
- **THEN** the rectangle is constrained to a square (equal width and height)

### Requirement: Nudge with arrows
Arrow keys SHALL move selected nodes by 1px. Shift+arrow SHALL move by 10px.

#### Scenario: Arrow nudge
- **WHEN** user presses the right arrow key with a node selected
- **THEN** the node moves 1px to the right

### Requirement: Delete selection
Backspace/Delete SHALL remove all selected nodes.

#### Scenario: Delete node
- **WHEN** user presses backspace with a node selected
- **THEN** the node is removed from the scene graph

### Requirement: Select all
⌘A SHALL select all nodes on the current canvas.

#### Scenario: Select all
- **WHEN** user presses ⌘A
- **THEN** all nodes on the canvas are selected

### Requirement: Section creation with auto-adopt
Creating a section on the canvas SHALL automatically reparent overlapping sibling nodes into the section. Only nodes fully or partially within the section bounds are adopted.

#### Scenario: Draw section over existing nodes
- **WHEN** user draws a section that overlaps two rectangles
- **THEN** the two rectangles become children of the new section


### Requirement: Z-order manipulation
The editor SHALL support bringing selected nodes to front (]) and sending to back ([). Bring to front moves node to end of parent's childIds; send to back moves to start.

#### Scenario: Bring to front
- **WHEN** user selects a node and presses ]
- **THEN** the node moves to the top of its sibling z-order

#### Scenario: Send to back
- **WHEN** user selects a node and presses [
- **THEN** the node moves to the bottom of its sibling z-order

### Requirement: Toggle visibility
The editor SHALL support toggling node visibility (⇧⌘H). Hidden nodes are not rendered but remain in the scene graph and layers panel.

#### Scenario: Hide node
- **WHEN** user selects a visible node and presses ⇧⌘H
- **THEN** the node's `visible` property becomes false

### Requirement: Toggle lock
The editor SHALL support toggling node lock state (⇧⌘L). Locked nodes cannot be selected or moved via canvas interaction.

#### Scenario: Lock node
- **WHEN** user selects a node and presses ⇧⌘L
- **THEN** the node's `locked` property becomes true

### Requirement: Move to page
The editor SHALL support moving selected nodes to a different page, reparenting them under the target page's CANVAS node.

#### Scenario: Move selection to another page
- **WHEN** user moves a node to Page 2 via context menu
- **THEN** the node is reparented under Page 2's CANVAS node and removed from the current page

### Requirement: Rename node
The editor SHALL support renaming nodes programmatically via `renameNode(id, name)`.

#### Scenario: Rename a layer
- **WHEN** `renameNode` is called with a new name
- **THEN** the node's name property is updated