openpencil/openspec/specs/vector-edit/spec.md

vector-edit Specification

Purpose

Geometry edit mode for VECTOR nodes: direct editing of anchors, segments, and tangents without invoking base transform interactions.

Requirements

Requirement: Enter curve edit mode

Double-clicking a VECTOR node in Select mode SHALL enter geometry edit mode for that node.

Scenario: Enter by double-click

• WHEN user double-clicks a vector curve
• THEN editor opens geometry edit mode for that vector
• AND editable vertices/segments are initialized

Requirement: Edit mode scope

Only one vector SHALL be actively edited at a time.

Scenario: Enter another vector

• WHEN user double-clicks a different vector while one vector is in edit mode
• THEN previous edit session ends
• AND new vector becomes the active edited vector

Requirement: Exit curve edit mode

User SHALL be able to exit curve edit mode and return to normal selection interactions.

Scenario: Exit with Escape

• WHEN curve edit mode is active and user presses Escape
• THEN curve edit mode ends

Scenario: Exit by tool/context switch

• WHEN curve edit mode is active and user switches to incompatible context (for example selects non-geometry transform workflow)
• THEN curve edit mode ends cleanly

Requirement: Transform interaction isolation in edit mode

While curve edit mode is active, base selection transform bbox interactions SHALL be disabled for the edited vector.

Scenario: Hidden/non-interactive bbox corners

• WHEN user hovers where resize/rotate corners would normally be
• THEN transform cursors are not shown
• AND resize/rotate handles are not hit-testable

Requirement: Vertex selection and direct drag

Anchors in curve edit mode SHALL support direct manipulation by drag.

Scenario: Drag an anchor

• WHEN user drags an anchor point in curve edit mode
• THEN anchor position updates by pointer delta
• AND connected segments update in preview and final geometry

Requirement: Handle drag without modifiers

Dragging a tangent handle without modifiers SHALL use the node's current composition rules.

Scenario: Default handle drag

• WHEN user drags a tangent with no modifier keys
• THEN tangent updates according to current handle composition of the vertex

Requirement: Continuous override in curve edit mode

Holding Cmd/Ctrl while dragging a tangent SHALL force Continuous behavior for the drag.

Scenario: Cmd/Ctrl tangent drag

• WHEN user drags a tangent while holding Cmd/Ctrl
• THEN active tangent direction is constrained to the sister-handle axis
• AND active tangent length changes with drag

Requirement: Corner override in curve edit mode

Holding Alt/Option while dragging a tangent SHALL force independent handle editing.

Scenario: Alt/Option tangent drag

• WHEN user drags a tangent while holding Alt/Option
• THEN active tangent changes independently
• AND sister tangent remains unchanged

Requirement: Shift axis lock for Continuous/Symmetric

Holding Shift during tangent drag on Continuous (ANGLE) or Symmetric (ANGLE_AND_LENGTH) vertices SHALL lock direction to pre-drag axis and allow length-only edits.

Scenario: Shift lock with Continuous

• WHEN user starts dragging a tangent on ANGLE vertex and then holds Shift
• THEN tangent direction stays equal to pre-drag direction
• AND only tangent length changes

Scenario: Shift lock with Symmetric

• WHEN user starts dragging a tangent on ANGLE_AND_LENGTH vertex and then holds Shift
• THEN both tangents stay collinear on pre-drag axis
• AND only lengths update per composition rules

Requirement: Modifier transitions during one drag

Modifier changes (Cmd/Ctrl, Alt/Option, Shift) during an active drag SHALL be applied live without canceling drag.

Scenario: Toggle modifiers mid-drag

• WHEN user changes modifier keys while still dragging a tangent
• THEN active composition behavior switches immediately
• AND drag session continues from current pointer state

Requirement: Bend mode handle targeting on anchor drag

For bend override (Cmd/Ctrl + anchor drag), edited tangent SHALL be determined by segment attachment direction at the anchor, not by nearest neighbor-point distance.

Scenario: Direction-based target on 2-segment vertex

• WHEN vertex has two attached segments and user starts bend drag with Cmd/Ctrl
• THEN edited tangent is chosen by best directional alignment to drag direction

Scenario: Direction-based target on multi-branch vertex

• WHEN vertex has 3+ attached segments and user starts bend drag with Cmd/Ctrl
• THEN edited tangent/segment is resolved by segment attachment direction
• AND selected target supports vector-web branching topology

Requirement: Bend mode target lock

Resolved bend target SHALL lock after initial determination for the current drag session.

Scenario: Lock target after initial resolution

• WHEN bend drag begins and target tangent is resolved
• THEN only that tangent is edited for the remainder of the drag
• AND non-target tangents keep original coordinates

Requirement: Pen interactions while already in curve edit mode

With Pen active inside curve edit mode, contour insertion, endpoint resume, and point deletion SHALL be available.

Scenario: Insert anchor on contour

• WHEN Pen is active and user clicks a segment in curve edit mode
• THEN segment is split and new anchor is inserted at hit position

Scenario: Resume drawing from endpoint

• WHEN Pen is active and user clicks an open-path endpoint in curve edit mode
• THEN editor resumes path drawing from that endpoint

Scenario: Delete anchor with Alt/Option click

• WHEN Pen is active and user Alt/Option-clicks an anchor in curve edit mode
• THEN anchor is removed and neighboring segments are reconnected if topology allows

Requirement: Visual preview correctness during curve edit

Interactive preview in curve edit mode SHALL render active tangent feedback from anchor to active tangent endpoint.

Scenario: Active tangent preview line

• WHEN user drags an active tangent
• THEN preview line is rendered from anchor to active tangent endpoint
• AND preview does not render a misleading line between non-active handles