Pad/doc/touch.md

# Touch and Input Handling

This document specifies how Pad handles low-level pointer and keyboard events using Gioui primitives, and how these are translated into editor actions (cursor movement, selection, scrolling).

## 1. Gioui Primitives

Pad avoids high-level widgets and uses the following low-level Gioui ops and events. Ops are submitted in the paint function; Events are returned by `w.Event()`.

| Op (submitted in paint) | Event (returned by w.Event()) | Use Case |
|---|---|---|
| `pointer.InputOp` | `pointer.Event` | Defines hit-regions (editor, buttons, search bar). Captures `Press`, `Release`, `Move`, `Drag`, `Scroll`. |
| `key.InputOp` | `key.Event` | Enables keyboard focus. Captures `Edit` (text insertion), `Press` (Backspace, Enter, Arrows). |
| `key.FocusOp` | — | Requests keyboard focus for the active element. |
| `key.SoftKeyboardOp` | — | Explicitly shows/hides the Android soft keyboard. |

### 1.1 Op/Event Flow

Because Logic does not have access to `*op.Ops`, the Op/Event flow is split:

1. **Logic → Ops**: Logic computes `[]Element`. Each element carries metadata about what input ops it needs (e.g., "this TextField needs `pointer.InputOp` with `Kind: Tap` on region X").
2. **Renderer → Ops**: During the paint function, the Renderer iterates `[]Element` and submits the appropriate `pointer.InputOp` / `key.InputOp` calls into `*op.Ops`.
3. **Gioui → Events**: Gioui returns `pointer.Event` / `key.Event` via `w.Event()` in subsequent cycles.
4. **Main → Logic**: The Main goroutine batches these events into `[]InputEvent` and sends them to Logic.
5. **Logic → State**: Logic processes events, updates state, and computes a new frame.

This ensures that hit-regions are always defined in the same frame where the elements are drawn, and Logic remains testable without the SDK.

## 2. Coordinate Mapping

The editor operates in three coordinate spaces:

1.  **UI Space (DP)**: The raw (X, Y) coordinates from Gioui events, relative to the window origin.
2.  **Text Space (Lines/Cols)**: The logical position within the text file, accounting for scroll offset and word wrap.
3.  **Byte Space (Offsets)**: The raw byte offset in the UTF-8 file buffer.

### 2.1 Hit-Region Tags

Gioui `pointer.InputOp` takes a `tag` (an `op.Tag`). When an event fires, `event.Tag` identifies which region was touched.

**Tagging Strategy**:
- The Renderer assigns a unique tag per element (e.g., `editor`, `search_bar`, `status_bar`, `alpha_index`, `merge_hunk_accept_ours`).
- When Logic receives a `pointer.Event`, it first checks the tag to determine which element was touched, then applies element-specific coordinate logic.

### 2.2 Mapping UI → Byte Offset (Editor/TextField)

When a `pointer.Event` occurs at `(Ex, Ey)` on the `editor` tag:

1.  **Adjust for Scroll**: `Y = Ey + scroll_offset`.
2.  **Identify Visual Line**: `visual_line = floor(Y / line_height)`.
3.  **Resolve to Logical Line**: If word wrap is enabled, use the cached wrap positions to map `visual_line` → `logical_line`. Otherwise, they are the same.
4.  **Identify Column**:
    - Retrieve text for `logical_line` from the chunked buffer.
    - Use the font shaper to measure glyph widths until the cumulative width exceeds `Ex`.
    - Clamp to the line length.
5.  **Result**: Convert `(logical_line, col_index)` to a byte offset using the **Line Index**.

### 2.3 Mapping UI → Element (Non-Text Elements)

For buttons, search bar, alpha index, merge hunks:
- Each element has a `Region()` (rectangle). The Main goroutine checks if `(Ex, Ey)` falls within the region.
- For the **Alpha Index**, the Y-coordinate maps to a letter (e.g., `letter = alphabet[floor((Y - alpha_top) / (alpha_height / 26))]`).
- For **Merge Hunks**, the tag identifies which hunk button (accept-ours / accept-theirs) was tapped.

## 3. Gestures and State Machine

The Logic goroutine maintains a small state machine for the active gesture. The state is transient (does not survive process death) and is reset on gesture completion.

### 3.1 Gesture States

| State | Entry Condition | Exit Condition | Action |
|---|---|---|---|
| `Idle` | Default state | `Press` received | — |
| `Pressed` | `Press` at (X, Y) | `Release` or `Drag` | Record press time and position |
| `Tapping` | `Release` received (short duration, no move) | Timeout or next `Press` | Move cursor, clear selection |
| `DoubleTap` | Second `Tapping` within 300ms | Gesture complete | Select word at (X, Y) |
| `LongPress` | `Press` held > 500ms | `Release` | Select word (future: magnifier) |
| `Selecting` | `Drag` received | `Release` | Update `selection_end` to current (X, Y) |
| `Scrolling` | `Drag` on non-focused area or two-finger drag | `Release` | Update `scroll_offset` |

### 3.2 Gesture Disambiguation

The Logic goroutine distinguishes gestures using timing and movement thresholds:

- **Tap vs Long Press**: If `Press` → `Release` occurs within 500ms, it's a tap. Otherwise, it's a long press.
- **Tap vs Drag**: If the finger moves more than 16 DP between `Press` and `Release`, it's a drag. Otherwise, it's a tap.
- **Single vs Double Tap**: If two taps occur within 300ms, the second tap triggers a word selection.
- **Select vs Scroll**: If the keyboard is visible (focused `TextField`), a single-finger drag is a selection. If the keyboard is hidden, a single-finger drag is a scroll. Two-finger drags are always scrolls.

### 3.3 Selection Logic

Selection is defined by two byte offsets: `selection_start` and `selection_end`.
- If `selection_start == selection_end`, there is no selection (just a cursor).
- During a **Drag** gesture:
    - On `Press`: Set `selection_start = selection_end = offset_at(X, Y)`.
    - On `Drag`: Update `selection_end = offset_at(X, Y)`.
    - The UI renders a `TextField` with highlighted regions between the two offsets.

### 3.4 Double Click (Word Selection)

When a double-click is detected:
1.  Identify the character at the click offset.
2.  Expand left and right until a non-word character (space, punctuation, newline) is hit.
3.  Set `selection_start` and `selection_end` to these boundaries.

## 4. Input Batching and Latency

As specified in `architecture.md`, the Main goroutine batches events. For touch, this is critical:

### 4.1 Event Compression in the Main Loop

The Main goroutine collects events during its event cycle. For a drag gesture, multiple `pointer.Event` (Type: `Move`) may fire before the next `FrameEvent`. The Main goroutine:

1.  Accumulates all events into a `[]InputEvent` slice.
2.  On the next `FrameEvent`, it sends the entire batch to Logic via `inputChan`.
3.  Logic processes the batch sequentially, updating the gesture state and cursor/selection.
4.  Logic produces a single frame reflecting the final state after all events.

This means that if 3 `Drag` events fire in one frame, Logic sees all 3 and produces one frame with the cursor/selection at the final position. There is no "churn" of intermediate frames.

### 4.2 Latency Budget

- **Event Capture**: Gioui captures the touch event immediately (sub-ms).
- **Batching**: Main goroutine holds events until the next `FrameEvent` (up to 16ms, but typically < 8ms).
- **Processing**: Logic processes the batch and computes layout (< 16ms).
- **Rendering**: Frame receiver stores and invalidates (sub-ms).
- **Total**: < 32ms from touch to visual feedback (typically < 16ms).

### 4.3 Gesture Continuity

Because Logic maintains the gesture state machine across frames, a multi-frame drag gesture is continuous:
- Frame 1: `Press` at A → Logic enters `Pressed` state.
- Frame 2: `Drag` to B → Logic enters `Selecting` state, updates `selection_end`.
- Frame 3: `Drag` to C → Logic updates `selection_end` again.
- Frame 4: `Release` → Logic finalizes selection, enters `Idle` state.

Each frame produces a new `[]Element` with the updated selection highlight.

## 5. Keyboard Interaction

The `TextField` element must be "focused" to receive keyboard events. Focus is a transient state managed by Logic.

### 5.1 Focus Acquisition

1.  **Tap on Editor**: User taps the `TextField` region. Main goroutine sends `pointer.Event` (Type: `Press`) to Logic.
2.  **Focus Request**: Logic sets `focused = true` and computes a frame with `key.FocusOp` and `key.SoftKeyboardOp(true)`.
3.  **Keyboard Appears**: Gioui shows the Android soft keyboard. Subsequent `w.Event()` calls return `key.Event`.

### 5.2 Focus Loss

1.  **Tap Outside Editor**: User taps a non-editor region (e.g., status bar, directory browser). Logic sets `focused = false` and computes a frame with `key.SoftKeyboardOp(false)`.
2.  **Keyboard Disappears**: Gioui hides the soft keyboard.

### 5.3 Key Events

| Event | Type | Name | Action |
|---|---|---|---|
| Text insertion | `Edit` | — | Insert `event.Text` at cursor, append to undo chain |
| Backspace | `Press` | `Backspace` | Delete character before cursor, append to delete chain |
| Enter | `Press` | `Enter` | Insert newline at cursor |
| Tab | `Press` | `Tab` | Insert spaces (configurable, e.g., 4 spaces) |
| Arrow Up/Down | `Press` | `Up`/`Down` | Move cursor up/down one line |
| Arrow Left/Right | `Press` | `Left`/`Right` | Move cursor left/right one character |
| Ctrl+A | `Press` | `A` (with Ctrl) | Select all text |
| Ctrl+Z | `Press` | `Z` (with Ctrl) | Undo |
| Ctrl+Y | `Press` | `Y` (with Ctrl) | Redo |
| Ctrl+F | `Press` | `F` (with Ctrl) | Show search bar |

### 5.4 IME and Composition

Android soft keyboards use IME composition for languages like Chinese, Japanese, or Korean. Gioui's `key.Event` (Type: `Edit`) handles the final committed text. Logic treats the committed text as a single insertion at the cursor.

## 6. Scroll Momentum

Pad implements a momentum model in the Logic goroutine to provide smooth scrolling.

### 6.1 Scroll Sources

| Source | Event | Behavior |
|---|---|---|
| **Mouse Wheel** | `pointer.Event` (Source: `MouseWheel`) | Direct scroll by `event.Scroll.Y` DP |
| **Finger Drag (No Focus)** | `pointer.Event` (Type: `Move`, no keyboard) | Direct 1:1 mapping of finger movement to `scroll_offset` |
| **Fling** | `pointer.Event` (Type: `Release`, high velocity) | Momentum-based scroll with exponential decay |

### 6.2 Fling Logic

When a `Release` event occurs with a high vertical velocity:

1.  **Velocity Calculation**: Logic tracks the position and timestamp of the last few `Move` events. On `Release`, it calculates the velocity (DP/ms).
2.  **Momentum Start**: If velocity > threshold (e.g., 0.5 DP/ms), Logic enters a `Flinging` state.
3.  **Decay**: On each subsequent frame (triggered by a timer or periodic `sendFrame()`), Logic updates `scroll_offset` by `velocity * elapsed_ms` and multiplies `velocity` by a decay factor (e.g., 0.95).
4.  **Stop**: When velocity drops below a minimum (e.g., 0.01 DP/ms), Logic stops the fling and returns to `Idle`.

### 6.3 Scroll Clamping

`scroll_offset` is clamped to ensure the viewport never scrolls past the top or bottom of the file:
- **Min**: 0 (top of file)
- **Max**: `total_file_height - viewport_height` (bottom of file)