diff --git a/.lore/plans/vi-mode-pair-writing.md b/.lore/plans/vi-mode-pair-writing.md
new file mode 100644
index 00000000..cb826ea4
--- /dev/null
+++ b/.lore/plans/vi-mode-pair-writing.md
@@ -0,0 +1,233 @@
+# Plan: Vi Mode for Pair Writing
+
+## Context
+
+- **Spec**: `.lore/specs/vi-mode-pair-writing.md`
+- **Research**: `.lore/research/vi-mode-implementation.md`
+- **Integration target**: `PairWritingMode.tsx` and `PairWritingEditor.tsx`
+
+## Approach
+
+The vi mode implementation follows a **layered architecture** with clear separation:
+
+1. **Configuration layer** - Vault config addition, keyboard detection
+2. **State machine layer** - Mode management, key sequence buffering
+3. **Command execution layer** - Cursor manipulation, text operations
+4. **UI layer** - Mode indicator, command input
+
+The core abstraction is a `useViMode` hook that encapsulates all vi behavior and integrates with the existing `PairWritingEditor` via props.
+
+## Technical Decisions
+
+**TD-1: Hook-based architecture**
+
+Create `useViMode(textareaRef, options)` hook that returns:
+- `mode`: current mode (normal/insert/command)
+- `handleKeyDown`: event handler to attach to textarea
+- `commandBuffer`: current ex command being typed
+- `pendingCount`: numeric prefix being accumulated
+- `pendingOperator`: buffered operator awaiting motion (`d`, `y`, or null)
+- `clipboard`: internal yank buffer
+- `undoStack`: array of content snapshots for `u` command
+
+This keeps vi logic isolated and testable independent of React rendering.
+
+**TD-2: Keyboard detection via matchMedia**
+
+Use `window.matchMedia('(pointer: fine)')` combined with `navigator.maxTouchPoints` to detect keyboard availability:
+```typescript
+const hasKeyboard =
+  window.matchMedia('(pointer: fine)').matches ||
+  navigator.maxTouchPoints === 0;
+```
+
+This isn't perfect but catches most cases. If detection fails, user gets standard editing (safe fallback).
+
+**TD-3: Textarea cursor manipulation**
+
+Use `selectionStart`/`selectionEnd` properties to track and move cursor:
+- Normal mode: collapse selection to single point (cursor)
+- Movement commands: update `selectionStart` and `selectionEnd`
+- Insert mode: let browser handle naturally
+
+Line-based operations parse content by newlines to find line boundaries.
+
+**TD-4: Key event handling strategy**
+
+In Normal mode, `onKeyDown` handler:
+1. Check for numeric digit → accumulate in `pendingCount`
+2. Check for operator key (`d`, `y`) → set pending operator
+3. Check for motion/action → execute with count
+4. `preventDefault()` to stop character insertion
+
+In Insert mode:
+- Only intercept `Escape` → return to Normal
+- All other keys pass through naturally
+
+**TD-5: Command mode UI**
+
+When `:` pressed, render a small input field at bottom of editor (vim-style command line). This is a controlled input that:
+- Captures text until Enter or Escape
+- On Enter, parses and executes command
+- On Escape, dismisses without action
+
+Rendered conditionally within `PairWritingEditor` when mode is 'command'.
+
+**TD-6: Integration with existing save/exit**
+
+The hook accepts callbacks for save and exit:
+```typescript
+useViMode(textareaRef, {
+  enabled: viModeEnabled && hasKeyboard,
+  onSave: () => handleSave(),
+  onExit: () => handleExitClick(),
+  onQuitWithUnsaved: () => setShowExitConfirm(true),
+});
+```
+
+`:w` calls `onSave`, `:wq` calls both, `:q` checks `hasUnsavedChanges` and either exits or triggers confirmation.
+
+**TD-7: Line operations implementation**
+
+For `dd`, `yy`, `p`, `P`:
+- Parse content into lines array
+- Find current line by counting newlines before cursor
+- Splice/insert lines as needed
+- Reconstruct content string
+- Update cursor position appropriately
+
+**TD-8: Numeric prefix handling**
+
+Buffer digits in state until a command key arrives.
+
+Note: `0` is special - it's "start of line" when no count is pending, but a digit when accumulating (e.g., `10j`).
+
+**TD-9: Undo stack**
+
+Maintain internal undo stack since programmatic `textarea.value` changes don't create browser undo history:
+- Push content snapshot before each edit operation (`dd`, `x`, `p`, Insert mode exit)
+- `u` command pops and restores previous state
+- Stack has reasonable depth limit (e.g., 100 entries)
+- Insert mode batches changes into single undo entry (snapshot on mode enter, not per keystroke)
+
+**TD-10: Cursor rendering with overlay**
+
+Use hybrid approach: textarea for content, overlay div for block cursor in Normal mode.
+
+Architecture:
+```
+┌─────────────────────────────────────┐
+│ PairWritingEditor                   │
+│  ┌───────────────────────────────┐  │
+│  │ textarea (content)            │  │
+│  │  caret-color: transparent     │  │
+│  │  when Normal mode             │  │
+│  └───────────────────────────────┘  │
+│  ┌───────────────────────────────┐  │
+│  │ .vi-cursor (overlay)          │  │
+│  │  position: absolute           │  │
+│  │  pointer-events: none         │  │
+│  └───────────────────────────────┘  │
+│  ┌───────────────────────────────┐  │
+│  │ .vi-cursor-mirror (off-screen)│  │
+│  │  visibility: hidden           │  │
+│  │  copies textarea styles       │  │
+│  └───────────────────────────────┘  │
+└─────────────────────────────────────┘
+```
+
+Mirror element technique for cursor position:
+1. Create off-screen div with identical styling (font, padding, line-height, word-wrap)
+2. Split content at cursor position into before/after text nodes
+3. Insert span marker between them
+4. Measure span's `getBoundingClientRect()` for pixel coordinates
+5. Position overlay at those coordinates, adjusted for textarea scroll
+
+Mode-specific behavior:
+- **Normal mode**: Hide native caret (`caret-color: transparent`), show block cursor overlay
+- **Insert mode**: Hide overlay, show native caret (standard textarea behavior)
+- **Command mode**: Same as Normal (cursor stays visible while typing ex command)
+
+Scroll synchronization:
+```typescript
+// On textarea scroll, offset overlay position
+const updateCursorPosition = () => {
+  const pos = calculateCursorPixelPosition(textarea, cursorIndex);
+  overlay.style.left = `${pos.left - textarea.scrollLeft}px`;
+  overlay.style.top = `${pos.top - textarea.scrollTop}px`;
+};
+
+textarea.addEventListener('scroll', updateCursorPosition);
+```
+
+Cursor appearance by mode:
+- Normal: Block cursor (width ~0.6em, height ~1.2em, semi-transparent background)
+- Insert: Native line cursor (overlay hidden)
+- Command: Block cursor (same as Normal)
+
+Dependencies:
+- Can use `textarea-caret-position` npm package or implement core algorithm (~50 lines)
+- Prefer implementing core algorithm to avoid dependency for small feature
+
+**TD-8 implementation:**
+```typescript
+// State
+pendingCount: number | null
+
+// On digit
+if (/[0-9]/.test(key) && mode === 'normal') {
+  pendingCount = (pendingCount ?? 0) * 10 + parseInt(key);
+  return;
+}
+
+// On command
+const count = pendingCount ?? 1;
+pendingCount = null;
+executeCommand(key, count);
+```
+
+## Component Structure
+
+```
+frontend/src/
+├── hooks/
+│   ├── useViMode.ts              # Core vi mode hook (state machine, commands)
+│   ├── useViMode.test.ts         # Unit tests for vi logic
+│   ├── useViCursor.ts            # Cursor position calculation and overlay management
+│   └── useViCursor.test.ts       # Unit tests for cursor positioning
+├── components/
+│   └── pair-writing/
+│       ├── PairWritingEditor.tsx # Modified to integrate useViMode + cursor overlay
+│       ├── ViModeIndicator.tsx   # Mode display component ("-- NORMAL --", etc.)
+│       ├── ViCommandLine.tsx     # Ex command input component
+│       ├── ViCursor.tsx          # Block cursor overlay component
+│       └── vi-mode.css           # Styles for vi UI elements (cursor, indicator, command line)
+```
+
+## Data Flow
+
+```
+VaultConfig.viMode (backend)
+        ↓
+VaultInfo.viMode (shared type, API response)
+        ↓
+PairWritingMode reads from vault context
+        ↓
+useViMode(enabled: viMode && hasKeyboard)
+        ↓
+handleKeyDown attached to textarea
+        ↓
+State changes → re-render with mode indicator
+```
+
+## Considerations
+
+**Cursor rendering**: Uses overlay approach (TD-10) with mirror element technique. This provides vim-authentic block cursor in Normal mode while preserving native textarea behavior in Insert mode. The `useViCursor` hook encapsulates position calculation and can be tested independently.
+
+**Testing strategy**: The `useViMode` hook should be tested in isolation using a mock textarea ref. Test each command produces expected cursor position and content changes. `useViCursor` tests verify pixel position calculations. Integration tests verify the full flow in `PairWritingEditor`.
+
+**Undo behavior**: Internal undo stack (TD-9) handles `u` command. Browser `Ctrl+Z` may not work reliably for programmatic changes, so the internal stack is the primary undo mechanism. Insert mode batches all keystrokes into one undo entry.
+
+**Performance**: Line operations on large files could be slow. For v1, accept this limitation. If needed later, consider rope data structure or virtual DOM for content.
+
+**Future extensibility**: The command dispatch pattern makes adding new commands straightforward. Visual mode would add another mode state and selection tracking.
diff --git a/.lore/research/vi-mode-implementation.md b/.lore/research/vi-mode-implementation.md
new file mode 100644
index 00000000..b4ce3798
--- /dev/null
+++ b/.lore/research/vi-mode-implementation.md
@@ -0,0 +1,308 @@
+# Research: Vi Mode Implementation for Pair Writing
+
+## Summary
+
+Vi/Vim is a modal text editor where keystrokes have different meanings depending on the current mode. Implementing vi mode for Pair Writing requires a state machine managing mode transitions and a key handler that interprets input based on current mode. Several JavaScript libraries exist that implement vi for textareas, providing proven patterns.
+
+## Key Findings
+
+### Modal Architecture
+
+Vi operates in distinct modes:
+
+| Mode | Purpose | Entry | Exit |
+|------|---------|-------|------|
+| **Normal** | Navigation and commands | Default, `Esc` from other modes | `i`, `a`, `o`, `v`, `:` |
+| **Insert** | Text entry | `i`, `I`, `a`, `A`, `o`, `O` | `Esc` |
+| **Visual** | Selection | `v` (char), `V` (line) | `Esc`, action completion |
+| **Command** | Ex commands (`:w`, `:q`) | `:` from Normal | `Enter`, `Esc` |
+
+### Essential Commands (Minimum Viable)
+
+**Movement (Normal mode):**
+- `h`, `j`, `k`, `l` - Character/line movement (left, down, up, right)
+- `w`, `b` - Word forward/backward
+- `0`, `$` - Line start/end
+- `gg`, `G` - Document start/end
+
+**Mode switching:**
+- `i` - Insert before cursor
+- `I` - Insert at line start
+- `a` - Append after cursor
+- `A` - Append at line end
+- `o` - Open line below
+- `O` - Open line above
+- `Esc` - Return to Normal mode
+
+**Editing (Normal mode):**
+- `x` - Delete character
+- `dd` - Delete line
+- `yy` - Yank (copy) line
+- `p` - Put (paste) after cursor
+- `P` - Put before cursor
+- `u` - Undo
+
+**Ex commands:**
+- `:w` - Write (save)
+- `:q` - Quit
+- `:wq` or `:x` - Write and quit
+
+### Implementation Patterns from Existing Libraries
+
+**Vim.js** (~19KB, no dependencies):
+- Mode-based state machine
+- Event-driven keyboard handling
+- Numeric prefix support (`5j` = move 5 lines)
+- Dual-key sequences (`dd`, `yy`)
+- Separate clipboard/register for yank/put
+
+**VimMotions browser extension:**
+- Uses backtick (`) instead of Esc for mode exit (mobile-friendly)
+- Visual feedback via highlighting system for mode indication
+- Supports textarea, input, and contenteditable
+
+**Key architectural decisions:**
+1. State machine with explicit mode transitions
+2. Key handler dispatches to mode-specific handlers
+3. Clipboard is internal (separate from system clipboard)
+4. Visual feedback for current mode is essential
+5. Numeric prefixes require buffering keystrokes
+
+### Integration Points for Memory Loop
+
+**Current Pair Writing architecture:**
+- `PairWritingEditor.tsx` - Textarea-based editor component
+- `usePairWritingState.ts` - State hook (content, snapshot, unsaved changes)
+- `useTextSelection.ts` - Selection tracking for context menu
+- Vault config in `vault-config.ts` - No vi mode setting yet
+
+**Required additions:**
+1. `viMode?: boolean` in `VaultConfig` interface
+2. Vi mode state hook or integration into existing state
+3. Key event handler for Normal mode
+4. Mode indicator UI component
+5. Internal clipboard for yank/put operations
+
+**Configuration flow:**
+- User enables vi mode in vault config (`.memory-loop.json`)
+- Config change triggers editor behavior change
+- Editor shows mode indicator when vi mode enabled
+
+### Escape Key Alternatives for Mobile
+
+Traditional Esc is awkward on mobile keyboards. Options:
+- Backtick (`) - Used by VimMotions extension
+- `jj` or `jk` sequence - Common vim mapping
+- Swipe gesture - Native mobile feel
+- On-screen mode button - Most accessible
+
+### Scope Considerations
+
+**Minimal viable implementation:**
+- Normal and Insert modes only (no Visual initially)
+- Basic movement: `h`, `j`, `k`, `l`, `0`, `$`
+- Insert commands: `i`, `a`, `o`
+- Exit insert: `Esc` (or alternative)
+- Basic editing: `x`, `dd`
+- Yank/put: `yy`, `p`
+- Ex commands: `:w`, `:q`, `:wq`
+
+**Deferred for later:**
+- Visual mode selection
+- Word motions (`w`, `b`, `e`)
+- Change commands (`c`, `cw`, `cc`)
+- Search (`/`, `?`, `n`, `N`)
+- Marks and jumps
+- Macros and registers
+
+## Sources
+
+- [Vim Cheat Sheet](https://vim.rtorr.com/) - Comprehensive command reference
+- [Vim.js](https://github.com/toplan/Vim.js) - Lightweight textarea vim implementation
+- [VimMotions](https://github.com/RonelXavier/VimMotions) - Browser extension with mobile considerations
+- [Onivim Modal Editing 101](https://onivim.github.io/docs/getting-started/modal-editing-101) - Modal editing concepts
+- [VS Code ModalEdit Tutorial](https://johtela.github.io/vscode-modaledit/docs/tutorial.html) - Implementation patterns
+- [nixCraft Vim Save/Quit Guide](https://www.cyberciti.biz/faq/linux-unix-vim-save-and-quit-command/) - Ex command reference
+
+## Notes
+
+### For Issue #394 Specifically
+
+The issue requests:
+1. Vi mode based on vault configuration - needs config addition
+2. Mode change when config changes - reactive update
+3. Basic movement keys - `hjkl`
+4. Insert/append mode - `i`, `a`
+5. Yank, copy, put - `yy`, `p`
+6. `:` for write and quit - exits pair writing
+
+This aligns well with a minimal implementation. The `:wq` behavior mapping to "exit pair writing" is a nice fit since Pair Writing is effectively a modal editing session within the app.
+
+### Architecture Recommendation
+
+Create a `useViMode` hook that:
+1. Reads vi mode setting from vault config
+2. Manages mode state (normal/insert/command)
+3. Provides key event handler to attach to textarea
+4. Exposes mode for UI indicator
+5. Handles clipboard internally
+
+The hook integrates with `PairWritingEditor` via:
+- `onKeyDown` handler override when vi mode enabled
+- Mode indicator rendered conditionally
+- Modified cursor behavior in Normal mode
+
+## Cursor Rendering Research (Added 2026-01-29)
+
+### The Problem
+
+In Normal mode, we need to:
+1. Prevent keystrokes from inserting text
+2. Show the cursor position (preferably as a block cursor, vim-style)
+3. Handle the cursor visibility on empty lines
+
+Native textarea cursors only appear when focused and accepting input, creating a conflict with Normal mode behavior.
+
+### Approaches Found in Existing Implementations
+
+**Approach A: Hidden Textarea + Custom Rendering (Modern Editors)**
+
+Used by newer editors (not contenteditable-based). The pattern:
+1. Hidden/transparent textarea captures keyboard input
+2. Visible content rendered separately (div or canvas)
+3. Custom cursor element positioned absolutely over content
+4. Cursor position calculated via mirror element technique
+
+Pros:
+- Full control over cursor appearance (block, line, underline)
+- Predictable cross-browser behavior
+- Clean separation of input capture vs. display
+
+Cons:
+- Significant implementation complexity
+- Must sync scroll position, selection, and content between hidden input and visible display
+- More code to maintain
+
+**Approach B: Textarea + Overlay Cursor (Hybrid)**
+
+Keep textarea visible for content, add overlay for cursor:
+1. Textarea remains the source of truth for content
+2. Mirror element technique calculates cursor pixel position
+3. Absolutely positioned div renders block cursor over textarea
+4. In Normal mode: hide native caret via `caret-color: transparent`, show overlay
+5. In Insert mode: hide overlay, show native caret
+
+Mirror element technique (from [textarea-caret-position](https://github.com/component/textarea-caret-position)):
+```javascript
+// Create off-screen div with identical styling
+const mirror = document.createElement('div');
+// Copy all relevant CSS properties (font, padding, line-height, etc.)
+
+// Split text at cursor position
+const textBefore = textarea.value.substring(0, cursorPos);
+const textAfter = textarea.value.substring(cursorPos);
+
+// Build mirror content using safe DOM methods
+const cursorSpan = document.createElement('span');
+cursorSpan.textContent = '\u00A0'; // non-breaking space
+
+mirror.textContent = ''; // clear
+mirror.appendChild(document.createTextNode(textBefore));
+mirror.appendChild(cursorSpan);
+mirror.appendChild(document.createTextNode(textAfter));
+
+// Get position from span
+const rect = cursorSpan.getBoundingClientRect();
+// Returns {top, left, height} relative to viewport
+```
+
+Pros:
+- Leverages native textarea for text handling
+- Less complexity than full custom rendering
+- Can still use native selection/copy/paste
+
+Cons:
+- Must keep overlay in sync with scroll
+- Edge cases with wrapped lines
+- Two sources of cursor truth (native + overlay)
+
+**Approach C: CodeMirror's Method (for reference)**
+
+CodeMirror uses `doc.markText` to highlight the character under the cursor in Normal mode, creating a visual block effect. However:
+- Doesn't work on empty lines (no character to mark)
+- Requires CodeMirror's infrastructure
+- Not applicable to plain textarea
+
+**Approach D: ContentEditable (Not Recommended)**
+
+Some editors use contenteditable div instead of textarea:
+- Known issues with vim mode cursor on empty content
+- Inconsistent cross-browser behavior
+- DOM mutation complexities
+- "DOM is not the perfect tool for this job" - CKEditor team
+
+### CSS Properties for Cursor Control
+
+```css
+/* Hide native caret */
+textarea {
+  caret-color: transparent;
+}
+
+/* Block cursor overlay */
+.vi-cursor {
+  position: absolute;
+  background-color: var(--cursor-color);
+  opacity: 0.7;
+  pointer-events: none;
+  animation: blink 1s step-end infinite;
+}
+
+@keyframes blink {
+  50% { opacity: 0; }
+}
+
+/* Different cursor styles by mode */
+.vi-cursor--normal {
+  width: 0.6em;  /* block width */
+  height: 1.2em;
+}
+
+.vi-cursor--insert {
+  width: 2px;  /* thin line */
+  height: 1.2em;
+}
+```
+
+### Scroll Synchronization
+
+When textarea scrolls, overlay must follow:
+```javascript
+textarea.addEventListener('scroll', () => {
+  cursorOverlay.style.transform =
+    `translate(-${textarea.scrollLeft}px, -${textarea.scrollTop}px)`;
+});
+```
+
+### Recommendation for Memory Loop
+
+**Approach B (Textarea + Overlay)** is the right balance:
+- Keeps existing textarea architecture
+- Adds overlay only when vi mode enabled
+- Mirror element library is ~2KB, well-tested
+- Can use `textarea-caret-position` npm package or implement core algorithm
+
+Implementation steps:
+1. Add cursor overlay div inside PairWritingEditor
+2. Calculate position on cursor move using mirror technique
+3. Toggle `caret-color: transparent` in Normal mode
+4. Sync overlay position on scroll
+5. Style overlay differently per mode
+
+### Sources
+
+- [textarea-caret-position](https://github.com/component/textarea-caret-position) - Mirror element library
+- [DEV.to: Calculate cursor coordinates](https://dev.to/phuocng/calculate-the-coordinates-of-the-current-cursor-in-a-text-area-cle) - Implementation walkthrough
+- [CodeMirror vim cursor issues](https://github.com/codemirror/codemirror5/issues/6312) - Empty line problem
+- [ContentEditable: The Good, Bad, Ugly](https://medium.com/content-uneditable/contenteditable-the-good-the-bad-and-the-ugly-261a38555e9c) - Why not contenteditable
+- [monaco-vim](https://github.com/brijeshb42/monaco-vim) - Monaco editor vim implementation
diff --git a/.lore/retros/vi-mode-pair-writing.md b/.lore/retros/vi-mode-pair-writing.md
new file mode 100644
index 00000000..d7e3322c
--- /dev/null
+++ b/.lore/retros/vi-mode-pair-writing.md
@@ -0,0 +1,48 @@
+# Retro: Vi Mode for Pair Writing
+
+## Summary
+
+Added vi-style modal editing to Pair Writing mode. Implementation includes Normal/Insert/Command modes, hjkl navigation, line operations (dd, yy, p, P), numeric prefixes, internal undo stack, ex commands (:w, :wq, :q, :q!), block cursor overlay, mode indicator, and auto-scrolling. Feature is gated on vault config toggle + keyboard detection.
+
+## What Went Well
+
+- **Detailed upfront planning paid off**: The 15-chunk breakdown with clear dependencies allowed systematic implementation without backtracking. Each chunk built cleanly on the previous.
+
+- **Hook-based architecture**: Isolating vi logic in `useViMode` and cursor logic in `useViCursor` made unit testing straightforward. 256 tests for the core hook alone.
+
+- **Spec constraints were realistic**: Explicitly scoping out Visual mode, word motions, and search kept the feature focused. No scope creep during implementation.
+
+- **The research phase identified the right approach**: Mirror element technique for cursor positioning was researched beforehand and worked well once correctly implemented.
+
+- **Incremental milestones**: Being able to see mode indicator and block cursor (Milestone A) before any commands worked provided early visual feedback.
+
+## What Could Improve
+
+- **Cursor overlay had multiple bugs**: The mirror element calculation had a fundamental error (measuring viewport-relative instead of mirror-relative), and the color choice made it invisible. Should have tested visually earlier in the process.
+
+- **Config state sync was incomplete**: Adding `viMode` to the schema wasn't enough - had to trace through multiple frontend state sync points (initialConfig in two places, reducer UPDATE_VAULT_CONFIG, VaultSelect setVaults). The data flow for config changes is more complex than the plan acknowledged.
+
+- **Scroll behavior with wrapped lines**: Line-based scroll calculation assumed 1 logical line = 1 visual line. Real documents have wrapped lines. Should have considered this in the plan.
+
+- **Testing in JSDOM vs real browser**: Some issues (cursor visibility, scroll behavior) only surfaced during manual testing. JSDOM tests passed but didn't catch visual/layout bugs.
+
+## Lessons Learned
+
+1. **Visual components need visual testing**: Unit tests for cursor position calculation passed, but the actual cursor was invisible. For overlay/positioning code, add a manual test checkpoint before declaring the chunk complete.
+
+2. **Trace config changes end-to-end**: When adding a new config field, grep for all places the config object is constructed, copied, or merged. In this codebase: shared schema, backend config loading, frontend initialConfig props (multiple components), reducer cases, and post-save state updates.
+
+3. **Text wrapping breaks line math**: Any calculation involving "line N is at position Y pixels" needs to account for soft wrapping. Use the same measurement technique (mirror element) for both cursor rendering and scroll calculations.
+
+4. **Polish emerges from use**: Auto-focus and auto-scroll weren't in the original spec but became obvious needs during real usage. Budget time for this "last 10%" polish.
+
+5. **Color visibility depends on context**: A color that's visible in isolation may not be visible when overlaid on similar colors. The cursor used `--color-text` which matched the text itself. Use accent colors for overlays.
+
+## Artifacts
+
+- Spec: `.lore/specs/vi-mode-pair-writing.md`
+- Plan: `.lore/plans/vi-mode-pair-writing.md`
+- Work breakdown: `.lore/work/vi-mode-pair-writing.md`
+- Research: `.lore/research/vi-mode-implementation.md`
+- Issue: #394
+- PR: #433
diff --git a/.lore/specs/vi-mode-pair-writing.md b/.lore/specs/vi-mode-pair-writing.md
new file mode 100644
index 00000000..b6174a9d
--- /dev/null
+++ b/.lore/specs/vi-mode-pair-writing.md
@@ -0,0 +1,65 @@
+# Spec: Vi Mode for Pair Writing
+
+## Overview
+
+Add vi-style modal editing to Pair Writing mode. When enabled via vault configuration, the editor operates in Normal mode by default where keystrokes execute navigation and editing commands rather than inserting text. Users enter Insert mode to type, and use ex commands (`:w`, `:wq`) to save and exit.
+
+## Requirements
+
+### Configuration
+- REQ-1: Add `viMode?: boolean` to VaultConfig interface
+- REQ-2: Vi mode setting read when entering Pair Writing (not live-monitored)
+- REQ-3: Vi mode only available when physical keyboard detected; disabled on touch-only devices
+
+### Modes
+- REQ-4: Support three modes: Normal (default), Insert, and Command
+- REQ-5: Mode indicator visible when vi mode enabled (e.g., "-- NORMAL --", "-- INSERT --")
+- REQ-6: Esc returns to Normal mode from Insert or Command mode
+
+### Normal Mode Commands
+- REQ-7: Movement: `h` (left), `j` (down), `k` (up), `l` (right)
+- REQ-8: Line movement: `0` (start of line), `$` (end of line)
+- REQ-9: Insert mode entry: `i` (before cursor), `a` (after cursor), `A` (end of line), `o` (new line below), `O` (new line above)
+- REQ-10: Delete: `x` (character), `dd` (line)
+- REQ-11: Yank/put: `yy` (copy line), `p` (paste after), `P` (paste before)
+- REQ-12: Undo: `u` undoes last edit operation (maintains internal undo stack)
+- REQ-13: Numeric prefixes: `[count]` before commands (e.g., `5j` moves 5 lines)
+
+### Command Mode
+- REQ-14: `:` in Normal mode opens command input
+- REQ-15: `:w` saves file, remains in Pair Writing
+- REQ-16: `:wq` saves file and exits Pair Writing
+- REQ-17: `:q` exits if no unsaved changes; shows confirmation dialog if unsaved
+- REQ-18: `:q!` exits without saving (discards changes)
+- REQ-19: `Esc` or empty input cancels command mode
+
+### Internal Clipboard
+- REQ-20: Yank/put operations use internal clipboard (separate from system)
+- REQ-21: Clipboard persists within Pair Writing session
+
+## Success Criteria
+
+- [ ] Vi mode toggle in `.memory-loop.json` enables modal editing
+- [ ] Mode indicator displays current mode
+- [ ] `hjkl` navigation works in Normal mode
+- [ ] `i`, `a`, `A`, `o`, `O` enter Insert mode at correct positions
+- [ ] Typing in Insert mode inserts text normally
+- [ ] Esc returns to Normal mode
+- [ ] `dd` deletes current line, `yy` copies it, `p` pastes
+- [ ] `u` undoes last edit operation
+- [ ] `5j` moves cursor down 5 lines
+- [ ] `:w` saves, `:wq` saves and exits, `:q` prompts if unsaved
+- [ ] Touch-only devices bypass vi mode (standard editing)
+
+## Constraints
+
+- No Visual mode in v1 (selection via standard touch/mouse)
+- No word motions (`w`, `b`, `e`) in v1
+- No search (`/`, `?`) in v1
+- No repeat command (`.`) in v1
+- Keyboard detection may not be 100% reliable; acceptable to have edge cases
+
+## Context
+
+- Research: `.lore/research/vi-mode-implementation.md`
+- Issue: #394
diff --git a/.lore/work/vi-mode-pair-writing.md b/.lore/work/vi-mode-pair-writing.md
new file mode 100644
index 00000000..acf26b24
--- /dev/null
+++ b/.lore/work/vi-mode-pair-writing.md
@@ -0,0 +1,242 @@
+# Work Breakdown: Vi Mode for Pair Writing
+
+Spec: `.lore/specs/vi-mode-pair-writing.md`
+Plan: `.lore/plans/vi-mode-pair-writing.md`
+
+## Chunks
+
+### 1. Configuration Layer ✓
+**What**: Add `viMode` to VaultConfig and flow it through to frontend
+**Delivers**: Config toggle that can be read in PairWritingEditor (no behavior change yet)
+**Depends on**: Nothing
+**Completed**: 2026-01-29
+
+Tasks:
+- Add `viMode?: boolean` to `VaultConfig` interface (backend)
+- Add `viMode?: boolean` to `VaultInfo` type (shared)
+- Add to `EditableVaultConfig` schema if user-editable, or just config file
+- Flow through vault discovery to API response
+- Verify config is accessible in `PairWritingMode` component
+
+### 2. Keyboard Detection ✓
+**What**: Detect physical keyboard presence, gate vi mode on it
+**Delivers**: `useHasKeyboard` hook that returns boolean; vi mode disabled on touch-only
+**Depends on**: Nothing (can parallel with Chunk 1)
+**Completed**: 2026-01-29
+
+Tasks:
+- Create `useHasKeyboard.ts` hook using matchMedia + maxTouchPoints
+- Add tests for detection logic (mock matchMedia)
+- Export from hooks index
+
+### 3. Vi Mode State Machine (Core) ✓
+**What**: Mode state management (normal/insert/command) and transitions
+**Delivers**: `useViMode` hook with mode state, no commands yet
+**Depends on**: Nothing (can parallel)
+**Completed**: 2026-01-29
+
+Tasks:
+- Create `useViMode.ts` with mode enum and state
+- Implement mode transitions: Normal↔Insert, Normal↔Command
+- Handle Esc key to return to Normal from any mode
+- Add `enabled` option to bypass when vi mode off
+- Unit tests for state transitions
+
+### 4. Cursor Overlay System ✓
+**What**: Block cursor rendering using mirror element technique
+**Delivers**: `useViCursor` hook + `ViCursor` component showing cursor position
+**Depends on**: Chunk 3 (needs mode to toggle cursor style)
+**Completed**: 2026-01-29
+
+Tasks:
+- Create `useViCursor.ts` with mirror element position calculation
+- Create `ViCursor.tsx` overlay component
+- Add `vi-mode.css` with cursor styles (block, blink animation)
+- Toggle `caret-color: transparent` based on mode
+- Handle scroll synchronization
+- Unit tests for position calculation
+
+### 5. Mode Indicator UI ✓
+**What**: Display current mode ("-- NORMAL --", "-- INSERT --", etc.)
+**Delivers**: `ViModeIndicator` component visible in editor
+**Depends on**: Chunk 3 (needs mode state)
+**Completed**: 2026-01-29
+
+Tasks:
+- Create `ViModeIndicator.tsx` component
+- Style to appear at bottom of editor (vim-style)
+- Show/hide based on vi mode enabled
+- Add to `vi-mode.css`
+
+### 6. Basic Movement Commands ✓
+**What**: `h`, `j`, `k`, `l`, `0`, `$` cursor movement
+**Delivers**: Navigation works in Normal mode
+**Depends on**: Chunks 3, 4 (need mode + cursor)
+**Completed**: 2026-01-29
+
+Tasks:
+- Add command dispatch to `useViMode`
+- Implement character movement (h, l) via selectionStart manipulation
+- Implement line movement (j, k) with line boundary detection
+- Implement line start/end (0, $)
+- Handle document boundaries (clamp, don't wrap)
+- Unit tests for each movement command
+
+### 7. Insert Mode Entry Commands ✓
+**What**: `i`, `a`, `A`, `o`, `O` to enter Insert mode
+**Delivers**: Can enter Insert mode at various positions
+**Depends on**: Chunk 6 (builds on cursor manipulation)
+**Completed**: 2026-01-29
+
+Tasks:
+- `i`: enter Insert at cursor
+- `a`: move right one, enter Insert
+- `A`: move to end of line, enter Insert
+- `o`: insert newline below, enter Insert
+- `O`: insert newline above, enter Insert
+- Unit tests for cursor position after each
+
+### 8. Undo Stack ✓
+**What**: Internal undo history for `u` command
+**Delivers**: Can undo edit operations
+**Depends on**: Chunk 3 (needs to hook into content changes)
+**Completed**: 2026-01-29
+
+Tasks:
+- Add undo stack to `useViMode` state
+- Push snapshot before edit operations
+- Implement `u` command to pop and restore
+- Batch Insert mode into single undo entry
+- Limit stack depth (100 entries)
+- Unit tests for undo behavior
+
+### 9. Delete Commands ✓
+**What**: `x` (character) and `dd` (line) deletion
+**Delivers**: Can delete content in Normal mode
+**Depends on**: Chunks 6, 8 (movement + undo)
+**Completed**: 2026-01-29
+
+Tasks:
+- Implement `x`: delete character at cursor
+- Implement `dd`: delete current line
+- Push to undo stack before delete
+- Update cursor position after delete
+- Handle edge cases (empty line, end of doc)
+- Unit tests
+
+### 10. Yank/Put Commands ✓
+**What**: `yy`, `p`, `P` with internal clipboard
+**Delivers**: Copy/paste lines within editor
+**Depends on**: Chunks 6, 8, 9 (movement, undo, line operations)
+**Completed**: 2026-01-29
+
+Tasks:
+- Add clipboard state to `useViMode`
+- Implement `yy`: copy current line to clipboard
+- Implement `p`: paste after cursor line
+- Implement `P`: paste before cursor line
+- Push to undo stack before paste
+- Unit tests
+
+### 11. Numeric Prefixes ✓
+**What**: Count prefix for commands (e.g., `5j`, `3dd`)
+**Delivers**: Commands can be repeated with count
+**Depends on**: Chunks 6, 9, 10 (needs commands to prefix)
+**Completed**: 2026-01-29
+
+Tasks:
+- Add `pendingCount` state to `useViMode`
+- Accumulate digits before command
+- Handle `0` special case (command vs. digit)
+- Pass count to command execution
+- Clear count after command or Esc
+- Unit tests for count accumulation and execution
+
+### 12. Command Mode UI ✓
+**What**: `:` command input field and parsing
+**Delivers**: Can type ex commands
+**Depends on**: Chunk 3 (needs Command mode state)
+**Completed**: 2026-01-29
+
+Tasks:
+- Create `ViCommandLine.tsx` component
+- Render at bottom of editor when mode is 'command'
+- Capture input until Enter or Esc
+- Focus management (focus input on enter, return on exit)
+- Add to `vi-mode.css`
+
+### 13. Ex Commands ✓
+**What**: `:w`, `:wq`, `:q`, `:q!` implementation
+**Delivers**: Can save and exit via commands
+**Depends on**: Chunk 12 (needs command input)
+**Completed**: 2026-01-29
+
+Tasks:
+- Parse command string in `useViMode`
+- `:w` → call `onSave` callback
+- `:wq` → call `onSave` then `onExit`
+- `:q` → check unsaved, call `onExit` or `onQuitWithUnsaved`
+- `:q!` → call `onExit` (discard)
+- Handle unknown commands (no-op or error indicator)
+- Unit tests for each command
+
+### 14. Integration ✓
+**What**: Wire everything into `PairWritingEditor`
+**Delivers**: Full vi mode working in Pair Writing
+**Depends on**: All previous chunks
+**Completed**: 2026-01-29
+
+Tasks:
+- Integrate `useViMode` into `PairWritingEditor`
+- Integrate `useViCursor` and `ViCursor`
+- Add `ViModeIndicator` and `ViCommandLine`
+- Pass callbacks (onSave, onExit, onQuitWithUnsaved)
+- Gate on `viMode` config + `hasKeyboard`
+- Integration tests
+
+### 15. Polish and Edge Cases ✓
+**What**: Handle remaining edge cases from review
+**Delivers**: Robust implementation
+**Depends on**: Chunk 14
+**Completed**: 2026-01-29
+
+Tasks:
+- Esc in Normal mode cancels pending operator/count ✓
+- Cursor boundary clamping (h at start, l at end) - verified existing tests
+- `dd` on empty document - verified existing tests
+- `p` with empty clipboard - verified existing tests
+- Interaction with `isProcessingQuickAction` state ✓
+- ViCommandLine converted to display-only (focus stays on textarea) ✓
+- Tests added for Escape clearing pending state in Normal mode
+
+## Suggested Order
+
+1. ~~**Chunk 1** (Configuration) - Foundation, quick win~~ ✓
+2. ~~**Chunk 2** (Keyboard Detection) - Can parallel with 1~~ ✓
+3. ~~**Chunk 3** (State Machine) - Core architecture, can parallel~~ ✓
+4. ~~**Chunk 4** (Cursor Overlay) - Visual feedback, depends on 3~~ ✓
+5. ~~**Chunk 5** (Mode Indicator) - Quick UI win, depends on 3~~ ✓
+6. ~~**Chunk 6** (Basic Movement) - First real vi behavior~~ ✓
+7. ~~**Chunk 7** (Insert Entry) - Can now edit text~~ ✓
+8. ~~**Chunk 8** (Undo Stack) - Safety net before destructive commands~~ ✓
+9. ~~**Chunk 9** (Delete) - First destructive command~~ ✓
+10. ~~**Chunk 10** (Yank/Put) - Copy/paste~~ ✓
+11. ~~**Chunk 11** (Numeric Prefixes) - Power user feature~~ ✓
+12. ~~**Chunk 12** (Command Mode UI) - Needed for ex commands~~ ✓
+13. ~~**Chunk 13** (Ex Commands) - Save/exit flow~~ ✓
+14. ~~**Chunk 14** (Integration) - Wire it all together~~ ✓
+15. ~~**Chunk 15** (Polish) - Edge cases and hardening~~ ✓
+
+## Release Points
+
+**Milestone A (Chunks 1-5)**: ✓ COMPLETE (2026-01-29)
+Vi mode toggle works, shows mode indicator and block cursor. No commands yet, but visual infrastructure complete.
+
+**Milestone B (Chunks 6-7)**: ✓ COMPLETE (2026-01-29)
+Navigation and insert mode work. Can move around and type text.
+
+**Milestone C (Chunks 8-11)**: ✓ COMPLETE (2026-01-29)
+Full Normal mode editing. Delete, yank, put, undo, counts all work.
+
+**Milestone D (Chunks 12-15)**: ✓ COMPLETE (2026-01-29)
+Complete feature. Ex commands for save/exit, full integration, polished. Edge cases handled.
diff --git a/backend/src/__tests__/meeting-capture.test.ts b/backend/src/__tests__/meeting-capture.test.ts
index 00488c9a..5e15bf7b 100644
--- a/backend/src/__tests__/meeting-capture.test.ts
+++ b/backend/src/__tests__/meeting-capture.test.ts
@@ -195,6 +195,7 @@ describe("getMeetingsDirectory", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
     const dir = getMeetingsDirectory(vault);
     expect(dir).toBe("/vaults/test/00_Inbox/meetings");
@@ -217,6 +218,7 @@ describe("getMeetingsDirectory", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
     const dir = getMeetingsDirectory(vault);
     expect(dir).toBe("/vaults/custom/Custom/Inbox/meetings");
@@ -380,6 +382,7 @@ describe("startMeeting Integration", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
   });
 
@@ -493,6 +496,7 @@ describe("captureToMeeting Integration", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
 
     // Start a meeting to get active meeting state
@@ -619,6 +623,7 @@ describe("stopMeeting Integration", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
   });
 
@@ -724,6 +729,7 @@ describe("Edge Cases", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
   });
 
diff --git a/backend/src/__tests__/note-capture.test.ts b/backend/src/__tests__/note-capture.test.ts
index af990365..3b61f6a1 100644
--- a/backend/src/__tests__/note-capture.test.ts
+++ b/backend/src/__tests__/note-capture.test.ts
@@ -581,6 +581,7 @@ describe("captureToDaily Integration", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
   });
 
@@ -812,6 +813,7 @@ describe("Edge Cases", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
   });
 
diff --git a/backend/src/__tests__/session-manager.test.ts b/backend/src/__tests__/session-manager.test.ts
index abd1b88e..8d7bd60f 100644
--- a/backend/src/__tests__/session-manager.test.ts
+++ b/backend/src/__tests__/session-manager.test.ts
@@ -70,6 +70,7 @@ function createMockVault(overrides: Partial<VaultInfo> = {}): VaultInfo {
     ...overrides,
     order: overrides.order ?? 999999,
     cardsEnabled: overrides.cardsEnabled ?? true,
+    viMode: overrides.viMode ?? false,
   };
 }
 
diff --git a/backend/src/__tests__/test-helpers.ts b/backend/src/__tests__/test-helpers.ts
index 21a36523..9a85edbe 100644
--- a/backend/src/__tests__/test-helpers.ts
+++ b/backend/src/__tests__/test-helpers.ts
@@ -34,6 +34,8 @@ export function createMockVault(overrides: Partial<VaultInfo> = {}): VaultInfo {
     order: overrides.order ?? 999999,
     // Ensure cardsEnabled is always a boolean
     cardsEnabled: overrides.cardsEnabled ?? true,
+    // Ensure viMode is always a boolean
+    viMode: overrides.viMode ?? false,
   };
 }
 
diff --git a/backend/src/__tests__/transcript-manager.test.ts b/backend/src/__tests__/transcript-manager.test.ts
index 0886a8b5..836e30b9 100644
--- a/backend/src/__tests__/transcript-manager.test.ts
+++ b/backend/src/__tests__/transcript-manager.test.ts
@@ -324,6 +324,7 @@ describe("getTranscriptsDirectory", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
     const dir = getTranscriptsDirectory(vault);
     expect(dir).toBe("/vaults/test-vault/00_Inbox/chats");
@@ -346,6 +347,7 @@ describe("getTranscriptsDirectory", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
     const dir = getTranscriptsDirectory(vault);
     expect(dir).toBe("/vaults/test-vault/Custom/Inbox/chats");
@@ -368,6 +370,7 @@ describe("getTranscriptsDirectory", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
     const dir = getTranscriptsDirectory(vault);
     expect(dir).toBe("/vaults/test-vault/content/00_Inbox/chats");
@@ -428,6 +431,7 @@ describe("Transcript Integration", () => {
       badges: [],
       order: 999999,
     cardsEnabled: true,
+      viMode: false,
     };
   });
 
diff --git a/backend/src/__tests__/vault-config.test.ts b/backend/src/__tests__/vault-config.test.ts
index 86e7d642..1212bd30 100644
--- a/backend/src/__tests__/vault-config.test.ts
+++ b/backend/src/__tests__/vault-config.test.ts
@@ -20,6 +20,7 @@ import {
   DEFAULT_QUOTES_PER_WEEK,
   DEFAULT_DISCUSSION_MODEL,
   DEFAULT_CARDS_ENABLED,
+  DEFAULT_VI_MODE,
   VALID_DISCUSSION_MODELS,
   loadVaultConfig,
   loadSlashCommands,
@@ -37,6 +38,7 @@ import {
   resolvePinnedAssets,
   resolveDiscussionModel,
   resolveCardsEnabled,
+  resolveViMode,
   saveSlashCommands,
   savePinnedAssets,
   saveVaultConfig,
@@ -124,6 +126,12 @@ describe("vault-config", () => {
     });
   });
 
+  describe("DEFAULT_VI_MODE", () => {
+    test("exports expected default vi mode value", () => {
+      expect(DEFAULT_VI_MODE).toBe(false);
+    });
+  });
+
   describe("loadVaultConfig", () => {
     test("returns empty object when no config file exists", async () => {
       const config = await loadVaultConfig(testDir);
@@ -856,6 +864,84 @@ describe("vault-config", () => {
     });
   });
 
+  describe("loadVaultConfig with viMode", () => {
+    test("loads config with viMode true", async () => {
+      await writeFile(
+        join(testDir, CONFIG_FILE_NAME),
+        JSON.stringify({ viMode: true })
+      );
+
+      const config = await loadVaultConfig(testDir);
+      expect(config.viMode).toBe(true);
+    });
+
+    test("loads config with viMode false", async () => {
+      await writeFile(
+        join(testDir, CONFIG_FILE_NAME),
+        JSON.stringify({ viMode: false })
+      );
+
+      const config = await loadVaultConfig(testDir);
+      expect(config.viMode).toBe(false);
+    });
+
+    test("ignores non-boolean viMode value", async () => {
+      await writeFile(
+        join(testDir, CONFIG_FILE_NAME),
+        JSON.stringify({ viMode: "true" })
+      );
+
+      const config = await loadVaultConfig(testDir);
+      expect(config.viMode).toBeUndefined();
+    });
+
+    test("ignores numeric viMode value", async () => {
+      await writeFile(
+        join(testDir, CONFIG_FILE_NAME),
+        JSON.stringify({ viMode: 1 })
+      );
+
+      const config = await loadVaultConfig(testDir);
+      expect(config.viMode).toBeUndefined();
+    });
+
+    test("loads viMode alongside other fields", async () => {
+      await writeFile(
+        join(testDir, CONFIG_FILE_NAME),
+        JSON.stringify({
+          contentRoot: "content",
+          viMode: true,
+        })
+      );
+
+      const config = await loadVaultConfig(testDir);
+      expect(config.contentRoot).toBe("content");
+      expect(config.viMode).toBe(true);
+    });
+  });
+
+  describe("resolveViMode", () => {
+    test("returns default (false) when viMode not configured", () => {
+      const result = resolveViMode({});
+      expect(result).toBe(false);
+    });
+
+    test("returns default (false) when viMode is undefined", () => {
+      const result = resolveViMode({ viMode: undefined });
+      expect(result).toBe(false);
+    });
+
+    test("returns true when viMode is true", () => {
+      const result = resolveViMode({ viMode: true });
+      expect(result).toBe(true);
+    });
+
+    test("returns false when viMode is false", () => {
+      const result = resolveViMode({ viMode: false });
+      expect(result).toBe(false);
+    });
+  });
+
   describe("loadSlashCommands", () => {
     test("returns undefined when cache file does not exist", async () => {
       const commands = await loadSlashCommands(testDir);
@@ -1778,5 +1864,60 @@ describe("vault-config", () => {
       expect(parsed.cardsEnabled).toBe(true);
       expect(parsed.title).toBe("Vault");
     });
+
+    test("saves viMode field correctly", async () => {
+      const editableConfig: EditableVaultConfig = {
+        title: "Test Vault",
+        viMode: true,
+      };
+      const result = await saveVaultConfig(testDir, editableConfig);
+
+      expect(result).toEqual({ success: true });
+
+      const content = await readFile(join(testDir, CONFIG_FILE_NAME), "utf-8");
+      const parsed = JSON.parse(content) as Record<string, unknown>;
+      expect(parsed.title).toBe("Test Vault");
+      expect(parsed.viMode).toBe(true);
+    });
+
+    test("preserves viMode true when updating other fields", async () => {
+      // Create existing config with viMode
+      await writeFile(
+        join(testDir, CONFIG_FILE_NAME),
+        JSON.stringify({ viMode: true })
+      );
+
+      const editableConfig: EditableVaultConfig = {
+        title: "New Title",
+      };
+      const result = await saveVaultConfig(testDir, editableConfig);
+
+      expect(result).toEqual({ success: true });
+
+      const content = await readFile(join(testDir, CONFIG_FILE_NAME), "utf-8");
+      const parsed = JSON.parse(content) as Record<string, unknown>;
+      expect(parsed.title).toBe("New Title");
+      expect(parsed.viMode).toBe(true);
+    });
+
+    test("updates viMode when explicitly set", async () => {
+      // Create existing config with viMode true
+      await writeFile(
+        join(testDir, CONFIG_FILE_NAME),
+        JSON.stringify({ viMode: true, title: "Vault" })
+      );
+
+      const editableConfig: EditableVaultConfig = {
+        viMode: false,
+      };
+      const result = await saveVaultConfig(testDir, editableConfig);
+
+      expect(result).toEqual({ success: true });
+
+      const content = await readFile(join(testDir, CONFIG_FILE_NAME), "utf-8");
+      const parsed = JSON.parse(content) as Record<string, unknown>;
+      expect(parsed.viMode).toBe(false);
+      expect(parsed.title).toBe("Vault");
+    });
   });
 });
diff --git a/backend/src/__tests__/vault-manager.test.ts b/backend/src/__tests__/vault-manager.test.ts
index 49957804..5d7b3e55 100644
--- a/backend/src/__tests__/vault-manager.test.ts
+++ b/backend/src/__tests__/vault-manager.test.ts
@@ -662,6 +662,7 @@ describe("Filesystem Integration", () => {
         badges: [],
         order: 999999,
     cardsEnabled: true,
+      viMode: false,
       };
 
       expect(getVaultInboxPath(vault)).toBe("/vaults/test-vault/00_Inbox");
@@ -684,6 +685,7 @@ describe("Filesystem Integration", () => {
         badges: [],
         order: 999999,
     cardsEnabled: true,
+      viMode: false,
       };
 
       expect(getVaultInboxPath(vault)).toBe("/vaults/test-vault/Custom/Inbox");
@@ -706,6 +708,7 @@ describe("Filesystem Integration", () => {
         badges: [],
         order: 999999,
     cardsEnabled: true,
+      viMode: false,
       };
 
       expect(getVaultInboxPath(vault)).toBe("/vaults/test-vault/content/00_Inbox");
@@ -898,6 +901,7 @@ describe("Goals Feature", () => {
         badges: [],
         order: 999999,
     cardsEnabled: true,
+      viMode: false,
       };
 
       const goals = await getVaultGoals(vault);
@@ -933,6 +937,7 @@ describe("Goals Feature", () => {
         badges: [],
         order: 999999,
     cardsEnabled: true,
+      viMode: false,
       };
 
       const content = await getVaultGoals(vault);
@@ -957,6 +962,7 @@ describe("Goals Feature", () => {
         badges: [],
         order: 999999,
     cardsEnabled: true,
+      viMode: false,
       };
 
       const goals = await getVaultGoals(vault);
diff --git a/backend/src/__tests__/vault-resolution.test.ts b/backend/src/__tests__/vault-resolution.test.ts
index 2fe776ab..35cc0561 100644
--- a/backend/src/__tests__/vault-resolution.test.ts
+++ b/backend/src/__tests__/vault-resolution.test.ts
@@ -355,6 +355,7 @@ describe("getVaultFromContext", () => {
         badges: [],
         order: Infinity,
         cardsEnabled: true,
+      viMode: false,
       };
       c.set("vault", mockVault);
 
diff --git a/backend/src/__tests__/websocket-handler.test.ts b/backend/src/__tests__/websocket-handler.test.ts
index 07f8f66d..9072d583 100644
--- a/backend/src/__tests__/websocket-handler.test.ts
+++ b/backend/src/__tests__/websocket-handler.test.ts
@@ -322,6 +322,7 @@ function createMockVault(overrides: Partial<VaultInfo> = {}): VaultInfo {
     ...overrides,
     order: overrides.order ?? 999999,
     cardsEnabled: overrides.cardsEnabled ?? true,
+    viMode: overrides.viMode ?? false,
   };
 }
 
diff --git a/backend/src/handlers/__tests__/pair-writing-handlers.test.ts b/backend/src/handlers/__tests__/pair-writing-handlers.test.ts
index 5d335ef5..3deef1b6 100644
--- a/backend/src/handlers/__tests__/pair-writing-handlers.test.ts
+++ b/backend/src/handlers/__tests__/pair-writing-handlers.test.ts
@@ -52,6 +52,7 @@ beforeEach(async () => {
     badges: [],
     order: 0,
     cardsEnabled: true,
+      viMode: false,
   };
   sentMessages = [];
   sentErrors = [];
diff --git a/backend/src/vault-config.ts b/backend/src/vault-config.ts
index 98cd81d7..84bb3619 100644
--- a/backend/src/vault-config.ts
+++ b/backend/src/vault-config.ts
@@ -150,6 +150,13 @@ export interface VaultConfig {
    * Default: true
    */
   cardsEnabled?: boolean;
+
+  /**
+   * Whether vi mode is enabled for the Pair Writing editor.
+   * When true, the editor uses vi-style keybindings.
+   * Default: false
+   */
+  viMode?: boolean;
 }
 
 /**
@@ -225,6 +232,12 @@ export const DEFAULT_ORDER = 999999;
  */
 export const DEFAULT_CARDS_ENABLED = true;
 
+/**
+ * Default value for vi mode in Pair Writing editor.
+ * When false (default), the editor uses standard keybindings.
+ */
+export const DEFAULT_VI_MODE = false;
+
 /**
  * Valid badge color names.
  */
@@ -337,6 +350,11 @@ export async function loadVaultConfig(vaultPath: string): Promise<VaultConfig> {
       config.cardsEnabled = obj.cardsEnabled;
     }
 
+    // Validate viMode (must be a boolean)
+    if (typeof obj.viMode === "boolean") {
+      config.viMode = obj.viMode;
+    }
+
     // Validate badges array
     if (Array.isArray(obj.badges)) {
       config.badges = obj.badges.filter(
@@ -569,6 +587,16 @@ export function resolveCardsEnabled(config: VaultConfig): boolean {
   return config.cardsEnabled ?? DEFAULT_CARDS_ENABLED;
 }
 
+/**
+ * Resolves whether vi mode is enabled for Pair Writing editor.
+ *
+ * @param config - Vault configuration
+ * @returns true if vi mode is enabled (default: false)
+ */
+export function resolveViMode(config: VaultConfig): boolean {
+  return config.viMode ?? DEFAULT_VI_MODE;
+}
+
 /**
  * Saves pinned assets to the vault configuration file.
  * Preserves existing configuration fields while updating pinnedAssets.
@@ -624,7 +652,8 @@ function isAllDefaults(config: EditableVaultConfig): boolean {
     config.recentDiscussions === undefined &&
     (config.badges === undefined || config.badges.length === 0) &&
     config.order === undefined &&
-    config.cardsEnabled === undefined
+    config.cardsEnabled === undefined &&
+    config.viMode === undefined
   );
 }
 
@@ -707,6 +736,9 @@ export async function saveVaultConfig(
     if (editableConfig.cardsEnabled !== undefined) {
       mergedConfig.cardsEnabled = editableConfig.cardsEnabled;
     }
+    if (editableConfig.viMode !== undefined) {
+      mergedConfig.viMode = editableConfig.viMode;
+    }
 
     // Write merged config back to file
     await writeFile(configPath, JSON.stringify(mergedConfig, null, 2) + "\n", "utf-8");
diff --git a/backend/src/vault-manager.ts b/backend/src/vault-manager.ts
index 2fb084ac..95cebf08 100644
--- a/backend/src/vault-manager.ts
+++ b/backend/src/vault-manager.ts
@@ -25,6 +25,7 @@ import {
   resolveBadges,
   resolveOrder,
   resolveCardsEnabled,
+  resolveViMode,
   type VaultConfig,
 } from "./vault-config";
 
@@ -343,6 +344,7 @@ export async function parseVault(
     badges: resolveBadges(config),
     order: resolveOrder(config),
     cardsEnabled: resolveCardsEnabled(config),
+    viMode: resolveViMode(config),
   };
 }
 
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index a40ddf9f..b5209aa8 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -261,6 +261,7 @@ function MainContent(): React.ReactNode {
             badges: vault.badges,
             order: vault.order === Infinity ? undefined : vault.order,
             cardsEnabled: vault.cardsEnabled,
+            viMode: vault.viMode,
           }}
           onSave={handleConfigSave}
           onCancel={handleConfigCancel}
diff --git a/frontend/src/components/browse/__tests__/BrowseMode.test.tsx b/frontend/src/components/browse/__tests__/BrowseMode.test.tsx
index 557873de..d002961c 100644
--- a/frontend/src/components/browse/__tests__/BrowseMode.test.tsx
+++ b/frontend/src/components/browse/__tests__/BrowseMode.test.tsx
@@ -68,6 +68,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 const mockDirectoryEntries: FileEntry[] = [
diff --git a/frontend/src/components/capture/__tests__/NoteCapture.test.tsx b/frontend/src/components/capture/__tests__/NoteCapture.test.tsx
index 1042ae83..9823f4b3 100644
--- a/frontend/src/components/capture/__tests__/NoteCapture.test.tsx
+++ b/frontend/src/components/capture/__tests__/NoteCapture.test.tsx
@@ -28,6 +28,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 // Mock matchMedia for touch device detection
diff --git a/frontend/src/components/discussion/__tests__/Discussion.test.tsx b/frontend/src/components/discussion/__tests__/Discussion.test.tsx
index aeb8b297..b4f1d9f4 100644
--- a/frontend/src/components/discussion/__tests__/Discussion.test.tsx
+++ b/frontend/src/components/discussion/__tests__/Discussion.test.tsx
@@ -80,6 +80,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 function TestWrapper({ children }: { children: ReactNode }) {
diff --git a/frontend/src/components/home/__tests__/HealthPanel.test.tsx b/frontend/src/components/home/__tests__/HealthPanel.test.tsx
index fac723de..3cee9c08 100644
--- a/frontend/src/components/home/__tests__/HealthPanel.test.tsx
+++ b/frontend/src/components/home/__tests__/HealthPanel.test.tsx
@@ -66,6 +66,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 beforeEach(() => {
diff --git a/frontend/src/components/home/__tests__/HomeView.test.tsx b/frontend/src/components/home/__tests__/HomeView.test.tsx
index 6ef53193..00c60c0f 100644
--- a/frontend/src/components/home/__tests__/HomeView.test.tsx
+++ b/frontend/src/components/home/__tests__/HomeView.test.tsx
@@ -267,6 +267,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 /**
diff --git a/frontend/src/components/home/__tests__/InspirationCard.test.tsx b/frontend/src/components/home/__tests__/InspirationCard.test.tsx
index 30047d8c..d1b1b2af 100644
--- a/frontend/src/components/home/__tests__/InspirationCard.test.tsx
+++ b/frontend/src/components/home/__tests__/InspirationCard.test.tsx
@@ -28,6 +28,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 const mockContextual: InspirationItem = {
diff --git a/frontend/src/components/home/__tests__/RecentActivity.test.tsx b/frontend/src/components/home/__tests__/RecentActivity.test.tsx
index d36a844a..0e5b5b4d 100644
--- a/frontend/src/components/home/__tests__/RecentActivity.test.tsx
+++ b/frontend/src/components/home/__tests__/RecentActivity.test.tsx
@@ -39,6 +39,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 const mockCaptures: RecentNoteEntry[] = [
diff --git a/frontend/src/components/pair-writing/PairWritingEditor.tsx b/frontend/src/components/pair-writing/PairWritingEditor.tsx
index d7d2777d..6999451e 100644
--- a/frontend/src/components/pair-writing/PairWritingEditor.tsx
+++ b/frontend/src/components/pair-writing/PairWritingEditor.tsx
@@ -6,6 +6,12 @@
  *
  * Unlike MemoryEditor, this component receives content via props rather than
  * fetching a specific file, making it suitable for editing any vault file.
+ *
+ * Optionally supports vi mode editing (when viModeEnabled prop is true and
+ * a physical keyboard is detected). Vi mode provides vim-style navigation
+ * and commands for power users.
+ *
+ * @see .lore/specs/vi-mode-pair-writing.md
  */
 
 import { useState, useCallback, useEffect, useRef } from "react";
@@ -25,7 +31,14 @@ import {
   useTextSelection,
   type SelectionContext,
 } from "../../hooks/useTextSelection";
+import { useHasKeyboard } from "../../hooks/useHasKeyboard";
+import { useViMode } from "../../hooks/useViMode";
+import { useViCursor } from "../../hooks/useViCursor";
+import { ViCursor } from "./ViCursor";
+import { ViModeIndicator } from "./ViModeIndicator";
+import { ViCommandLine } from "./ViCommandLine";
 import "./PairWritingEditor.css";
+import "./vi-mode.css";
 
 export interface PairWritingEditorProps {
   initialContent: string;
@@ -50,6 +63,14 @@ export interface PairWritingEditorProps {
   ContextMenuComponent?: typeof EditorContextMenu;
   /** Increment this to trigger opening the context menu (for toolbar Actions button) */
   openMenuTrigger?: number;
+  /** Whether vi mode is enabled for this vault (from vault config) */
+  viModeEnabled?: boolean;
+  /** Called when vi mode :w or :wq command is executed */
+  onSave?: () => void;
+  /** Called when vi mode :q! or :wq command is executed */
+  onExit?: () => void;
+  /** Called when vi mode :q command is executed with unsaved changes */
+  onQuitWithUnsaved?: () => void;
 }
 
 export function PairWritingEditor({
@@ -65,6 +86,10 @@ export function PairWritingEditor({
   hasSnapshot = false,
   ContextMenuComponent = EditorContextMenu,
   openMenuTrigger = 0,
+  viModeEnabled = false,
+  onSave,
+  onExit,
+  onQuitWithUnsaved,
 }: PairWritingEditorProps): React.ReactNode {
   const [content, setContent] = useState(initialContent);
   const [menuOpen, setMenuOpen] = useState(false);
@@ -74,8 +99,59 @@ export function PairWritingEditor({
 
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
 
+  // Auto-focus textarea on mount so user can start typing immediately
+  useEffect(() => {
+    textareaRef.current?.focus();
+  }, []);
+
   const { selection } = useTextSelection(textareaRef, content);
 
+  // Vi mode integration
+  // Only enable vi mode if the vault has it enabled AND a keyboard is detected
+  const hasKeyboard = useHasKeyboard();
+  const viEnabled = viModeEnabled && hasKeyboard;
+
+  // Track cursor position for vi mode overlay
+  const [cursorPosition, setCursorPosition] = useState(0);
+
+  // Handle content changes from vi mode commands
+  const handleViContentChange = useCallback(
+    (newContent: string) => {
+      setContent(newContent);
+      onContentChange?.(newContent);
+    },
+    [onContentChange]
+  );
+
+  // Vi mode hook provides mode state, key handler, and command buffer
+  const {
+    mode: viMode,
+    handleKeyDown: viHandleKeyDown,
+    commandBuffer,
+  } = useViMode({
+    enabled: viEnabled,
+    textareaRef,
+    onSave,
+    onExit,
+    onQuitWithUnsaved,
+    onContentChange: handleViContentChange,
+  });
+
+  // Vi cursor hook provides cursor overlay positioning
+  const { cursorStyle, showOverlay } = useViCursor({
+    textareaRef,
+    cursorPosition,
+    mode: viMode,
+    enabled: viEnabled,
+  });
+
+  // Update cursor position when textarea selection changes
+  const handleSelect = useCallback(() => {
+    if (textareaRef.current) {
+      setCursorPosition(textareaRef.current.selectionStart);
+    }
+  }, []);
+
   // Notify parent when selection changes
   useEffect(() => {
     onSelectionChange?.(selection);
@@ -135,10 +211,28 @@ export function PairWritingEditor({
       const newContent = e.target.value;
       setContent(newContent);
       onContentChange?.(newContent);
+      // Update cursor position for vi mode overlay
+      setCursorPosition(e.target.selectionStart);
     },
     [onContentChange]
   );
 
+  // Handle keydown: pass through vi mode handler when enabled
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      viHandleKeyDown(e);
+      // Update cursor position after key processing
+      // Use requestAnimationFrame to ensure we get the updated position
+      // after the key event is processed
+      requestAnimationFrame(() => {
+        if (textareaRef.current) {
+          setCursorPosition(textareaRef.current.selectionStart);
+        }
+      });
+    },
+    [viHandleKeyDown]
+  );
+
   const openContextMenu = useCallback((position: MenuPosition) => {
     if (!selectionRef.current) return;
     setMenuPosition(position);
@@ -204,19 +298,42 @@ export function PairWritingEditor({
   const processingClass = isProcessingQuickAction ? " pair-writing-editor--processing" : "";
   const textareaProcessingClass = isProcessingQuickAction ? " pair-writing-editor__textarea--processing" : "";
 
+  // Vi mode adds classes to hide native caret when in normal/command mode
+  const viModeClass = viEnabled && viMode === "normal" ? " pair-writing-editor__textarea--vi-normal" : "";
+  const viCommandClass = viEnabled && viMode === "command" ? " pair-writing-editor__textarea--vi-command" : "";
+
   return (
     <div className={`pair-writing-editor${processingClass}`}>
       <textarea
         ref={textareaRef}
-        className={`pair-writing-editor__textarea${textareaProcessingClass}`}
+        className={`pair-writing-editor__textarea${textareaProcessingClass}${viModeClass}${viCommandClass}`}
         value={content}
         onChange={handleChange}
+        onKeyDown={handleKeyDown}
+        onSelect={handleSelect}
         onContextMenu={handleContextMenu}
         spellCheck={false}
         disabled={isProcessingQuickAction}
         aria-label="Document editor"
       />
 
+      {/* Vi mode cursor overlay - shown in normal/command mode */}
+      <ViCursor style={cursorStyle} visible={showOverlay} />
+
+      {/* Vi mode indicator - shows current mode at bottom of editor */}
+      <ViModeIndicator
+        mode={viMode}
+        visible={viEnabled}
+        commandBuffer={commandBuffer}
+      />
+
+      {/* Vi command line - shown when in command mode for ex commands */}
+      {/* Hidden during quick action processing to prevent interference */}
+      <ViCommandLine
+        visible={viEnabled && viMode === "command" && !isProcessingQuickAction}
+        value={commandBuffer}
+      />
+
       {isProcessingQuickAction && (
         <div className="pair-writing-editor__processing-overlay">
           <div className="pair-writing-editor__processing-spinner" />
diff --git a/frontend/src/components/pair-writing/PairWritingMode.tsx b/frontend/src/components/pair-writing/PairWritingMode.tsx
index aad95c64..a3711471 100644
--- a/frontend/src/components/pair-writing/PairWritingMode.tsx
+++ b/frontend/src/components/pair-writing/PairWritingMode.tsx
@@ -86,7 +86,10 @@ export function PairWritingMode({
 }: PairWritingModeProps): React.ReactNode {
   void _assetBaseUrl; // Preserved for interface stability; Discussion handles its own asset resolution
   const { state, actions } = usePairWritingState();
-  const { addMessage } = useSession();
+  const { addMessage, vault } = useSession();
+
+  // Get vi mode setting from vault config
+  const viModeEnabled = vault?.viMode ?? false;
   const [showExitConfirm, setShowExitConfirm] = useState(false);
   const [isSaving, setIsSaving] = useState(false);
   const [currentSelection, setCurrentSelection] = useState<SelectionContext | null>(null);
@@ -151,6 +154,24 @@ export function PairWritingMode({
     }
   }, [state.hasUnsavedChanges, actions, onExit]);
 
+  // Handle vi mode :q command with unsaved changes
+  // Shows the exit confirmation dialog just like clicking Exit button
+  const handleViQuitWithUnsaved = useCallback(() => {
+    if (state.hasUnsavedChanges) {
+      setShowExitConfirm(true);
+    } else {
+      // No unsaved changes, exit directly
+      actions.clearAll();
+      onExit();
+    }
+  }, [state.hasUnsavedChanges, actions, onExit]);
+
+  // Handle vi mode :q! command (force quit without saving)
+  const handleViForceExit = useCallback(() => {
+    actions.clearAll();
+    onExit();
+  }, [actions, onExit]);
+
   // Confirm exit with unsaved changes
   const handleConfirmExit = useCallback(() => {
     setShowExitConfirm(false);
@@ -264,6 +285,10 @@ export function PairWritingMode({
             hasSnapshot={state.snapshot !== null}
             snapshotContent={state.snapshot ?? undefined}
             openMenuTrigger={openMenuTrigger}
+            viModeEnabled={viModeEnabled}
+            onSave={handleSave}
+            onExit={handleViForceExit}
+            onQuitWithUnsaved={handleViQuitWithUnsaved}
           />
         </div>
 
diff --git a/frontend/src/components/pair-writing/ViCommandLine.tsx b/frontend/src/components/pair-writing/ViCommandLine.tsx
new file mode 100644
index 00000000..11f4e80c
--- /dev/null
+++ b/frontend/src/components/pair-writing/ViCommandLine.tsx
@@ -0,0 +1,74 @@
+/**
+ * ViCommandLine Component - Ex Command Display for Vi Mode
+ *
+ * Renders a vim-style command line display at the bottom of the editor.
+ * Appears when user presses ':' in Normal mode. Shows a ":" prefix
+ * followed by the current command buffer text.
+ *
+ * This is a pure display component: all keyboard input is handled by
+ * useViMode through the textarea's keydown events. The textarea retains
+ * focus while in command mode; this component just displays what's being
+ * typed.
+ *
+ * @see .lore/specs/vi-mode-pair-writing.md (REQ-14, REQ-19)
+ * @see .lore/plans/vi-mode-pair-writing.md (TD-5)
+ */
+
+import "./vi-mode.css";
+
+export interface ViCommandLineProps {
+  /** Whether the command line should be visible */
+  visible: boolean;
+  /** Current command buffer value (without the leading colon) */
+  value: string;
+}
+
+/**
+ * Vim-style command line display.
+ *
+ * This component renders at the bottom of the editor container, showing
+ * a ":" prefix followed by the command buffer text. The textarea retains
+ * focus; this is a pure display component.
+ *
+ * Key events are handled by useViMode through the textarea's onKeyDown,
+ * which updates the command buffer.
+ *
+ * @example
+ * ```tsx
+ * const { mode, commandBuffer } = useViMode({...});
+ *
+ * return (
+ *   <div className="pair-writing-editor">
+ *     <textarea onKeyDown={handleKeyDown} />
+ *     <ViCommandLine
+ *       visible={mode === "command"}
+ *       value={commandBuffer}
+ *     />
+ *   </div>
+ * );
+ * ```
+ */
+export function ViCommandLine({
+  visible,
+  value,
+}: ViCommandLineProps): React.ReactNode {
+  if (!visible) {
+    return null;
+  }
+
+  return (
+    <div
+      className="vi-command-line"
+      data-testid="vi-command-line"
+      role="status"
+      aria-label="Vi command line"
+      aria-live="polite"
+    >
+      <span className="vi-command-line__prefix" aria-hidden="true">
+        :
+      </span>
+      <span className="vi-command-line__text">{value}</span>
+      <span className="vi-command-line__cursor" aria-hidden="true" />
+    </div>
+  );
+}
diff --git a/frontend/src/components/pair-writing/ViCursor.tsx b/frontend/src/components/pair-writing/ViCursor.tsx
new file mode 100644
index 00000000..2e907b21
--- /dev/null
+++ b/frontend/src/components/pair-writing/ViCursor.tsx
@@ -0,0 +1,64 @@
+/**
+ * ViCursor Component - Block Cursor Overlay for Vi Mode
+ *
+ * Renders a block cursor overlay for vi normal mode. The cursor is positioned
+ * absolutely within the editor container, showing the current cursor position
+ * with a semi-transparent background and blink animation.
+ *
+ * @see .lore/plans/vi-mode-pair-writing.md (TD-10)
+ */
+
+import type { CSSProperties } from "react";
+import "./vi-mode.css";
+
+export interface ViCursorProps {
+  /** CSS style containing top, left, height from useViCursor */
+  style: CSSProperties;
+  /** Whether to show the cursor (visible in normal/command mode) */
+  visible: boolean;
+}
+
+/**
+ * Block cursor overlay for vi normal mode.
+ *
+ * This component renders on top of the textarea to show a vim-style block
+ * cursor when in normal mode. The native textarea caret is hidden via CSS
+ * (caret-color: transparent) when this cursor is shown.
+ *
+ * Features:
+ * - Block cursor appearance (~0.6em wide)
+ * - Semi-transparent background
+ * - Blink animation
+ * - pointer-events: none so it doesn't interfere with textarea interaction
+ *
+ * @example
+ * ```tsx
+ * const { cursorStyle, showOverlay } = useViCursor({
+ *   textareaRef,
+ *   cursorPosition,
+ *   mode: viMode,
+ *   enabled: viModeEnabled,
+ * });
+ *
+ * return (
+ *   <div className="pair-writing-editor">
+ *     <textarea ref={textareaRef} />
+ *     <ViCursor style={cursorStyle} visible={showOverlay} />
+ *   </div>
+ * );
+ * ```
+ */
+export function ViCursor({ style, visible }: ViCursorProps): React.ReactNode {
+  if (!visible) {
+    return null;
+  }
+
+  return (
+    <div
+      className="vi-cursor"
+      style={style}
+      data-testid="vi-cursor"
+      aria-hidden="true"
+    />
+  );
+}
diff --git a/frontend/src/components/pair-writing/ViModeIndicator.tsx b/frontend/src/components/pair-writing/ViModeIndicator.tsx
new file mode 100644
index 00000000..e58efb43
--- /dev/null
+++ b/frontend/src/components/pair-writing/ViModeIndicator.tsx
@@ -0,0 +1,58 @@
+/**
+ * ViModeIndicator Component
+ *
+ * Displays the current vi mode in vim-style format at the bottom of the editor.
+ * Shows "-- NORMAL --", "-- INSERT --", or "-- COMMAND --" based on mode.
+ *
+ * @see .lore/specs/vi-mode-pair-writing.md REQ-5
+ */
+
+import type { ViMode } from "../../hooks/useViMode";
+import "./vi-mode.css";
+
+export interface ViModeIndicatorProps {
+  /** Current vi mode */
+  mode: ViMode;
+  /** Whether vi mode is enabled (hidden when false) */
+  visible: boolean;
+  /** Command buffer to display in command mode (e.g., ":w") */
+  commandBuffer?: string;
+}
+
+/** Map mode to display text */
+const MODE_LABELS: Record<ViMode, string> = {
+  normal: "-- NORMAL --",
+  insert: "-- INSERT --",
+  command: "-- COMMAND --",
+};
+
+/**
+ * Mode indicator component showing current vi mode.
+ * Positioned at bottom-left of editor, styled like classic vim.
+ */
+export function ViModeIndicator({
+  mode,
+  visible,
+  commandBuffer,
+}: ViModeIndicatorProps): React.ReactNode {
+  if (!visible) {
+    return null;
+  }
+
+  const label = MODE_LABELS[mode];
+  const displayText =
+    mode === "command" && commandBuffer
+      ? `${label} ${commandBuffer}`
+      : label;
+
+  return (
+    <div
+      className="vi-mode-indicator"
+      data-mode={mode}
+      aria-live="polite"
+      aria-label={`Vi mode: ${mode}`}
+    >
+      {displayText}
+    </div>
+  );
+}
diff --git a/frontend/src/components/pair-writing/__tests__/ViCommandLine.test.tsx b/frontend/src/components/pair-writing/__tests__/ViCommandLine.test.tsx
new file mode 100644
index 00000000..7deb6be9
--- /dev/null
+++ b/frontend/src/components/pair-writing/__tests__/ViCommandLine.test.tsx
@@ -0,0 +1,274 @@
+/**
+ * Tests for ViCommandLine component
+ *
+ * ViCommandLine is a pure display component that shows the command buffer.
+ * All keyboard input is handled by useViMode through the textarea.
+ *
+ * Tests cover:
+ * - Visibility toggling
+ * - Rendering with colon prefix
+ * - Displaying command text
+ * - Cursor indicator
+ * - Accessibility attributes
+ *
+ * @see .lore/specs/vi-mode-pair-writing.md (REQ-14, REQ-19)
+ */
+
+import { describe, it, expect, afterEach } from "bun:test";
+import { render, screen, cleanup } from "@testing-library/react";
+import { ViCommandLine } from "../ViCommandLine";
+
+afterEach(() => {
+  cleanup();
+});
+
+// =============================================================================
+// Visibility Tests
+// =============================================================================
+
+describe("ViCommandLine - visibility", () => {
+  it("renders when visible is true", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    expect(screen.getByTestId("vi-command-line")).toBeDefined();
+  });
+
+  it("does not render when visible is false", () => {
+    render(
+      <ViCommandLine
+        visible={false}
+        value=""
+      />
+    );
+
+    expect(screen.queryByTestId("vi-command-line")).toBeNull();
+  });
+
+  it("returns null (not hidden element) when not visible", () => {
+    const { container } = render(
+      <ViCommandLine
+        visible={false}
+        value=""
+      />
+    );
+
+    expect(container.firstChild).toBeNull();
+  });
+});
+
+// =============================================================================
+// Colon Prefix Tests
+// =============================================================================
+
+describe("ViCommandLine - colon prefix", () => {
+  it("shows colon prefix", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    expect(screen.getByText(":")).toBeDefined();
+  });
+
+  it("colon prefix has aria-hidden for accessibility", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const prefix = screen.getByText(":");
+    expect(prefix.getAttribute("aria-hidden")).toBe("true");
+  });
+});
+
+// =============================================================================
+// Command Text Display Tests
+// =============================================================================
+
+describe("ViCommandLine - command text display", () => {
+  it("displays the command value", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value="wq"
+      />
+    );
+
+    expect(screen.getByText("wq")).toBeDefined();
+  });
+
+  it("displays empty value correctly (shows cursor only)", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    // The container should exist even with empty value
+    expect(screen.getByTestId("vi-command-line")).toBeDefined();
+    // The text span should be empty
+    const container = screen.getByTestId("vi-command-line");
+    const textSpan = container.querySelector(".vi-command-line__text");
+    expect(textSpan?.textContent).toBe("");
+  });
+
+  it("updates display when value changes", () => {
+    const { rerender } = render(
+      <ViCommandLine
+        visible={true}
+        value="w"
+      />
+    );
+
+    expect(screen.getByText("w")).toBeDefined();
+
+    rerender(
+      <ViCommandLine
+        visible={true}
+        value="wq"
+      />
+    );
+
+    expect(screen.getByText("wq")).toBeDefined();
+  });
+});
+
+// =============================================================================
+// Cursor Indicator Tests
+// =============================================================================
+
+describe("ViCommandLine - cursor indicator", () => {
+  it("shows cursor element after text", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value="w"
+      />
+    );
+
+    const container = screen.getByTestId("vi-command-line");
+    const cursor = container.querySelector(".vi-command-line__cursor");
+    expect(cursor).toBeDefined();
+    expect(cursor).not.toBeNull();
+  });
+
+  it("cursor has aria-hidden for accessibility", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const container = screen.getByTestId("vi-command-line");
+    const cursor = container.querySelector(".vi-command-line__cursor");
+    expect(cursor?.getAttribute("aria-hidden")).toBe("true");
+  });
+});
+
+// =============================================================================
+// Accessibility Tests
+// =============================================================================
+
+describe("ViCommandLine - accessibility", () => {
+  it("has status role for live region", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const container = screen.getByTestId("vi-command-line");
+    expect(container.getAttribute("role")).toBe("status");
+  });
+
+  it("has aria-label on container", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const container = screen.getByTestId("vi-command-line");
+    expect(container.getAttribute("aria-label")).toBe("Vi command line");
+  });
+
+  it("has aria-live for screen reader announcements", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const container = screen.getByTestId("vi-command-line");
+    expect(container.getAttribute("aria-live")).toBe("polite");
+  });
+});
+
+// =============================================================================
+// CSS Class Tests
+// =============================================================================
+
+describe("ViCommandLine - CSS classes", () => {
+  it("has vi-command-line class on container", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const container = screen.getByTestId("vi-command-line");
+    expect(container.classList.contains("vi-command-line")).toBe(true);
+  });
+
+  it("has vi-command-line__prefix class on colon", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const prefix = screen.getByText(":");
+    expect(prefix.classList.contains("vi-command-line__prefix")).toBe(true);
+  });
+
+  it("has vi-command-line__text class on text display", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value="w"
+      />
+    );
+
+    const text = screen.getByText("w");
+    expect(text.classList.contains("vi-command-line__text")).toBe(true);
+  });
+
+  it("has vi-command-line__cursor class on cursor", () => {
+    render(
+      <ViCommandLine
+        visible={true}
+        value=""
+      />
+    );
+
+    const container = screen.getByTestId("vi-command-line");
+    const cursor = container.querySelector(".vi-command-line__cursor");
+    expect(cursor?.classList.contains("vi-command-line__cursor")).toBe(true);
+  });
+});
diff --git a/frontend/src/components/pair-writing/__tests__/ViModeIndicator.test.tsx b/frontend/src/components/pair-writing/__tests__/ViModeIndicator.test.tsx
new file mode 100644
index 00000000..fd0fafda
--- /dev/null
+++ b/frontend/src/components/pair-writing/__tests__/ViModeIndicator.test.tsx
@@ -0,0 +1,189 @@
+/**
+ * Tests for ViModeIndicator component
+ *
+ * Tests cover:
+ * - Rendering correct mode labels
+ * - Visibility toggling
+ * - Command buffer display in command mode
+ * - Accessibility attributes
+ *
+ * @see .lore/specs/vi-mode-pair-writing.md REQ-5
+ */
+
+import { describe, it, expect, afterEach } from "bun:test";
+import { render, screen, cleanup } from "@testing-library/react";
+import { ViModeIndicator } from "../ViModeIndicator";
+import type { ViMode } from "../../../hooks/useViMode";
+
+afterEach(() => {
+  cleanup();
+});
+
+// =============================================================================
+// Mode Label Tests
+// =============================================================================
+
+describe("ViModeIndicator - mode labels", () => {
+  it("renders '-- NORMAL --' when mode is normal", () => {
+    render(<ViModeIndicator mode="normal" visible={true} />);
+
+    expect(screen.getByText("-- NORMAL --")).toBeDefined();
+  });
+
+  it("renders '-- INSERT --' when mode is insert", () => {
+    render(<ViModeIndicator mode="insert" visible={true} />);
+
+    expect(screen.getByText("-- INSERT --")).toBeDefined();
+  });
+
+  it("renders '-- COMMAND --' when mode is command", () => {
+    render(<ViModeIndicator mode="command" visible={true} />);
+
+    expect(screen.getByText("-- COMMAND --")).toBeDefined();
+  });
+
+  it("sets data-mode attribute for CSS styling", () => {
+    const modes: ViMode[] = ["normal", "insert", "command"];
+
+    for (const mode of modes) {
+      cleanup();
+      render(<ViModeIndicator mode={mode} visible={true} />);
+
+      const indicator = document.querySelector(".vi-mode-indicator");
+      expect(indicator?.getAttribute("data-mode")).toBe(mode);
+    }
+  });
+});
+
+// =============================================================================
+// Visibility Tests
+// =============================================================================
+
+describe("ViModeIndicator - visibility", () => {
+  it("renders when visible is true", () => {
+    render(<ViModeIndicator mode="normal" visible={true} />);
+
+    const indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator).not.toBeNull();
+  });
+
+  it("does not render when visible is false", () => {
+    render(<ViModeIndicator mode="normal" visible={false} />);
+
+    const indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator).toBeNull();
+  });
+
+  it("returns null (not hidden element) when not visible", () => {
+    const { container } = render(
+      <ViModeIndicator mode="normal" visible={false} />
+    );
+
+    // Container should be empty when not visible
+    expect(container.firstChild).toBeNull();
+  });
+});
+
+// =============================================================================
+// Command Buffer Tests
+// =============================================================================
+
+describe("ViModeIndicator - command buffer", () => {
+  it("shows commandBuffer in command mode", () => {
+    render(
+      <ViModeIndicator mode="command" visible={true} commandBuffer=":w" />
+    );
+
+    expect(screen.getByText("-- COMMAND -- :w")).toBeDefined();
+  });
+
+  it("shows full command buffer with longer commands", () => {
+    render(
+      <ViModeIndicator mode="command" visible={true} commandBuffer=":wq" />
+    );
+
+    expect(screen.getByText("-- COMMAND -- :wq")).toBeDefined();
+  });
+
+  it("ignores commandBuffer in normal mode", () => {
+    render(
+      <ViModeIndicator mode="normal" visible={true} commandBuffer=":w" />
+    );
+
+    expect(screen.getByText("-- NORMAL --")).toBeDefined();
+    expect(screen.queryByText(":w")).toBeNull();
+  });
+
+  it("ignores commandBuffer in insert mode", () => {
+    render(
+      <ViModeIndicator mode="insert" visible={true} commandBuffer=":w" />
+    );
+
+    expect(screen.getByText("-- INSERT --")).toBeDefined();
+    expect(screen.queryByText(":w")).toBeNull();
+  });
+
+  it("shows only mode label when commandBuffer is empty string", () => {
+    render(<ViModeIndicator mode="command" visible={true} commandBuffer="" />);
+
+    expect(screen.getByText("-- COMMAND --")).toBeDefined();
+  });
+
+  it("shows only mode label when commandBuffer is undefined", () => {
+    render(<ViModeIndicator mode="command" visible={true} />);
+
+    expect(screen.getByText("-- COMMAND --")).toBeDefined();
+  });
+});
+
+// =============================================================================
+// Accessibility Tests
+// =============================================================================
+
+describe("ViModeIndicator - accessibility", () => {
+  it("has aria-live attribute for screen readers", () => {
+    render(<ViModeIndicator mode="normal" visible={true} />);
+
+    const indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator?.getAttribute("aria-live")).toBe("polite");
+  });
+
+  it("has descriptive aria-label", () => {
+    render(<ViModeIndicator mode="normal" visible={true} />);
+
+    const indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator?.getAttribute("aria-label")).toBe("Vi mode: normal");
+  });
+
+  it("updates aria-label based on mode", () => {
+    const { rerender } = render(
+      <ViModeIndicator mode="normal" visible={true} />
+    );
+
+    let indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator?.getAttribute("aria-label")).toBe("Vi mode: normal");
+
+    rerender(<ViModeIndicator mode="insert" visible={true} />);
+
+    indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator?.getAttribute("aria-label")).toBe("Vi mode: insert");
+
+    rerender(<ViModeIndicator mode="command" visible={true} />);
+
+    indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator?.getAttribute("aria-label")).toBe("Vi mode: command");
+  });
+});
+
+// =============================================================================
+// CSS Class Tests
+// =============================================================================
+
+describe("ViModeIndicator - CSS classes", () => {
+  it("has vi-mode-indicator class", () => {
+    render(<ViModeIndicator mode="normal" visible={true} />);
+
+    const indicator = document.querySelector(".vi-mode-indicator");
+    expect(indicator).not.toBeNull();
+  });
+});
diff --git a/frontend/src/components/pair-writing/__tests__/vi-mode-integration.test.tsx b/frontend/src/components/pair-writing/__tests__/vi-mode-integration.test.tsx
new file mode 100644
index 00000000..0801290e
--- /dev/null
+++ b/frontend/src/components/pair-writing/__tests__/vi-mode-integration.test.tsx
@@ -0,0 +1,604 @@
+/**
+ * Integration tests for vi mode in PairWritingEditor.
+ *
+ * Tests the full vi mode integration including:
+ * - Gating on viModeEnabled prop and keyboard detection
+ * - Mode indicator visibility
+ * - Block cursor overlay rendering
+ * - Command line for ex commands
+ * - Interaction with Quick Actions (processing state blocks vi mode)
+ *
+ * These tests verify the wiring between:
+ * - PairWritingEditor component
+ * - useViMode hook
+ * - useViCursor hook
+ * - useHasKeyboard hook
+ * - Vi UI components (ViCursor, ViModeIndicator, ViCommandLine)
+ *
+ * @see .lore/specs/vi-mode-pair-writing.md
+ * @see .lore/work/vi-mode-pair-writing.md (Chunk 14)
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+  mock,
+} from "bun:test";
+import { render, screen, fireEvent, cleanup, act } from "@testing-library/react";
+import type { ServerMessage, ClientMessage } from "@memory-loop/shared";
+import { PairWritingEditor } from "../PairWritingEditor";
+import type { EditorContextMenuProps } from "../../shared/EditorContextMenu";
+
+// =============================================================================
+// Mock keyboard detection
+// =============================================================================
+
+// We need to mock the keyboard detection to control whether vi mode activates.
+// The useHasKeyboard hook checks matchMedia and maxTouchPoints.
+
+// Store original values to restore after tests
+const originalMatchMedia = window.matchMedia;
+const originalMaxTouchPoints = navigator.maxTouchPoints;
+
+function setupKeyboardMock(hasKeyboard: boolean) {
+  // Mock matchMedia to return hasKeyboard for "(pointer: fine)"
+  window.matchMedia = (query: string): MediaQueryList => {
+    if (query === "(pointer: fine)") {
+      return {
+        matches: hasKeyboard,
+        media: query,
+        onchange: null,
+        addListener: () => {},
+        removeListener: () => {},
+        addEventListener: () => {},
+        removeEventListener: () => {},
+        dispatchEvent: () => true,
+      };
+    }
+    return originalMatchMedia(query);
+  };
+
+  // Mock maxTouchPoints
+  Object.defineProperty(navigator, "maxTouchPoints", {
+    value: hasKeyboard ? 0 : 5, // 0 = no touch, 5 = touch device
+    configurable: true,
+  });
+}
+
+function restoreKeyboardMock() {
+  window.matchMedia = originalMatchMedia;
+  Object.defineProperty(navigator, "maxTouchPoints", {
+    value: originalMaxTouchPoints,
+    configurable: true,
+  });
+}
+
+// =============================================================================
+// Mock Components
+// =============================================================================
+
+/**
+ * Mock context menu component - required because PairWritingEditor expects it.
+ */
+function MockContextMenu({
+  isOpen,
+  onDismiss,
+}: EditorContextMenuProps): React.ReactNode {
+  return isOpen ? (
+    <div data-testid="context-menu">
+      <button onClick={onDismiss}>Dismiss</button>
+    </div>
+  ) : null;
+}
+
+// =============================================================================
+// Test Fixtures
+// =============================================================================
+
+function createDefaultProps() {
+  return {
+    initialContent: "Hello world\nSecond line\nThird line",
+    filePath: "notes/test.md",
+    sendMessage: mock<(message: ClientMessage) => void>(() => {}),
+    lastMessage: null as ServerMessage | null,
+    onContentChange: mock<(content: string) => void>(() => {}),
+    ContextMenuComponent: MockContextMenu,
+    viModeEnabled: true,
+    onSave: mock<() => void>(() => {}),
+    onExit: mock<() => void>(() => {}),
+    onQuitWithUnsaved: mock<() => void>(() => {}),
+  };
+}
+
+function getTextarea(): HTMLTextAreaElement {
+  return screen.getByRole("textbox", { name: "Document editor" });
+}
+
+// =============================================================================
+// Setup/Teardown
+// =============================================================================
+
+beforeEach(() => {
+  setupKeyboardMock(true); // Default: keyboard available
+});
+
+afterEach(() => {
+  cleanup();
+  restoreKeyboardMock();
+});
+
+// =============================================================================
+// Vi Mode Gating Tests
+// =============================================================================
+
+describe("vi mode gating", () => {
+  it("shows mode indicator when viModeEnabled is true and keyboard detected", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    // Mode indicator should be visible
+    const indicator = screen.getByText("-- NORMAL --");
+    expect(indicator).toBeDefined();
+  });
+
+  it("hides mode indicator when viModeEnabled is false", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={false} />);
+
+    // Mode indicator should not be visible
+    expect(screen.queryByText("-- NORMAL --")).toBeNull();
+  });
+
+  it("hides mode indicator when no keyboard detected", () => {
+    setupKeyboardMock(false); // Touch-only device
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    // Mode indicator should not be visible (vi mode disabled)
+    expect(screen.queryByText("-- NORMAL --")).toBeNull();
+  });
+
+  it("shows block cursor overlay in normal mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    // Block cursor should be visible in normal mode
+    const cursor = screen.getByTestId("vi-cursor");
+    expect(cursor).toBeDefined();
+  });
+
+  it("hides block cursor when vi mode disabled", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={false} />);
+
+    // Block cursor should not exist
+    expect(screen.queryByTestId("vi-cursor")).toBeNull();
+  });
+});
+
+// =============================================================================
+// Mode Transitions via Keys
+// =============================================================================
+
+describe("mode transitions", () => {
+  it("transitions to insert mode when 'i' is pressed", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    // Start in normal mode
+    expect(screen.getByText("-- NORMAL --")).toBeDefined();
+
+    // Press 'i' to enter insert mode
+    const textarea = getTextarea();
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "i" });
+    });
+
+    // Should now show insert mode
+    expect(screen.getByText("-- INSERT --")).toBeDefined();
+  });
+
+  it("returns to normal mode when Escape is pressed in insert mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Enter insert mode
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "i" });
+    });
+    expect(screen.getByText("-- INSERT --")).toBeDefined();
+
+    // Press Escape to return to normal mode
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "Escape" });
+    });
+    expect(screen.getByText("-- NORMAL --")).toBeDefined();
+  });
+
+  it("hides block cursor in insert mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    // Cursor visible in normal mode
+    expect(screen.getByTestId("vi-cursor")).toBeDefined();
+
+    // Enter insert mode
+    const textarea = getTextarea();
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "i" });
+    });
+
+    // Cursor should be hidden in insert mode
+    expect(screen.queryByTestId("vi-cursor")).toBeNull();
+  });
+
+  it("shows block cursor again after returning to normal mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Enter and exit insert mode
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "i" });
+    });
+    expect(screen.queryByTestId("vi-cursor")).toBeNull();
+
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "Escape" });
+    });
+    expect(screen.getByTestId("vi-cursor")).toBeDefined();
+  });
+});
+
+// =============================================================================
+// Command Mode Tests
+// =============================================================================
+
+describe("command mode", () => {
+  it("enters command mode when ':' is pressed in normal mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+    act(() => {
+      fireEvent.keyDown(textarea, { key: ":" });
+    });
+
+    // Should show command mode indicator
+    expect(screen.getByText(/-- COMMAND --/)).toBeDefined();
+  });
+
+  it("shows command line input in command mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+    act(() => {
+      fireEvent.keyDown(textarea, { key: ":" });
+    });
+
+    // Command line should be visible
+    const commandLine = screen.getByTestId("vi-command-line");
+    expect(commandLine).toBeDefined();
+  });
+
+  it("hides command line when not in command mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    // In normal mode, command line should not be visible
+    expect(screen.queryByTestId("vi-command-line")).toBeNull();
+  });
+
+  it("returns to normal mode when Escape pressed in command mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Enter command mode
+    act(() => {
+      fireEvent.keyDown(textarea, { key: ":" });
+    });
+    expect(screen.getByTestId("vi-command-line")).toBeDefined();
+
+    // Press Escape
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "Escape" });
+    });
+
+    // Should be back in normal mode, command line hidden
+    expect(screen.queryByTestId("vi-command-line")).toBeNull();
+    expect(screen.getByText("-- NORMAL --")).toBeDefined();
+  });
+});
+
+// =============================================================================
+// Ex Command Callbacks
+// =============================================================================
+
+describe("ex command callbacks", () => {
+  it("calls onSave when :w command is executed", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Enter command mode and type :w<Enter>
+    // Each keypress needs separate act() because state must update between
+    void act(() => fireEvent.keyDown(textarea, { key: ":" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "w" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "Enter" }));
+
+    expect(props.onSave).toHaveBeenCalled();
+  });
+
+  it("calls onSave and onExit when :wq command is executed", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Enter command mode and type :wq<Enter>
+    void act(() => fireEvent.keyDown(textarea, { key: ":" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "w" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "q" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "Enter" }));
+
+    expect(props.onSave).toHaveBeenCalled();
+    expect(props.onExit).toHaveBeenCalled();
+  });
+
+  it("calls onQuitWithUnsaved when :q command is executed", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Enter command mode and type :q<Enter>
+    void act(() => fireEvent.keyDown(textarea, { key: ":" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "q" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "Enter" }));
+
+    expect(props.onQuitWithUnsaved).toHaveBeenCalled();
+  });
+
+  it("calls onExit directly when :q! command is executed", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Enter command mode and type :q!<Enter>
+    void act(() => fireEvent.keyDown(textarea, { key: ":" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "q" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "!" }));
+    void act(() => fireEvent.keyDown(textarea, { key: "Enter" }));
+
+    expect(props.onExit).toHaveBeenCalled();
+  });
+});
+
+// =============================================================================
+// Content Change Propagation
+// =============================================================================
+
+describe("content change propagation", () => {
+  it("calls onContentChange when vi mode modifies content via 'o' command", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Position cursor on first line
+    act(() => {
+      textarea.setSelectionRange(5, 5);
+      fireEvent.select(textarea);
+    });
+
+    // Press 'o' to open new line below
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "o" });
+    });
+
+    // Content should have been updated with new line
+    expect(props.onContentChange).toHaveBeenCalled();
+  });
+
+  it("calls onContentChange when vi mode deletes content via 'x' command", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Position cursor at start
+    act(() => {
+      textarea.setSelectionRange(0, 0);
+      fireEvent.select(textarea);
+    });
+
+    // Press 'x' to delete character
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "x" });
+    });
+
+    // Content should have been updated
+    expect(props.onContentChange).toHaveBeenCalled();
+  });
+});
+
+// =============================================================================
+// CSS Class Application
+// =============================================================================
+
+describe("CSS class application", () => {
+  it("adds vi-normal class to textarea in normal mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+    expect(textarea.classList.contains("pair-writing-editor__textarea--vi-normal")).toBe(
+      true
+    );
+  });
+
+  it("removes vi-normal class in insert mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "i" });
+    });
+
+    expect(textarea.classList.contains("pair-writing-editor__textarea--vi-normal")).toBe(
+      false
+    );
+  });
+
+  it("adds vi-command class in command mode", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+    act(() => {
+      fireEvent.keyDown(textarea, { key: ":" });
+    });
+
+    expect(textarea.classList.contains("pair-writing-editor__textarea--vi-command")).toBe(
+      true
+    );
+  });
+
+  it("does not add vi classes when vi mode disabled", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={false} />);
+
+    const textarea = getTextarea();
+    expect(textarea.classList.contains("pair-writing-editor__textarea--vi-normal")).toBe(
+      false
+    );
+    expect(textarea.classList.contains("pair-writing-editor__textarea--vi-command")).toBe(
+      false
+    );
+  });
+});
+
+// =============================================================================
+// Movement Commands Affect Cursor Position
+// =============================================================================
+
+describe("movement commands update cursor", () => {
+  it("updates cursor position after movement command 'l'", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Start at position 0
+    act(() => {
+      textarea.setSelectionRange(0, 0);
+      fireEvent.select(textarea);
+    });
+
+    // Move right with 'l'
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "l" });
+    });
+
+    // Cursor should have moved
+    expect(textarea.selectionStart).toBe(1);
+  });
+
+  it("updates cursor position after movement command 'h'", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Start at position 5
+    act(() => {
+      textarea.setSelectionRange(5, 5);
+      fireEvent.select(textarea);
+    });
+
+    // Move left with 'h'
+    act(() => {
+      fireEvent.keyDown(textarea, { key: "h" });
+    });
+
+    // Cursor should have moved
+    expect(textarea.selectionStart).toBe(4);
+  });
+});
+
+// =============================================================================
+// Normal Input When Vi Mode Disabled
+// =============================================================================
+
+describe("normal input when vi mode disabled", () => {
+  it("allows normal typing when viModeEnabled is false", () => {
+    setupKeyboardMock(true);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={false} />);
+
+    const textarea = getTextarea();
+
+    // Type characters - they should be inserted normally
+    act(() => {
+      fireEvent.change(textarea, { target: { value: "Hello world\nSecond line\nThird linex" } });
+    });
+
+    // Content should be updated
+    expect(textarea.value).toBe("Hello world\nSecond line\nThird linex");
+    expect(props.onContentChange).toHaveBeenCalledWith(
+      "Hello world\nSecond line\nThird linex"
+    );
+  });
+
+  it("allows normal typing when no keyboard detected", () => {
+    setupKeyboardMock(false);
+    const props = createDefaultProps();
+    render(<PairWritingEditor {...props} viModeEnabled={true} />);
+
+    const textarea = getTextarea();
+
+    // Type characters - they should be inserted normally even with viModeEnabled
+    act(() => {
+      fireEvent.change(textarea, { target: { value: "Modified content" } });
+    });
+
+    expect(textarea.value).toBe("Modified content");
+    expect(props.onContentChange).toHaveBeenCalledWith("Modified content");
+  });
+});
diff --git a/frontend/src/components/pair-writing/index.ts b/frontend/src/components/pair-writing/index.ts
index fdd72c59..dca87df6 100644
--- a/frontend/src/components/pair-writing/index.ts
+++ b/frontend/src/components/pair-writing/index.ts
@@ -5,3 +5,7 @@
 export { PairWritingMode, type PairWritingModeProps } from "./PairWritingMode";
 export { PairWritingEditor, type PairWritingEditorProps } from "./PairWritingEditor";
 export { PairWritingToolbar, type PairWritingToolbarProps } from "./PairWritingToolbar";
+export { ViModeIndicator, type ViModeIndicatorProps } from "./ViModeIndicator";
+export { ViCursor, type ViCursorProps } from "./ViCursor";
+export { ViCommandLine, type ViCommandLineProps } from "./ViCommandLine";
+export type { ViMode } from "../../hooks/useViMode";
diff --git a/frontend/src/components/pair-writing/vi-mode.css b/frontend/src/components/pair-writing/vi-mode.css
new file mode 100644
index 00000000..bfa70159
--- /dev/null
+++ b/frontend/src/components/pair-writing/vi-mode.css
@@ -0,0 +1,119 @@
+/**
+ * Vi Mode Styles
+ *
+ * Styles for vi mode UI elements: block cursor overlay, mode indicator,
+ * and command line.
+ *
+ * @see .lore/plans/vi-mode-pair-writing.md (TD-10)
+ */
+
+/* Hide native caret in normal mode */
+.pair-writing-editor__textarea--vi-normal {
+  caret-color: transparent;
+}
+
+/* Hide native caret in command mode (cursor stays visible) */
+.pair-writing-editor__textarea--vi-command {
+  caret-color: transparent;
+}
+
+/* Block cursor overlay */
+.vi-cursor {
+  position: absolute;
+  pointer-events: none;
+  background-color: var(--color-accent-quartary, #d4a574);
+  opacity: 0.85;
+  width: 0.6em;
+  animation: vi-cursor-blink 1s step-end infinite;
+  z-index: 5;
+}
+
+/* Blink animation for block cursor */
+@keyframes vi-cursor-blink {
+  0%,
+  100% {
+    opacity: 0.85;
+  }
+  50% {
+    opacity: 0.3;
+  }
+}
+
+/* Disable blink when textarea is not focused */
+.pair-writing-editor:not(:focus-within) .vi-cursor {
+  animation: none;
+  opacity: 0.5;
+}
+
+/* ============================================
+   Mode Indicator
+
+   Displays current mode at bottom-left of editor.
+   Vim-style appearance: monospace, bold, subtle.
+   ============================================ */
+
+.vi-mode-indicator {
+  position: absolute;
+  bottom: 8px;
+  left: 8px;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-bold);
+  color: var(--color-text-secondary);
+  pointer-events: none;
+  user-select: none;
+  z-index: 5;
+}
+
+/* Mode-specific styling for visual distinction */
+.vi-mode-indicator[data-mode="insert"] {
+  color: var(--color-success);
+}
+
+.vi-mode-indicator[data-mode="command"] {
+  color: var(--color-accent-quartary);
+}
+
+/* ============================================
+   Command Line Input
+
+   Vim-style command input at bottom of editor.
+   Shows ":" prefix followed by input field.
+   ============================================ */
+
+.vi-command-line {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  display: flex;
+  align-items: center;
+  padding: 4px 8px;
+  background-color: var(--color-surface);
+  border-top: 1px solid var(--color-border);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  z-index: 10;
+}
+
+.vi-command-line__prefix {
+  color: var(--color-text);
+  font-weight: var(--font-weight-bold);
+  margin-right: 2px;
+  user-select: none;
+}
+
+.vi-command-line__text {
+  color: var(--color-text);
+  white-space: pre;
+}
+
+.vi-command-line__cursor {
+  display: inline-block;
+  width: 0.6em;
+  height: 1.1em;
+  background-color: var(--color-text);
+  opacity: 0.7;
+  animation: vi-cursor-blink 1s step-end infinite;
+  vertical-align: text-bottom;
+}
diff --git a/frontend/src/components/vault/ConfigEditorDialog.tsx b/frontend/src/components/vault/ConfigEditorDialog.tsx
index 3d2e2f67..5c870281 100644
--- a/frontend/src/components/vault/ConfigEditorDialog.tsx
+++ b/frontend/src/components/vault/ConfigEditorDialog.tsx
@@ -55,6 +55,7 @@ export interface EditableVaultConfig {
   badges?: Badge[]; // max 5
   order?: number; // display order on vault selection screen
   cardsEnabled?: boolean; // whether spaced repetition card discovery is enabled
+  viMode?: boolean; // whether vi-style editing is enabled in Pair Writing
 }
 
 export interface ConfigEditorDialogProps {
@@ -87,6 +88,7 @@ function hasConfigChanged(
   if (initial.recentDiscussions !== current.recentDiscussions) return true;
   if (initial.order !== current.order) return true;
   if (initial.cardsEnabled !== current.cardsEnabled) return true;
+  if (initial.viMode !== current.viMode) return true;
 
   // Compare badges array
   const initialBadges = initial.badges ?? [];
@@ -342,6 +344,7 @@ export function ConfigEditorDialog({
   const recentCapturesId = useId();
   const recentDiscussionsId = useId();
   const cardsEnabledId = useId();
+  const viModeId = useId();
 
   // Form state - initialized from initialConfig
   const [formState, setFormState] = useState<EditableVaultConfig>(initialConfig);
@@ -777,6 +780,35 @@ export function ConfigEditorDialog({
                 </p>
               </div>
             </section>
+
+            {/* Editing Settings Section */}
+            <section className="config-editor__section">
+              <h3 className="config-editor__section-title">Editing</h3>
+              <p className="config-editor__section-description">
+                Configure the Pair Writing editing experience.
+              </p>
+
+              <div className="config-editor__checkbox-field">
+                <label className="config-editor__checkbox-label">
+                  <input
+                    id={viModeId}
+                    type="checkbox"
+                    className="config-editor__checkbox"
+                    checked={formState.viMode ?? false}
+                    onChange={(e) =>
+                      setFormState((prev) => ({
+                        ...prev,
+                        viMode: e.target.checked,
+                      }))
+                    }
+                  />
+                  <span>Enable Vi Mode</span>
+                </label>
+                <p className="config-editor__field-hint">
+                  Use vi-style modal editing in Pair Writing. Requires a physical keyboard.
+                </p>
+              </div>
+            </section>
           </div>
 
           {/* Footer with actions */}
diff --git a/frontend/src/components/vault/VaultSelect.tsx b/frontend/src/components/vault/VaultSelect.tsx
index 0dfe53e6..d9515dfb 100644
--- a/frontend/src/components/vault/VaultSelect.tsx
+++ b/frontend/src/components/vault/VaultSelect.tsx
@@ -376,6 +376,7 @@ export function VaultSelect({ onReady }: VaultSelectProps): React.ReactNode {
                 badges: config.badges ?? v.badges,
                 order: config.order ?? v.order,
                 cardsEnabled: config.cardsEnabled ?? v.cardsEnabled,
+                viMode: config.viMode ?? v.viMode,
               }
             : v
         )
@@ -722,6 +723,7 @@ export function VaultSelect({ onReady }: VaultSelectProps): React.ReactNode {
             badges: configEditorVault.badges,
             order: configEditorVault.order === Infinity ? undefined : configEditorVault.order,
             cardsEnabled: configEditorVault.cardsEnabled,
+            viMode: configEditorVault.viMode,
           }}
           onSave={handleConfigSave}
           onCancel={handleConfigCancel}
diff --git a/frontend/src/components/vault/__tests__/VaultSelect.test.tsx b/frontend/src/components/vault/__tests__/VaultSelect.test.tsx
index f62e0f1c..6b216af5 100644
--- a/frontend/src/components/vault/__tests__/VaultSelect.test.tsx
+++ b/frontend/src/components/vault/__tests__/VaultSelect.test.tsx
@@ -69,6 +69,7 @@ const testVaults: VaultInfo[] = [
     badges: [{ text: "Primary", color: "blue" }],
     order: 1,
     cardsEnabled: true,
+      viMode: false,
   },
   {
     id: "vault-2",
@@ -87,6 +88,7 @@ const testVaults: VaultInfo[] = [
     badges: [],
     order: 2,
     cardsEnabled: true,
+      viMode: false,
   },
 ];
 
@@ -783,6 +785,7 @@ describe("VaultSelect", () => {
         badges: [],
         order: 999,
         cardsEnabled: true,
+      viMode: false,
       };
 
       wsInstances[0].simulateMessage({
diff --git a/frontend/src/contexts/__tests__/SessionContext.test.tsx b/frontend/src/contexts/__tests__/SessionContext.test.tsx
index 3892c888..39892de1 100644
--- a/frontend/src/contexts/__tests__/SessionContext.test.tsx
+++ b/frontend/src/contexts/__tests__/SessionContext.test.tsx
@@ -50,6 +50,7 @@ const testVault: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 const testVault2: VaultInfo = {
@@ -68,6 +69,7 @@ const testVault2: VaultInfo = {
   badges: [],
   order: 999999,
     cardsEnabled: true,
+      viMode: false,
 };
 
 describe("SessionContext", () => {
diff --git a/frontend/src/contexts/session/__tests__/reducer-update-config.test.ts b/frontend/src/contexts/session/__tests__/reducer-update-config.test.ts
index 1bf2aec1..249df61a 100644
--- a/frontend/src/contexts/session/__tests__/reducer-update-config.test.ts
+++ b/frontend/src/contexts/session/__tests__/reducer-update-config.test.ts
@@ -29,6 +29,7 @@ const mockVault: VaultInfo = {
   badges: [],
   order: 1,
   cardsEnabled: false, // Start with false
+  viMode: false,
 };
 
 describe("UPDATE_VAULT_CONFIG action", () => {
diff --git a/frontend/src/contexts/session/reducer.ts b/frontend/src/contexts/session/reducer.ts
index 8e609c50..7ede144b 100644
--- a/frontend/src/contexts/session/reducer.ts
+++ b/frontend/src/contexts/session/reducer.ts
@@ -728,6 +728,7 @@ export function sessionReducer(
           badges: action.config.badges ?? state.vault.badges,
           order: action.config.order ?? state.vault.order,
           cardsEnabled: action.config.cardsEnabled ?? state.vault.cardsEnabled,
+          viMode: action.config.viMode ?? state.vault.viMode,
         },
       };
 
diff --git a/frontend/src/hooks/__tests__/useViCursor.test.ts b/frontend/src/hooks/__tests__/useViCursor.test.ts
new file mode 100644
index 00000000..f4a953bf
--- /dev/null
+++ b/frontend/src/hooks/__tests__/useViCursor.test.ts
@@ -0,0 +1,346 @@
+/**
+ * useViCursor Hook Tests
+ *
+ * Tests the vi mode block cursor position calculation and visibility.
+ *
+ * @see .lore/plans/vi-mode-pair-writing.md (TD-10)
+ */
+
+import { describe, it, expect, afterEach } from "bun:test";
+import { renderHook } from "@testing-library/react";
+import { useViCursor, calculateCursorPosition, type UseViCursorOptions } from "../useViCursor";
+import { createRef } from "react";
+
+// Mock textarea for testing
+function createMockTextarea(options: {
+  value?: string;
+  scrollTop?: number;
+  scrollLeft?: number;
+}): HTMLTextAreaElement {
+  const textarea = document.createElement("textarea");
+  textarea.value = options.value ?? "";
+  textarea.scrollTop = options.scrollTop ?? 0;
+  textarea.scrollLeft = options.scrollLeft ?? 0;
+
+  // Set up basic styling that affects cursor position
+  textarea.style.fontFamily = "monospace";
+  textarea.style.fontSize = "14px";
+  textarea.style.lineHeight = "20px";
+  textarea.style.padding = "10px";
+  textarea.style.width = "300px";
+  textarea.style.whiteSpace = "pre-wrap";
+  textarea.style.wordWrap = "break-word";
+  textarea.style.boxSizing = "border-box";
+
+  // Append to DOM so getBoundingClientRect works
+  document.body.appendChild(textarea);
+
+  return textarea;
+}
+
+describe("useViCursor", () => {
+  let textarea: HTMLTextAreaElement | null = null;
+
+  afterEach(() => {
+    if (textarea && textarea.parentNode) {
+      document.body.removeChild(textarea);
+    }
+    textarea = null;
+  });
+
+  describe("showOverlay visibility", () => {
+    it("shows overlay in normal mode when enabled", () => {
+      textarea = createMockTextarea({ value: "hello" });
+      const ref = createRef<HTMLTextAreaElement>();
+      (ref as { current: HTMLTextAreaElement }).current = textarea;
+
+      const { result } = renderHook(() =>
+        useViCursor({
+          textareaRef: ref,
+          cursorPosition: 0,
+          mode: "normal",
+          enabled: true,
+        })
+      );
+
+      expect(result.current.showOverlay).toBe(true);
+    });
+
+    it("shows overlay in command mode when enabled", () => {
+      textarea = createMockTextarea({ value: "hello" });
+      const ref = createRef<HTMLTextAreaElement>();
+      (ref as { current: HTMLTextAreaElement }).current = textarea;
+
+      const { result } = renderHook(() =>
+        useViCursor({
+          textareaRef: ref,
+          cursorPosition: 0,
+          mode: "command",
+          enabled: true,
+        })
+      );
+
+      expect(result.current.showOverlay).toBe(true);
+    });
+
+    it("hides overlay in insert mode", () => {
+      textarea = createMockTextarea({ value: "hello" });
+      const ref = createRef<HTMLTextAreaElement>();
+      (ref as { current: HTMLTextAreaElement }).current = textarea;
+
+      const { result } = renderHook(() =>
+        useViCursor({
+          textareaRef: ref,
+          cursorPosition: 0,
+          mode: "insert",
+          enabled: true,
+        })
+      );
+
+      expect(result.current.showOverlay).toBe(false);
+    });
+
+    it("hides overlay when disabled", () => {
+      textarea = createMockTextarea({ value: "hello" });
+      const ref = createRef<HTMLTextAreaElement>();
+      (ref as { current: HTMLTextAreaElement }).current = textarea;
+
+      const { result } = renderHook(() =>
+        useViCursor({
+          textareaRef: ref,
+          cursorPosition: 0,
+          mode: "normal",
+          enabled: false,
+        })
+      );
+
+      expect(result.current.showOverlay).toBe(false);
+    });
+
+    it("toggles overlay when mode changes from normal to insert", () => {
+      textarea = createMockTextarea({ value: "hello" });
+      const ref = createRef<HTMLTextAreaElement>();
+      (ref as { current: HTMLTextAreaElement }).current = textarea;
+
+      const initialProps: UseViCursorOptions = {
+        textareaRef: ref,
+        cursorPosition: 0,
+        mode: "normal",
+        enabled: true,
+      };
+
+      const { result, rerender } = renderHook(
+        (props: UseViCursorOptions) => useViCursor(props),
+        { initialProps }
+      );
+
+      expect(result.current.showOverlay).toBe(true);
+
+      // Switch to insert mode
+      const insertProps: UseViCursorOptions = {
+        textareaRef: ref,
+        cursorPosition: 0,
+        mode: "insert",
+        enabled: true,
+      };
+      rerender(insertProps);
+
+      expect(result.current.showOverlay).toBe(false);
+    });
+  });
+
+  describe("cursorStyle position", () => {
+    it("returns style object with top, left, height", () => {
+      textarea = createMockTextarea({ value: "hello" });
+      const ref = createRef<HTMLTextAreaElement>();
+      (ref as { current: HTMLTextAreaElement }).current = textarea;
+
+      const { result } = renderHook(() =>
+        useViCursor({
+          textareaRef: ref,
+          cursorPosition: 0,
+          mode: "normal",
+          enabled: true,
+        })
+      );
+
+      expect(result.current.cursorStyle).toHaveProperty("top");
+      expect(result.current.cursorStyle).toHaveProperty("left");
+      expect(result.current.cursorStyle).toHaveProperty("height");
+      expect(typeof result.current.cursorStyle.top).toBe("number");
+      expect(typeof result.current.cursorStyle.left).toBe("number");
+      expect(typeof result.current.cursorStyle.height).toBe("number");
+    });
+
+    it("recalculates position when cursorPosition changes", () => {
+      textarea = createMockTextarea({ value: "hello world" });
+      const ref = createRef<HTMLTextAreaElement>();
+      (ref as { current: HTMLTextAreaElement }).current = textarea;
+
+      const { result, rerender } = renderHook(
+        (props) => useViCursor(props),
+        {
+          initialProps: {
+            textareaRef: ref,
+            cursorPosition: 0,
+            mode: "normal" as const,
+            enabled: true,
+          },
+        }
+      );
+
+      // Verify initial state has position properties
+      expect(result.current.cursorStyle).toHaveProperty("top");
+      expect(result.current.cursorStyle).toHaveProperty("left");
+
+      // Move cursor to position 5 - should not throw
+      rerender({
+        textareaRef: ref,
+        cursorPosition: 5,
+        mode: "normal" as const,
+        enabled: true,
+      });
+
+      // Position properties should still exist after rerender
+      // Note: In JSDOM, getBoundingClientRect returns zeros, so we can't
+      // verify actual pixel positions. The real behavior is tested in
+      // browser integration tests.
+      expect(result.current.cursorStyle).toHaveProperty("top");
+      expect(result.current.cursorStyle).toHaveProperty("left");
+    });
+  });
+
+  describe("null ref handling", () => {
+    it("returns default position when textareaRef is null", () => {
+      const ref = createRef<HTMLTextAreaElement>();
+      // ref.current is null by default
+
+      const { result } = renderHook(() =>
+        useViCursor({
+          textareaRef: ref,
+          cursorPosition: 0,
+          mode: "normal",
+          enabled: true,
+        })
+      );
+
+      // Should have default values without throwing
+      expect(result.current.cursorStyle).toHaveProperty("top");
+      expect(result.current.cursorStyle).toHaveProperty("left");
+    });
+  });
+});
+
+describe("calculateCursorPosition", () => {
+  let textarea: HTMLTextAreaElement | null = null;
+
+  afterEach(() => {
+    if (textarea && textarea.parentNode) {
+      document.body.removeChild(textarea);
+    }
+    textarea = null;
+  });
+
+  it("returns position with top, left, height", () => {
+    textarea = createMockTextarea({ value: "hello" });
+
+    const position = calculateCursorPosition(textarea, 0);
+
+    expect(position).toHaveProperty("top");
+    expect(position).toHaveProperty("left");
+    expect(position).toHaveProperty("height");
+    expect(typeof position.top).toBe("number");
+    expect(typeof position.left).toBe("number");
+    expect(typeof position.height).toBe("number");
+  });
+
+  it("calculates position for different cursor positions without error", () => {
+    textarea = createMockTextarea({ value: "hello world" });
+
+    // These should all complete without throwing
+    const pos0 = calculateCursorPosition(textarea, 0);
+    const pos5 = calculateCursorPosition(textarea, 5);
+    const pos10 = calculateCursorPosition(textarea, 10);
+
+    // All should return valid position objects
+    // Note: In JSDOM, getBoundingClientRect returns zeros, so we verify
+    // structure rather than actual pixel values
+    expect(pos0).toHaveProperty("top");
+    expect(pos0).toHaveProperty("left");
+    expect(pos5).toHaveProperty("top");
+    expect(pos5).toHaveProperty("left");
+    expect(pos10).toHaveProperty("top");
+    expect(pos10).toHaveProperty("left");
+  });
+
+  it("calculates position for different lines without error", () => {
+    textarea = createMockTextarea({ value: "line one\nline two\nline three" });
+
+    // These should all complete without throwing
+    const line1 = calculateCursorPosition(textarea, 0);
+    const line2 = calculateCursorPosition(textarea, 9); // Start of "line two"
+    const line3 = calculateCursorPosition(textarea, 18); // Start of "line three"
+
+    // All should return valid position objects
+    expect(line1).toHaveProperty("top");
+    expect(line1).toHaveProperty("height");
+    expect(line2).toHaveProperty("top");
+    expect(line2).toHaveProperty("height");
+    expect(line3).toHaveProperty("top");
+    expect(line3).toHaveProperty("height");
+  });
+
+  it("handles empty textarea", () => {
+    textarea = createMockTextarea({ value: "" });
+
+    // Should not throw
+    const position = calculateCursorPosition(textarea, 0);
+    expect(position).toHaveProperty("top");
+    expect(position).toHaveProperty("left");
+    expect(position).toHaveProperty("height");
+  });
+
+  it("handles cursor at end of text", () => {
+    textarea = createMockTextarea({ value: "hello" });
+
+    // Should not throw when cursor is at end
+    const position = calculateCursorPosition(textarea, 5);
+    expect(position).toHaveProperty("top");
+  });
+
+  it("cleans up mirror element after calculation", () => {
+    textarea = createMockTextarea({ value: "hello" });
+
+    const initialChildCount = document.body.children.length;
+    calculateCursorPosition(textarea, 0);
+    const finalChildCount = document.body.children.length;
+
+    // Should clean up mirror element (only textarea should remain as added element)
+    expect(finalChildCount).toBe(initialChildCount);
+  });
+
+  it("accounts for scroll offset in position", () => {
+    textarea = createMockTextarea({
+      value: "a\nb\nc\nd\ne\nf\ng\nh\ni\nj\nk\nl\nm\nn\no\np",
+      scrollTop: 0,
+    });
+
+    // Make textarea small so it can scroll
+    textarea.style.height = "50px";
+    textarea.style.overflow = "auto";
+
+    // Calculate position before scroll
+    calculateCursorPosition(textarea, 30); // Somewhere in the middle
+
+    // Simulate scroll
+    textarea.scrollTop = 20;
+
+    // Calculate position after scroll - key is that it doesn't throw
+    const posAfterScroll = calculateCursorPosition(textarea, 30);
+
+    // The top position should account for scroll
+    // In JSDOM, getBoundingClientRect returns zeros, so we just verify
+    // the function handles scroll without error
+    expect(posAfterScroll).toHaveProperty("top");
+  });
+});
diff --git a/frontend/src/hooks/__tests__/useViMode.test.ts b/frontend/src/hooks/__tests__/useViMode.test.ts
new file mode 100644
index 00000000..98fbdaaf
--- /dev/null
+++ b/frontend/src/hooks/__tests__/useViMode.test.ts
@@ -0,0 +1,4966 @@
+/**
+ * useViMode Hook Tests
+ *
+ * Tests the vi mode state machine: mode transitions between normal, insert, and command.
+ * Also tests movement commands (h, j, k, l, 0, $), delete commands (x, dd),
+ * yank/put commands (yy, p, P), and undo.
+ *
+ * @see .lore/plans/vi-mode-pair-writing.md
+ * @see REQ-4: Support three modes: Normal (default), Insert, and Command
+ * @see REQ-6: Esc returns to Normal mode from Insert or Command mode
+ * @see REQ-7: Movement: h (left), j (down), k (up), l (right)
+ * @see REQ-8: Line movement: 0 (start of line), $ (end of line)
+ * @see REQ-10: Delete: x (character), dd (line)
+ * @see REQ-11: Yank/put: yy (copy line), p (paste after), P (paste before)
+ * @see REQ-12: Undo: u undoes last edit operation
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { renderHook, act } from "@testing-library/react";
+import {
+  useViMode,
+  type UseViModeOptions,
+  getLineInfo,
+  getLineCount,
+  getLinePositions,
+  moveCursor,
+  executeExCommand,
+} from "../useViMode";
+
+// Helper to create a mock KeyboardEvent
+function createKeyEvent(
+  key: string,
+  options: Partial<React.KeyboardEvent<HTMLTextAreaElement>> = {}
+): React.KeyboardEvent<HTMLTextAreaElement> {
+  const prevented = { value: false };
+  return {
+    key,
+    preventDefault: () => {
+      prevented.value = true;
+    },
+    get defaultPrevented() {
+      return prevented.value;
+    },
+    ctrlKey: false,
+    metaKey: false,
+    altKey: false,
+    shiftKey: false,
+    ...options,
+  } as React.KeyboardEvent<HTMLTextAreaElement>;
+}
+
+describe("useViMode", () => {
+  const defaultOptions: UseViModeOptions = {
+    enabled: true,
+  };
+
+  describe("initial state", () => {
+    it("starts in normal mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it("starts with empty command buffer", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      expect(result.current.commandBuffer).toBe("");
+    });
+
+    it("starts with null pending count", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      expect(result.current.pendingCount).toBeNull();
+    });
+
+    it("starts with null pending operator", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      expect(result.current.pendingOperator).toBeNull();
+    });
+
+    it("starts with null clipboard", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      expect(result.current.clipboard).toBeNull();
+    });
+
+    it("starts with empty undo stack", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+  });
+
+  describe("normal to insert mode transitions", () => {
+    it("transitions to insert mode on 'i' key", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const event = createKeyEvent("i");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("transitions to insert mode on 'a' key", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const event = createKeyEvent("a");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(result.current.mode).toBe("insert");
+    });
+
+    it("transitions to insert mode on 'A' key", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const event = createKeyEvent("A");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(result.current.mode).toBe("insert");
+    });
+
+    it("transitions to insert mode on 'o' key", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const event = createKeyEvent("o");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(result.current.mode).toBe("insert");
+    });
+
+    it("transitions to insert mode on 'O' key", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const event = createKeyEvent("O");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(result.current.mode).toBe("insert");
+    });
+  });
+
+  describe("normal to command mode transitions", () => {
+    it("transitions to command mode on ':' key", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const event = createKeyEvent(":");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(result.current.mode).toBe("command");
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("clears command buffer when entering command mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // First enter command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+
+      // Type something
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+
+      expect(result.current.commandBuffer).toBe("w");
+
+      // Exit command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      // Re-enter command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+
+      expect(result.current.commandBuffer).toBe("");
+    });
+  });
+
+  describe("insert to normal mode transitions", () => {
+    it("transitions to normal mode on Escape", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Enter insert mode first
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+      expect(result.current.mode).toBe("insert");
+
+      // Press Escape
+      const escapeEvent = createKeyEvent("Escape");
+      act(() => {
+        result.current.handleKeyDown(escapeEvent);
+      });
+
+      expect(result.current.mode).toBe("normal");
+      expect(escapeEvent.defaultPrevented).toBe(true);
+    });
+
+    it("allows other keys through in insert mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Enter insert mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      // Regular keys should not be prevented in insert mode
+      const letterEvent = createKeyEvent("x");
+      act(() => {
+        result.current.handleKeyDown(letterEvent);
+      });
+
+      expect(result.current.mode).toBe("insert"); // Still in insert mode
+      expect(letterEvent.defaultPrevented).toBe(false); // Key allowed through
+    });
+  });
+
+  describe("command to normal mode transitions", () => {
+    it("transitions to normal mode on Escape", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Enter command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      expect(result.current.mode).toBe("command");
+
+      // Press Escape
+      const escapeEvent = createKeyEvent("Escape");
+      act(() => {
+        result.current.handleKeyDown(escapeEvent);
+      });
+
+      expect(result.current.mode).toBe("normal");
+      expect(escapeEvent.defaultPrevented).toBe(true);
+    });
+
+    it("clears command buffer on Escape", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Enter command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+
+      // Type something
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+
+      expect(result.current.commandBuffer).toBe("wq");
+
+      // Press Escape
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      expect(result.current.commandBuffer).toBe("");
+    });
+
+    it("transitions to normal mode on Ctrl+C", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Enter command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      expect(result.current.mode).toBe("command");
+
+      // Type something
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      expect(result.current.commandBuffer).toBe("w");
+
+      // Press Ctrl+C (standard vi abort)
+      const ctrlCEvent = createKeyEvent("c", { ctrlKey: true });
+      act(() => {
+        result.current.handleKeyDown(ctrlCEvent);
+      });
+
+      expect(result.current.mode).toBe("normal");
+      expect(result.current.commandBuffer).toBe("");
+      expect(ctrlCEvent.defaultPrevented).toBe(true);
+    });
+
+    it("transitions to normal mode on Enter", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Enter command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+
+      // Press Enter
+      const enterEvent = createKeyEvent("Enter");
+      act(() => {
+        result.current.handleKeyDown(enterEvent);
+      });
+
+      expect(result.current.mode).toBe("normal");
+      expect(enterEvent.defaultPrevented).toBe(true);
+    });
+
+    it("clears command buffer on Enter", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Enter command mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+
+      // Type something
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+
+      expect(result.current.commandBuffer).toBe("w");
+
+      // Press Enter
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(result.current.commandBuffer).toBe("");
+    });
+  });
+
+  describe("command buffer", () => {
+    it("accumulates characters in command mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("!"));
+      });
+
+      expect(result.current.commandBuffer).toBe("wq!");
+    });
+
+    it("handles backspace in command buffer", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Backspace"));
+      });
+
+      expect(result.current.commandBuffer).toBe("w");
+    });
+
+    it("prevents default for characters in command mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+
+      const wEvent = createKeyEvent("w");
+      act(() => {
+        result.current.handleKeyDown(wEvent);
+      });
+
+      expect(wEvent.defaultPrevented).toBe(true);
+    });
+  });
+
+  describe("normal mode key blocking", () => {
+    it("prevents default for letter keys in normal mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const xEvent = createKeyEvent("x");
+      act(() => {
+        result.current.handleKeyDown(xEvent);
+      });
+
+      expect(xEvent.defaultPrevented).toBe(true);
+    });
+
+    it("allows keys with ctrl modifier through in normal mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const ctrlCEvent = createKeyEvent("c", { ctrlKey: true });
+      act(() => {
+        result.current.handleKeyDown(ctrlCEvent);
+      });
+
+      expect(ctrlCEvent.defaultPrevented).toBe(false);
+    });
+
+    it("allows keys with meta modifier through in normal mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const metaCEvent = createKeyEvent("c", { metaKey: true });
+      act(() => {
+        result.current.handleKeyDown(metaCEvent);
+      });
+
+      expect(metaCEvent.defaultPrevented).toBe(false);
+    });
+
+    it("allows multi-character keys (like Arrow keys) through in normal mode", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      const arrowEvent = createKeyEvent("ArrowDown");
+      act(() => {
+        result.current.handleKeyDown(arrowEvent);
+      });
+
+      expect(arrowEvent.defaultPrevented).toBe(false);
+    });
+  });
+
+  describe("enabled option", () => {
+    it("does not change mode when disabled", () => {
+      const { result } = renderHook(() => useViMode({ enabled: false }));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it("does not prevent default when disabled", () => {
+      const { result } = renderHook(() => useViMode({ enabled: false }));
+
+      const event = createKeyEvent("i");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(false);
+    });
+
+    it("handles dynamic enable/disable", () => {
+      const { result, rerender } = renderHook(
+        (props: UseViModeOptions) => useViMode(props),
+        { initialProps: { enabled: true } }
+      );
+
+      // Enter insert mode while enabled
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+      expect(result.current.mode).toBe("insert");
+
+      // Disable vi mode
+      rerender({ enabled: false });
+
+      // Escape should not work when disabled
+      const escapeEvent = createKeyEvent("Escape");
+      act(() => {
+        result.current.handleKeyDown(escapeEvent);
+      });
+
+      // Still in insert mode because vi mode is disabled
+      expect(result.current.mode).toBe("insert");
+      expect(escapeEvent.defaultPrevented).toBe(false);
+    });
+  });
+
+  describe("mode transition cycle", () => {
+    it("can cycle through all modes", () => {
+      const { result } = renderHook(() => useViMode(defaultOptions));
+
+      // Start in normal
+      expect(result.current.mode).toBe("normal");
+
+      // Normal -> Insert
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+      expect(result.current.mode).toBe("insert");
+
+      // Insert -> Normal
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+      expect(result.current.mode).toBe("normal");
+
+      // Normal -> Command
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      expect(result.current.mode).toBe("command");
+
+      // Command -> Normal
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+      expect(result.current.mode).toBe("normal");
+    });
+  });
+});
+
+/**
+ * Helper function tests for cursor manipulation utilities.
+ */
+describe("cursor manipulation helpers", () => {
+  describe("getLineInfo", () => {
+    it("returns correct info for single line text", () => {
+      const text = "Hello, world!";
+      const info = getLineInfo(text, 7);
+
+      expect(info.lineNumber).toBe(0);
+      expect(info.lineStart).toBe(0);
+      expect(info.lineEnd).toBe(13);
+      expect(info.column).toBe(7);
+    });
+
+    it("returns correct info for cursor at start of text", () => {
+      const text = "Hello, world!";
+      const info = getLineInfo(text, 0);
+
+      expect(info.lineNumber).toBe(0);
+      expect(info.lineStart).toBe(0);
+      expect(info.lineEnd).toBe(13);
+      expect(info.column).toBe(0);
+    });
+
+    it("returns correct info for cursor at end of text", () => {
+      const text = "Hello, world!";
+      const info = getLineInfo(text, 13);
+
+      expect(info.lineNumber).toBe(0);
+      expect(info.lineStart).toBe(0);
+      expect(info.lineEnd).toBe(13);
+      expect(info.column).toBe(13);
+    });
+
+    it("returns correct info for multiline text - first line", () => {
+      const text = "Line 1\nLine 2\nLine 3";
+      const info = getLineInfo(text, 3); // In "Line 1"
+
+      expect(info.lineNumber).toBe(0);
+      expect(info.lineStart).toBe(0);
+      expect(info.lineEnd).toBe(6);
+      expect(info.column).toBe(3);
+    });
+
+    it("returns correct info for multiline text - second line", () => {
+      const text = "Line 1\nLine 2\nLine 3";
+      const info = getLineInfo(text, 10); // In "Line 2"
+
+      expect(info.lineNumber).toBe(1);
+      expect(info.lineStart).toBe(7);
+      expect(info.lineEnd).toBe(13);
+      expect(info.column).toBe(3);
+    });
+
+    it("returns correct info for multiline text - last line", () => {
+      const text = "Line 1\nLine 2\nLine 3";
+      const info = getLineInfo(text, 17); // In "Line 3"
+
+      expect(info.lineNumber).toBe(2);
+      expect(info.lineStart).toBe(14);
+      expect(info.lineEnd).toBe(20);
+      expect(info.column).toBe(3);
+    });
+
+    it("handles empty text", () => {
+      const text = "";
+      const info = getLineInfo(text, 0);
+
+      expect(info.lineNumber).toBe(0);
+      expect(info.lineStart).toBe(0);
+      expect(info.lineEnd).toBe(0);
+      expect(info.column).toBe(0);
+    });
+
+    it("handles cursor right after newline", () => {
+      const text = "Line 1\nLine 2";
+      const info = getLineInfo(text, 7); // Right after newline
+
+      expect(info.lineNumber).toBe(1);
+      expect(info.lineStart).toBe(7);
+      expect(info.column).toBe(0);
+    });
+
+    it("handles empty line in middle", () => {
+      const text = "Line 1\n\nLine 3";
+      const info = getLineInfo(text, 7); // On empty line
+
+      expect(info.lineNumber).toBe(1);
+      expect(info.lineStart).toBe(7);
+      expect(info.lineEnd).toBe(7);
+      expect(info.column).toBe(0);
+    });
+  });
+
+  describe("getLineCount", () => {
+    it("returns 1 for empty string", () => {
+      expect(getLineCount("")).toBe(1);
+    });
+
+    it("returns 1 for single line without newline", () => {
+      expect(getLineCount("Hello")).toBe(1);
+    });
+
+    it("returns 2 for text with one newline", () => {
+      expect(getLineCount("Hello\nWorld")).toBe(2);
+    });
+
+    it("returns 3 for text with two newlines", () => {
+      expect(getLineCount("Line 1\nLine 2\nLine 3")).toBe(3);
+    });
+
+    it("counts trailing newline as additional line", () => {
+      expect(getLineCount("Hello\n")).toBe(2);
+    });
+  });
+
+  describe("getLinePositions", () => {
+    it("returns correct positions for first line", () => {
+      const text = "Line 1\nLine 2\nLine 3";
+      const result = getLinePositions(text, 0);
+
+      expect(result).not.toBeNull();
+      expect(result!.lineStart).toBe(0);
+      expect(result!.lineEnd).toBe(6);
+    });
+
+    it("returns correct positions for middle line", () => {
+      const text = "Line 1\nLine 2\nLine 3";
+      const result = getLinePositions(text, 1);
+
+      expect(result).not.toBeNull();
+      expect(result!.lineStart).toBe(7);
+      expect(result!.lineEnd).toBe(13);
+    });
+
+    it("returns correct positions for last line", () => {
+      const text = "Line 1\nLine 2\nLine 3";
+      const result = getLinePositions(text, 2);
+
+      expect(result).not.toBeNull();
+      expect(result!.lineStart).toBe(14);
+      expect(result!.lineEnd).toBe(20);
+    });
+
+    it("returns null for non-existent line", () => {
+      const text = "Line 1\nLine 2";
+      const result = getLinePositions(text, 5);
+
+      expect(result).toBeNull();
+    });
+
+    it("handles single line text", () => {
+      const text = "Hello";
+      const result = getLinePositions(text, 0);
+
+      expect(result).not.toBeNull();
+      expect(result!.lineStart).toBe(0);
+      expect(result!.lineEnd).toBe(5);
+    });
+
+    it("handles empty line", () => {
+      const text = "Line 1\n\nLine 3";
+      const result = getLinePositions(text, 1);
+
+      expect(result).not.toBeNull();
+      expect(result!.lineStart).toBe(7);
+      expect(result!.lineEnd).toBe(7);
+    });
+  });
+
+  describe("moveCursor", () => {
+    let textarea: HTMLTextAreaElement;
+
+    beforeEach(() => {
+      textarea = document.createElement("textarea");
+      textarea.value = "Hello, world!";
+      document.body.appendChild(textarea);
+    });
+
+    afterEach(() => {
+      textarea.remove();
+    });
+
+    it("sets selectionStart and selectionEnd to same value", () => {
+      moveCursor(textarea, 5);
+
+      expect(textarea.selectionStart).toBe(5);
+      expect(textarea.selectionEnd).toBe(5);
+    });
+
+    it("clamps to 0 when position is negative", () => {
+      moveCursor(textarea, -5);
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+
+    it("clamps to text length when position exceeds length", () => {
+      moveCursor(textarea, 100);
+
+      expect(textarea.selectionStart).toBe(13);
+      expect(textarea.selectionEnd).toBe(13);
+    });
+
+    it("handles position at start", () => {
+      moveCursor(textarea, 0);
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+
+    it("handles position at end", () => {
+      moveCursor(textarea, 13);
+
+      expect(textarea.selectionStart).toBe(13);
+      expect(textarea.selectionEnd).toBe(13);
+    });
+  });
+});
+
+/**
+ * Unit tests for executeExCommand function.
+ *
+ * @see REQ-15: :w saves file, remains in Pair Writing
+ * @see REQ-16: :wq saves file and exits Pair Writing
+ * @see REQ-17: :q exits if no unsaved changes; shows confirmation dialog if unsaved
+ * @see REQ-18: :q! exits without saving (discards changes)
+ */
+describe("executeExCommand", () => {
+  it(":w calls onSave callback only", () => {
+    let saveCalled = false;
+    let exitCalled = false;
+    let quitWithUnsavedCalled = false;
+
+    executeExCommand("w", {
+      onSave: () => {
+        saveCalled = true;
+      },
+      onExit: () => {
+        exitCalled = true;
+      },
+      onQuitWithUnsaved: () => {
+        quitWithUnsavedCalled = true;
+      },
+    });
+
+    expect(saveCalled).toBe(true);
+    expect(exitCalled).toBe(false);
+    expect(quitWithUnsavedCalled).toBe(false);
+  });
+
+  it(":wq calls onSave then onExit", () => {
+    const callOrder: string[] = [];
+
+    executeExCommand("wq", {
+      onSave: () => {
+        callOrder.push("save");
+      },
+      onExit: () => {
+        callOrder.push("exit");
+      },
+    });
+
+    expect(callOrder).toEqual(["save", "exit"]);
+  });
+
+  it(":x is alias for :wq", () => {
+    const callOrder: string[] = [];
+
+    executeExCommand("x", {
+      onSave: () => {
+        callOrder.push("save");
+      },
+      onExit: () => {
+        callOrder.push("exit");
+      },
+    });
+
+    expect(callOrder).toEqual(["save", "exit"]);
+  });
+
+  it(":q calls onQuitWithUnsaved", () => {
+    let quitWithUnsavedCalled = false;
+    let exitCalled = false;
+
+    executeExCommand("q", {
+      onExit: () => {
+        exitCalled = true;
+      },
+      onQuitWithUnsaved: () => {
+        quitWithUnsavedCalled = true;
+      },
+    });
+
+    expect(quitWithUnsavedCalled).toBe(true);
+    expect(exitCalled).toBe(false);
+  });
+
+  it(":q! calls onExit directly (force quit)", () => {
+    let exitCalled = false;
+    let quitWithUnsavedCalled = false;
+
+    executeExCommand("q!", {
+      onExit: () => {
+        exitCalled = true;
+      },
+      onQuitWithUnsaved: () => {
+        quitWithUnsavedCalled = true;
+      },
+    });
+
+    expect(exitCalled).toBe(true);
+    expect(quitWithUnsavedCalled).toBe(false);
+  });
+
+  it("trims whitespace from command", () => {
+    let saveCalled = false;
+
+    executeExCommand("  w  ", {
+      onSave: () => {
+        saveCalled = true;
+      },
+    });
+
+    expect(saveCalled).toBe(true);
+  });
+
+  it("unknown command is no-op", () => {
+    let saveCalled = false;
+    let exitCalled = false;
+    let quitWithUnsavedCalled = false;
+
+    executeExCommand("foo", {
+      onSave: () => {
+        saveCalled = true;
+      },
+      onExit: () => {
+        exitCalled = true;
+      },
+      onQuitWithUnsaved: () => {
+        quitWithUnsavedCalled = true;
+      },
+    });
+
+    expect(saveCalled).toBe(false);
+    expect(exitCalled).toBe(false);
+    expect(quitWithUnsavedCalled).toBe(false);
+  });
+
+  it("empty command is no-op", () => {
+    let saveCalled = false;
+
+    executeExCommand("", {
+      onSave: () => {
+        saveCalled = true;
+      },
+    });
+
+    expect(saveCalled).toBe(false);
+  });
+
+  it("handles empty callbacks object", () => {
+    // Should not throw
+    expect(() => executeExCommand("w", {})).not.toThrow();
+    expect(() => executeExCommand("wq", {})).not.toThrow();
+    expect(() => executeExCommand("q", {})).not.toThrow();
+    expect(() => executeExCommand("q!", {})).not.toThrow();
+  });
+});
+
+/**
+ * Movement command tests.
+ *
+ * @see REQ-7: Movement: h (left), j (down), k (up), l (right)
+ * @see REQ-8: Line movement: 0 (start of line), $ (end of line)
+ */
+describe("movement commands", () => {
+  let textarea: HTMLTextAreaElement;
+  let textareaRef: React.RefObject<HTMLTextAreaElement>;
+
+  function createTextareaRef(ta: HTMLTextAreaElement) {
+    return { current: ta } as React.RefObject<HTMLTextAreaElement>;
+  }
+
+  beforeEach(() => {
+    textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+    textareaRef = createTextareaRef(textarea);
+  });
+
+  afterEach(() => {
+    textarea.remove();
+  });
+
+  function getOptionsWithTextarea(): UseViModeOptions {
+    return {
+      enabled: true,
+      textareaRef,
+    };
+  }
+
+  describe("h (move left)", () => {
+    it("moves cursor left one character", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(textarea.selectionStart).toBe(2);
+      expect(textarea.selectionEnd).toBe(2);
+    });
+
+    it("stays at position 0 when already at start", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+
+    it("moves from position 1 to position 0", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 1;
+      textarea.selectionEnd = 1;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+
+    it("collapses selection when moving", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 1;
+      textarea.selectionEnd = 4; // Selection exists
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      // Moves based on selectionStart, collapses selection
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+  });
+
+  describe("l (move right)", () => {
+    it("moves cursor right one character", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("l"));
+      });
+
+      expect(textarea.selectionStart).toBe(3);
+      expect(textarea.selectionEnd).toBe(3);
+    });
+
+    it("stays at end when already at end", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 5;
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("l"));
+      });
+
+      expect(textarea.selectionStart).toBe(5);
+      expect(textarea.selectionEnd).toBe(5);
+    });
+
+    it("moves from second-to-last to last position", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 4;
+      textarea.selectionEnd = 4;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("l"));
+      });
+
+      expect(textarea.selectionStart).toBe(5);
+      expect(textarea.selectionEnd).toBe(5);
+    });
+  });
+
+  describe("j (move down)", () => {
+    it("moves cursor down one line", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3; // "Lin|e 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      // Should be at position 10 ("Lin|e 2")
+      expect(textarea.selectionStart).toBe(10);
+      expect(textarea.selectionEnd).toBe(10);
+    });
+
+    it("maintains column position when moving down", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 2; // "He|llo"
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      // Should be at "Wo|rld" (position 8)
+      expect(textarea.selectionStart).toBe(8);
+      expect(textarea.selectionEnd).toBe(8);
+    });
+
+    it("clamps column when next line is shorter", () => {
+      textarea.value = "Hello World\nHi";
+      textarea.selectionStart = 8; // "Hello Wo|rld"
+      textarea.selectionEnd = 8;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      // Next line only has 2 chars, should clamp to end (position 14 = 12 + 2)
+      expect(textarea.selectionStart).toBe(14);
+      expect(textarea.selectionEnd).toBe(14);
+    });
+
+    it("stays on last line when already at last line", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 17; // "Lin|e 3"
+      textarea.selectionEnd = 17;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      // Should stay at same position
+      expect(textarea.selectionStart).toBe(17);
+      expect(textarea.selectionEnd).toBe(17);
+    });
+
+    it("works with single line text (stays in place)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      expect(textarea.selectionStart).toBe(3);
+      expect(textarea.selectionEnd).toBe(3);
+    });
+
+    it("handles empty lines", () => {
+      textarea.value = "Line 1\n\nLine 3";
+      textarea.selectionStart = 3; // "Lin|e 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      // Should go to empty line, column clamped to 0 (position 7)
+      expect(textarea.selectionStart).toBe(7);
+      expect(textarea.selectionEnd).toBe(7);
+    });
+  });
+
+  describe("k (move up)", () => {
+    it("moves cursor up one line", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // "Lin|e 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      // Should be at position 3 ("Lin|e 1")
+      expect(textarea.selectionStart).toBe(3);
+      expect(textarea.selectionEnd).toBe(3);
+    });
+
+    it("maintains column position when moving up", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 8; // "Wo|rld"
+      textarea.selectionEnd = 8;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      // Should be at "He|llo" (position 2)
+      expect(textarea.selectionStart).toBe(2);
+      expect(textarea.selectionEnd).toBe(2);
+    });
+
+    it("clamps column when previous line is shorter", () => {
+      textarea.value = "Hi\nHello World";
+      textarea.selectionStart = 11; // "Hello Wo|rld"
+      textarea.selectionEnd = 11;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      // Previous line only has 2 chars, should clamp to end (position 2)
+      expect(textarea.selectionStart).toBe(2);
+      expect(textarea.selectionEnd).toBe(2);
+    });
+
+    it("stays on first line when already at first line", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3; // "Lin|e 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      // Should stay at same position
+      expect(textarea.selectionStart).toBe(3);
+      expect(textarea.selectionEnd).toBe(3);
+    });
+
+    it("works with single line text (stays in place)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      expect(textarea.selectionStart).toBe(3);
+      expect(textarea.selectionEnd).toBe(3);
+    });
+
+    it("handles empty lines", () => {
+      textarea.value = "Line 1\n\nLine 3";
+      textarea.selectionStart = 8; // "L|ine 3"
+      textarea.selectionEnd = 8;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      // Should go to empty line, column clamped to 0 (position 7)
+      expect(textarea.selectionStart).toBe(7);
+      expect(textarea.selectionEnd).toBe(7);
+    });
+  });
+
+  describe("0 (move to line start)", () => {
+    it("moves cursor to start of current line", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 7;
+      textarea.selectionEnd = 7;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+
+    it("stays at start when already at start", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+
+    it("works on second line of multiline text", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // "Lin|e 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      expect(textarea.selectionStart).toBe(7); // Start of "Line 2"
+      expect(textarea.selectionEnd).toBe(7);
+    });
+
+    it("works on empty line", () => {
+      textarea.value = "Line 1\n\nLine 3";
+      textarea.selectionStart = 7; // On the empty line
+      textarea.selectionEnd = 7;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      expect(textarea.selectionStart).toBe(7);
+      expect(textarea.selectionEnd).toBe(7);
+    });
+
+    it("works from end of line", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 5;
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(textarea.selectionEnd).toBe(0);
+    });
+  });
+
+  describe("$ (move to line end)", () => {
+    it("moves cursor to end of current line", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("$"));
+      });
+
+      expect(textarea.selectionStart).toBe(13);
+      expect(textarea.selectionEnd).toBe(13);
+    });
+
+    it("stays at end when already at end", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 13;
+      textarea.selectionEnd = 13;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("$"));
+      });
+
+      expect(textarea.selectionStart).toBe(13);
+      expect(textarea.selectionEnd).toBe(13);
+    });
+
+    it("works on middle line of multiline text", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 7; // "L|ine 2"
+      textarea.selectionEnd = 7;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("$"));
+      });
+
+      expect(textarea.selectionStart).toBe(13); // End of "Line 2" (before newline)
+      expect(textarea.selectionEnd).toBe(13);
+    });
+
+    it("works on empty line", () => {
+      textarea.value = "Line 1\n\nLine 3";
+      textarea.selectionStart = 7; // On the empty line
+      textarea.selectionEnd = 7;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("$"));
+      });
+
+      expect(textarea.selectionStart).toBe(7);
+      expect(textarea.selectionEnd).toBe(7);
+    });
+
+    it("works from start of line", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("$"));
+      });
+
+      expect(textarea.selectionStart).toBe(5);
+      expect(textarea.selectionEnd).toBe(5);
+    });
+
+    it("does not include newline character", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("$"));
+      });
+
+      // Should be at position 6 (end of "Line 1"), not 7 (the newline)
+      expect(textarea.selectionStart).toBe(6);
+      expect(textarea.selectionEnd).toBe(6);
+    });
+  });
+
+  describe("movement without textarea ref", () => {
+    it("does not crash when textareaRef is not provided", () => {
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: undefined })
+      );
+
+      const event = createKeyEvent("h");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      // Should prevent default but not crash
+      expect(event.defaultPrevented).toBe(true);
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it("does not crash when textareaRef.current is null", () => {
+      const nullRef = {
+        current: null,
+      } as React.RefObject<HTMLTextAreaElement | null>;
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: nullRef })
+      );
+
+      const event = createKeyEvent("j");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      // Should prevent default but not crash
+      expect(event.defaultPrevented).toBe(true);
+      expect(result.current.mode).toBe("normal");
+    });
+  });
+
+  describe("movement commands prevent default", () => {
+    it("h prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("h");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("j prevents default", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("j");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("k prevents default", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("k");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("l prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("l");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("0 prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("0");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("$ prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("$");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+  });
+});
+
+/**
+ * Insert mode entry command tests.
+ *
+ * @see REQ-9: Insert mode entry: i (before cursor), a (after cursor),
+ *             A (end of line), o (new line below), O (new line above)
+ */
+describe("insert mode entry commands", () => {
+  let textarea: HTMLTextAreaElement;
+  let textareaRef: React.RefObject<HTMLTextAreaElement>;
+
+  function createTextareaRef(ta: HTMLTextAreaElement) {
+    return { current: ta } as React.RefObject<HTMLTextAreaElement>;
+  }
+
+  beforeEach(() => {
+    textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+    textareaRef = createTextareaRef(textarea);
+  });
+
+  afterEach(() => {
+    textarea.remove();
+  });
+
+  function getOptionsWithTextarea(
+    onContentChange?: (content: string) => void
+  ): UseViModeOptions {
+    return {
+      enabled: true,
+      textareaRef,
+      onContentChange,
+    };
+  }
+
+  describe("'i' command (insert at cursor)", () => {
+    it("enters insert mode without moving cursor", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(2); // Cursor unchanged
+      expect(textarea.selectionEnd).toBe(2);
+    });
+
+    it("works at start of text", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("works at end of text", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 5;
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(5);
+    });
+
+    it("works with empty text", () => {
+      textarea.value = "";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(0);
+    });
+  });
+
+  describe("'a' command (append after cursor)", () => {
+    it("moves cursor right one position and enters insert mode", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("a"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(3); // Moved right
+      expect(textarea.selectionEnd).toBe(3);
+    });
+
+    it("positions at end when already at end", () => {
+      textarea.value = "Hi";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("a"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(2); // Stays at end (clamped)
+    });
+
+    it("works at start of text", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("a"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(1); // Moved to after first char
+    });
+
+    it("works with empty text", () => {
+      textarea.value = "";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("a"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(0); // Stays at 0 (clamped)
+    });
+  });
+
+  describe("'A' command (append at end of line)", () => {
+    it("moves cursor to end of current line", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 2; // "He|llo"
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("A"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(5); // End of "Hello"
+      expect(textarea.selectionEnd).toBe(5);
+    });
+
+    it("stays at end of single line text", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("A"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(5);
+    });
+
+    it("handles second line", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 8; // "Wo|rld"
+      textarea.selectionEnd = 8;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("A"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(11); // End of "World"
+    });
+
+    it("positions at start of empty line", () => {
+      textarea.value = "Hello\n\nWorld";
+      textarea.selectionStart = 6; // Empty line
+      textarea.selectionEnd = 6;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("A"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(6); // Same position (empty line)
+    });
+
+    it("works when already at end of line", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 5; // Already at end of "Hello"
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("A"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.selectionStart).toBe(5); // Stays at end
+    });
+  });
+
+  describe("'o' command (open line below)", () => {
+    it("inserts newline after current line and positions cursor", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 2; // "He|llo"
+      textarea.selectionEnd = 2;
+
+      let capturedContent = "";
+      const { result } = renderHook(() =>
+        useViMode(
+          getOptionsWithTextarea((content) => {
+            capturedContent = content;
+          })
+        )
+      );
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("Hello\n\nWorld"); // Newline inserted
+      expect(textarea.selectionStart).toBe(6); // Cursor on new blank line
+      expect(capturedContent).toBe("Hello\n\nWorld");
+    });
+
+    it("creates new last line", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("Hello\n");
+      expect(textarea.selectionStart).toBe(6); // After newline
+    });
+
+    it("works with cursor at end of line", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 6; // End of "Line 1"
+      textarea.selectionEnd = 6;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("Line 1\n\nLine 2");
+      expect(textarea.selectionStart).toBe(7);
+    });
+
+    it("works on last line of multi-line text", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 10; // "Lin|e 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("Line 1\nLine 2\n");
+      expect(textarea.selectionStart).toBe(14); // After final newline
+    });
+
+    it("works with empty text", () => {
+      textarea.value = "";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("\n");
+      expect(textarea.selectionStart).toBe(1);
+    });
+  });
+
+  describe("'O' command (open line above)", () => {
+    it("inserts newline before current line and positions cursor", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 8; // "Wo|rld"
+      textarea.selectionEnd = 8;
+
+      let capturedContent = "";
+      const { result } = renderHook(() =>
+        useViMode(
+          getOptionsWithTextarea((content) => {
+            capturedContent = content;
+          })
+        )
+      );
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("Hello\n\nWorld"); // Newline inserted before "World"
+      expect(textarea.selectionStart).toBe(6); // Cursor on new blank line
+      expect(capturedContent).toBe("Hello\n\nWorld");
+    });
+
+    it("creates new first line", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("\nHello");
+      expect(textarea.selectionStart).toBe(0); // At start of new blank line
+    });
+
+    it("works when on first line of multi-line text", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 3; // "Lin|e 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("\nLine 1\nLine 2");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("works when cursor at start of line", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 6; // Start of "World"
+      textarea.selectionEnd = 6;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("Hello\n\nWorld");
+      expect(textarea.selectionStart).toBe(6); // On new blank line
+    });
+
+    it("works with empty text", () => {
+      textarea.value = "";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("\n");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("handles middle line correctly", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // "Lin|e 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(textarea.value).toBe("Line 1\n\nLine 2\nLine 3");
+      expect(textarea.selectionStart).toBe(7); // On new blank line
+    });
+  });
+
+  describe("insert mode entry prevents default", () => {
+    it("'i' prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("i");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("'a' prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("a");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("'A' prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("A");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("'o' prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("o");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("'O' prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("O");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+  });
+});
+
+/**
+ * Undo stack tests.
+ *
+ * @see REQ-12: Undo: u undoes last edit operation (maintains internal undo stack)
+ * @see TD-9: Undo stack implementation in .lore/plans/vi-mode-pair-writing.md
+ */
+describe("undo stack", () => {
+  let textarea: HTMLTextAreaElement;
+  let textareaRef: React.RefObject<HTMLTextAreaElement>;
+
+  function createTextareaRef(ta: HTMLTextAreaElement) {
+    return { current: ta } as React.RefObject<HTMLTextAreaElement>;
+  }
+
+  beforeEach(() => {
+    textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+    textareaRef = createTextareaRef(textarea);
+  });
+
+  afterEach(() => {
+    textarea.remove();
+  });
+
+  function getOptionsWithTextarea(
+    onContentChange?: (content: string) => void
+  ): UseViModeOptions {
+    return {
+      enabled: true,
+      textareaRef,
+      onContentChange,
+    };
+  }
+
+  describe("pushUndoState", () => {
+    it("increases undo stack size when called", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      expect(result.current.undoStackSize).toBe(0);
+
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("pushes state before entering insert mode via 'i'", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      expect(result.current.undoStackSize).toBe(0);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("pushes state before entering insert mode via 'a'", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("a"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("pushes state before entering insert mode via 'A'", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("A"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("pushes state before 'o' command (which modifies content)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("pushes state before 'O' command (which modifies content)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(result.current.mode).toBe("insert");
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("does not push state for movement commands", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("l"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+  });
+
+  describe("'u' command (undo)", () => {
+    it("prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("u");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("does nothing when undo stack is empty", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      // Content and cursor should be unchanged
+      expect(textarea.value).toBe("Hello");
+      expect(textarea.selectionStart).toBe(2);
+      expect(result.current.undoStackSize).toBe(0);
+    });
+
+    it("restores content from undo stack", () => {
+      textarea.value = "Original";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      let capturedContent = "";
+      const { result } = renderHook(() =>
+        useViMode(
+          getOptionsWithTextarea((content) => {
+            capturedContent = content;
+          })
+        )
+      );
+
+      // Push the original state to undo stack
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      // Simulate an edit (in real usage, this would be insert mode changes)
+      textarea.value = "Modified";
+      textarea.selectionStart = 5;
+      textarea.selectionEnd = 5;
+
+      // Now undo
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("Original");
+      expect(capturedContent).toBe("Original");
+    });
+
+    it("restores cursor position from undo stack", () => {
+      textarea.value = "Hello World";
+      textarea.selectionStart = 5;
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Push state with cursor at position 5
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      // Move cursor
+      textarea.selectionStart = 8;
+      textarea.selectionEnd = 8;
+
+      // Undo should restore cursor to position 5
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.selectionStart).toBe(5);
+      expect(textarea.selectionEnd).toBe(5);
+    });
+
+    it("decreases undo stack size when undo is performed", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Push two states
+      act(() => {
+        result.current.pushUndoState();
+      });
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      expect(result.current.undoStackSize).toBe(2);
+
+      // Undo once
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(result.current.undoStackSize).toBe(1);
+
+      // Undo again
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+
+    it("supports multiple consecutive undos", () => {
+      textarea.value = "State 1";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Push State 1
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      // Change to State 2
+      textarea.value = "State 2";
+      textarea.selectionStart = 1;
+      textarea.selectionEnd = 1;
+
+      // Push State 2
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      // Change to State 3
+      textarea.value = "State 3";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      // First undo: back to State 2
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("State 2");
+      expect(textarea.selectionStart).toBe(1);
+
+      // Second undo: back to State 1
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("State 1");
+      expect(textarea.selectionStart).toBe(0);
+
+      // Third undo: stack is empty, no change
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("State 1");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("undoes 'o' command modifications", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Enter insert mode via 'o' (this pushes undo state first)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+
+      expect(textarea.value).toBe("Hello\n");
+      expect(result.current.mode).toBe("insert");
+
+      // Exit insert mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      expect(result.current.mode).toBe("normal");
+
+      // Undo should restore original content
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("Hello");
+      expect(textarea.selectionStart).toBe(3);
+    });
+
+    it("undoes 'O' command modifications", () => {
+      textarea.value = "World";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Enter insert mode via 'O' (this pushes undo state first)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("O"));
+      });
+
+      expect(textarea.value).toBe("\nWorld");
+      expect(result.current.mode).toBe("insert");
+
+      // Exit insert mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      // Undo should restore original content
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("World");
+      expect(textarea.selectionStart).toBe(2);
+    });
+
+    it("batches insert mode changes into single undo entry", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 5;
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Enter insert mode (pushes undo state)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("a"));
+      });
+
+      expect(result.current.undoStackSize).toBe(1);
+
+      // Simulate typing multiple characters in insert mode
+      // (In real usage, the browser handles this, we just simulate the result)
+      textarea.value = "Hello World";
+      textarea.selectionStart = 11;
+      textarea.selectionEnd = 11;
+
+      // Exit insert mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      // Stack size should still be 1 (no new entries during insert mode)
+      expect(result.current.undoStackSize).toBe(1);
+
+      // Single undo should restore the entire insert mode session
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("Hello");
+      expect(result.current.undoStackSize).toBe(0);
+    });
+  });
+
+  describe("undo stack depth limit", () => {
+    it("limits stack to 100 entries", () => {
+      textarea.value = "Test";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Push 105 states
+      for (let i = 0; i < 105; i++) {
+        act(() => {
+          result.current.pushUndoState();
+        });
+      }
+
+      // Stack should be capped at 100
+      expect(result.current.undoStackSize).toBe(100);
+    });
+
+    it("removes oldest entries when limit exceeded", () => {
+      textarea.value = "Entry 0";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Push first state (Entry 0)
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      // Push 100 more states (101 total, limit is 100)
+      for (let i = 1; i <= 100; i++) {
+        textarea.value = `Entry ${i}`;
+        textarea.selectionStart = i;
+        textarea.selectionEnd = i;
+        act(() => {
+          result.current.pushUndoState();
+        });
+      }
+
+      // Set to final state
+      textarea.value = "Final";
+      textarea.selectionStart = 101;
+      textarea.selectionEnd = 101;
+
+      // Stack should have 100 entries, oldest (Entry 0) should be removed
+      expect(result.current.undoStackSize).toBe(100);
+
+      // Undo 100 times - should get to "Entry 1" (Entry 0 was removed)
+      for (let i = 0; i < 100; i++) {
+        act(() => {
+          result.current.handleKeyDown(createKeyEvent("u"));
+        });
+      }
+
+      // After 100 undos, we should be at the oldest remaining entry
+      // The oldest entry is "Entry 1" (Entry 0 was removed when we exceeded 100)
+      expect(textarea.value).toBe("Entry 1");
+      expect(result.current.undoStackSize).toBe(0);
+    });
+  });
+
+  describe("undo without textarea", () => {
+    it("does not crash when textareaRef is not provided", () => {
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: undefined })
+      );
+
+      // Push should not crash
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      // Undo should not crash
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+
+    it("does not crash when textareaRef.current is null", () => {
+      const nullRef = {
+        current: null,
+      } as React.RefObject<HTMLTextAreaElement | null>;
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: nullRef })
+      );
+
+      // Push should not crash
+      act(() => {
+        result.current.pushUndoState();
+      });
+
+      // Undo should not crash
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+  });
+});
+
+/**
+ * Delete command tests.
+ *
+ * @see REQ-10: Delete: x (character), dd (line)
+ */
+describe("delete commands", () => {
+  let textarea: HTMLTextAreaElement;
+  let textareaRef: React.RefObject<HTMLTextAreaElement>;
+
+  function createTextareaRef(ta: HTMLTextAreaElement) {
+    return { current: ta } as React.RefObject<HTMLTextAreaElement>;
+  }
+
+  beforeEach(() => {
+    textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+    textareaRef = createTextareaRef(textarea);
+  });
+
+  afterEach(() => {
+    textarea.remove();
+  });
+
+  function getOptionsWithTextarea(
+    onContentChange?: (content: string) => void
+  ): UseViModeOptions {
+    return {
+      enabled: true,
+      textareaRef,
+      onContentChange,
+    };
+  }
+
+  describe("'x' command (delete character)", () => {
+    it("deletes the character at cursor position", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      let capturedContent = "";
+      const { result } = renderHook(() =>
+        useViMode(
+          getOptionsWithTextarea((content) => {
+            capturedContent = content;
+          })
+        )
+      );
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("Helo");
+      expect(capturedContent).toBe("Helo");
+    });
+
+    it("prevents default", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("x");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("keeps cursor at same position after delete", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.selectionStart).toBe(2);
+      expect(textarea.selectionEnd).toBe(2);
+    });
+
+    it("clamps cursor when deleting last character", () => {
+      textarea.value = "Hi";
+      textarea.selectionStart = 1;
+      textarea.selectionEnd = 1;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("H");
+      expect(textarea.selectionStart).toBe(1); // Clamped to end
+    });
+
+    it("does nothing when cursor is at end of text", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 5;
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("Hello");
+      expect(textarea.selectionStart).toBe(5);
+    });
+
+    it("does nothing on empty text", () => {
+      textarea.value = "";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("");
+    });
+
+    it("pushes to undo stack before delete", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      expect(result.current.undoStackSize).toBe(0);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("does not push to undo stack when nothing to delete", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 5; // At end
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+
+    it("can be undone with 'u'", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("Helo");
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("Hello");
+      expect(textarea.selectionStart).toBe(2);
+    });
+
+    it("deletes newline character when cursor is on it", () => {
+      textarea.value = "Hello\nWorld";
+      textarea.selectionStart = 5; // On the newline
+      textarea.selectionEnd = 5;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("HelloWorld");
+    });
+
+    it("deletes first character when at position 0", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("ello");
+      expect(textarea.selectionStart).toBe(0);
+    });
+  });
+
+  describe("'dd' command (delete line)", () => {
+    it("sets pending operator on first 'd' press", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingOperator).toBe("d");
+      expect(textarea.value).toBe("Hello"); // No change yet
+    });
+
+    it("prevents default on 'd' press", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("d");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("deletes line on 'dd' sequence", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      let capturedContent = "";
+      const { result } = renderHook(() =>
+        useViMode(
+          getOptionsWithTextarea((content) => {
+            capturedContent = content;
+          })
+        )
+      );
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 3");
+      expect(capturedContent).toBe("Line 1\nLine 3");
+    });
+
+    it("clears pending operator after dd execution", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingOperator).toBeNull();
+    });
+
+    it("positions cursor at start of next line after delete", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      // Cursor should be at start of what was "Line 3" (now at position 7)
+      expect(textarea.selectionStart).toBe(7);
+    });
+
+    it("deletes last line and positions cursor at previous line", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("Line 1");
+      // Cursor should be at start of Line 1
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("deletes only line leaving empty document", () => {
+      textarea.value = "Only line";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("deletes first line of multi-line text", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("Line 2\nLine 3");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("deletes empty line", () => {
+      textarea.value = "Line 1\n\nLine 3";
+      textarea.selectionStart = 7; // On empty line
+      textarea.selectionEnd = 7;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 3");
+    });
+
+    it("does nothing on empty document", () => {
+      textarea.value = "";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("");
+    });
+
+    it("pushes to undo stack before delete", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      expect(result.current.undoStackSize).toBe(0);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      // First 'd' should not push undo state yet
+      expect(result.current.undoStackSize).toBe(0);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      // Second 'd' (execution) should push undo state
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("does not push undo state on empty document", () => {
+      textarea.value = "";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+
+    it("can be undone with 'u'", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 3");
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 2\nLine 3");
+      expect(textarea.selectionStart).toBe(10);
+    });
+
+    it("clears pending operator when other key is pressed", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingOperator).toBe("d");
+
+      // Press a different key
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(result.current.pendingOperator).toBeNull();
+    });
+
+    it("clears pending operator on insert mode entry", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingOperator).toBe("d");
+
+      // Enter insert mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      expect(result.current.pendingOperator).toBeNull();
+      expect(result.current.mode).toBe("insert");
+    });
+
+    it("clears pending operator on Escape in Normal mode", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Press 'd' to set pending operator
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingOperator).toBe("d");
+      expect(result.current.mode).toBe("normal");
+
+      // Press Escape in normal mode to cancel
+      const escEvent = createKeyEvent("Escape");
+      act(() => {
+        result.current.handleKeyDown(escEvent);
+      });
+
+      expect(result.current.pendingOperator).toBeNull();
+      expect(result.current.mode).toBe("normal"); // Still in normal mode
+      expect(escEvent.defaultPrevented).toBe(true);
+    });
+
+    it("clears pending 'y' operator on Escape in Normal mode", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Press 'y' to set pending operator
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.pendingOperator).toBe("y");
+
+      // Press Escape to cancel
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      expect(result.current.pendingOperator).toBeNull();
+    });
+
+    it("clears pending count on Escape in Normal mode", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Press '5' to set pending count
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+
+      expect(result.current.pendingCount).toBe(5);
+
+      // Press Escape to cancel
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      expect(result.current.pendingCount).toBeNull();
+    });
+
+    it("clears both pending count and operator on Escape in Normal mode", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Type "3d" (count + operator pending)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("3"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingCount).toBe(3);
+      expect(result.current.pendingOperator).toBe("d");
+
+      // Press Escape to cancel both
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      expect(result.current.pendingCount).toBeNull();
+      expect(result.current.pendingOperator).toBeNull();
+    });
+  });
+
+  describe("delete without textarea", () => {
+    it("'x' does not crash when textareaRef is null", () => {
+      const nullRef = {
+        current: null,
+      } as React.RefObject<HTMLTextAreaElement | null>;
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: nullRef })
+      );
+
+      const event = createKeyEvent("x");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      // Should prevent default but not crash
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("'dd' does not crash when textareaRef is null", () => {
+      const nullRef = {
+        current: null,
+      } as React.RefObject<HTMLTextAreaElement | null>;
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: nullRef })
+      );
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      // Should not crash
+      expect(result.current.mode).toBe("normal");
+    });
+  });
+});
+
+/**
+ * Yank/Put command tests.
+ *
+ * @see REQ-11: Yank/put: yy (copy line), p (paste after), P (paste before)
+ * @see REQ-20: Yank/put operations use internal clipboard (separate from system)
+ * @see REQ-21: Clipboard persists within Pair Writing session
+ */
+describe("yank/put commands", () => {
+  let textarea: HTMLTextAreaElement;
+  let textareaRef: React.RefObject<HTMLTextAreaElement>;
+
+  function createTextareaRef(ta: HTMLTextAreaElement) {
+    return { current: ta } as React.RefObject<HTMLTextAreaElement>;
+  }
+
+  beforeEach(() => {
+    textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+    textareaRef = createTextareaRef(textarea);
+  });
+
+  afterEach(() => {
+    textarea.remove();
+  });
+
+  function getOptionsWithTextarea(
+    onContentChange?: (content: string) => void
+  ): UseViModeOptions {
+    return {
+      enabled: true,
+      textareaRef,
+      onContentChange,
+    };
+  }
+
+  describe("'yy' command (yank line)", () => {
+    it("sets pending operator on first 'y' press", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.pendingOperator).toBe("y");
+      expect(textarea.value).toBe("Hello"); // No change
+    });
+
+    it("prevents default on 'y' press", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("y");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("yanks line to clipboard on 'yy' sequence", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("Line 2");
+      expect(textarea.value).toBe("Line 1\nLine 2\nLine 3"); // No change to text
+    });
+
+    it("clears pending operator after yy execution", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.pendingOperator).toBeNull();
+    });
+
+    it("yanks empty line", () => {
+      textarea.value = "Line 1\n\nLine 3";
+      textarea.selectionStart = 7; // On empty line
+      textarea.selectionEnd = 7;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("");
+    });
+
+    it("yanks first line", () => {
+      textarea.value = "First\nSecond";
+      textarea.selectionStart = 2; // In "First"
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("First");
+    });
+
+    it("yanks last line", () => {
+      textarea.value = "First\nLast";
+      textarea.selectionStart = 8; // In "Last"
+      textarea.selectionEnd = 8;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("Last");
+    });
+
+    it("clipboard persists across multiple yanks (last yank wins)", () => {
+      textarea.value = "Line A\nLine B\nLine C";
+      textarea.selectionStart = 3; // In "Line A"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank Line A
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("Line A");
+
+      // Move to Line B and yank
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("Line B");
+    });
+
+    it("does not push to undo stack (yank is non-destructive)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+    });
+  });
+
+  describe("'p' command (paste after)", () => {
+    it("pastes clipboard content after current line", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      let capturedContent = "";
+      const { result } = renderHook(() =>
+        useViMode(
+          getOptionsWithTextarea((content) => {
+            capturedContent = content;
+          })
+        )
+      );
+
+      // First yank Line 2
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      // Move back to Line 1 and paste after
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("p"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 2\nLine 2\nLine 3");
+      expect(capturedContent).toBe("Line 1\nLine 2\nLine 2\nLine 3");
+    });
+
+    it("prevents default on 'p' press", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("p");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("positions cursor at start of pasted line", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank Line 2
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      // Move to Line 1 and paste
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("p"));
+      });
+
+      // Cursor should be at start of pasted line (after "Line 1\n")
+      expect(textarea.selectionStart).toBe(7);
+    });
+
+    it("does nothing with empty clipboard", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // No yank, clipboard is null
+      expect(result.current.clipboard).toBeNull();
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("p"));
+      });
+
+      // Content unchanged
+      expect(textarea.value).toBe("Line 1\nLine 2");
+    });
+
+    it("pushes to undo stack before paste", () => {
+      textarea.value = "Line 1";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank current line
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+
+      // Paste
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("p"));
+      });
+
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("paste on last line creates new last line", () => {
+      textarea.value = "First\nLast";
+      textarea.selectionStart = 8; // In "Last"
+      textarea.selectionEnd = 8;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank "First"
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      // Move to Last and paste after
+      textarea.selectionStart = 8;
+      textarea.selectionEnd = 8;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("p"));
+      });
+
+      expect(textarea.value).toBe("First\nLast\nFirst");
+    });
+
+    it("can undo paste operation", () => {
+      textarea.value = "Original";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank and paste
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("p"));
+      });
+
+      expect(textarea.value).toBe("Original\nOriginal");
+
+      // Undo
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("Original");
+    });
+  });
+
+  describe("'P' command (paste before)", () => {
+    it("pastes clipboard content before current line", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      let capturedContent = "";
+      const { result } = renderHook(() =>
+        useViMode(
+          getOptionsWithTextarea((content) => {
+            capturedContent = content;
+          })
+        )
+      );
+
+      // First yank Line 1
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      // Move to Line 2 and paste before
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("P"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 1\nLine 2\nLine 3");
+      expect(capturedContent).toBe("Line 1\nLine 1\nLine 2\nLine 3");
+    });
+
+    it("prevents default on 'P' press", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("P");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("positions cursor at start of pasted line", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank Line 1
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      // Move to Line 2 and paste before
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("P"));
+      });
+
+      // Cursor should be at start of pasted line (at "Line 1" insertion point)
+      expect(textarea.selectionStart).toBe(7);
+    });
+
+    it("does nothing with empty clipboard", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // No yank, clipboard is null
+      expect(result.current.clipboard).toBeNull();
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("P"));
+      });
+
+      // Content unchanged
+      expect(textarea.value).toBe("Line 1\nLine 2");
+    });
+
+    it("pushes to undo stack before paste", () => {
+      textarea.value = "Line 1";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank current line
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.undoStackSize).toBe(0);
+
+      // Paste before
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("P"));
+      });
+
+      expect(result.current.undoStackSize).toBe(1);
+    });
+
+    it("paste on first line creates new first line", () => {
+      textarea.value = "First\nSecond";
+      textarea.selectionStart = 2; // In "First"
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank "Second"
+      textarea.selectionStart = 8;
+      textarea.selectionEnd = 8;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      // Move to First and paste before
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("P"));
+      });
+
+      expect(textarea.value).toBe("Second\nFirst\nSecond");
+    });
+
+    it("can undo paste operation", () => {
+      textarea.value = "Original";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank and paste before
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("P"));
+      });
+
+      expect(textarea.value).toBe("Original\nOriginal");
+
+      // Undo
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      expect(textarea.value).toBe("Original");
+    });
+  });
+
+  describe("pending operator interaction", () => {
+    it("other keys clear pending 'y' operator", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.pendingOperator).toBe("y");
+
+      // Press 'h' (movement key)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(result.current.pendingOperator).toBeNull();
+    });
+
+    it("'y' then 'd' starts delete operator (not yank)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.pendingOperator).toBe("y");
+
+      // Press 'd' - should start delete operator
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingOperator).toBe("d");
+    });
+
+    it("'d' then 'y' starts yank operator (not delete)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(result.current.pendingOperator).toBe("d");
+
+      // Press 'y' - should start yank operator
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.pendingOperator).toBe("y");
+    });
+  });
+
+  describe("yank/put without textarea", () => {
+    it("'yy' does not crash when textareaRef is null", () => {
+      const nullRef = {
+        current: null,
+      } as React.RefObject<HTMLTextAreaElement | null>;
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: nullRef })
+      );
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      // Should not crash
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it("'p' does not crash when textareaRef is null", () => {
+      const nullRef = {
+        current: null,
+      } as React.RefObject<HTMLTextAreaElement | null>;
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: nullRef })
+      );
+
+      const event = createKeyEvent("p");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      // Should prevent default but not crash
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("'P' does not crash when textareaRef is null", () => {
+      const nullRef = {
+        current: null,
+      } as React.RefObject<HTMLTextAreaElement | null>;
+      const { result } = renderHook(() =>
+        useViMode({ enabled: true, textareaRef: nullRef })
+      );
+
+      const event = createKeyEvent("P");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      // Should prevent default but not crash
+      expect(event.defaultPrevented).toBe(true);
+    });
+  });
+});
+
+/**
+ * Numeric prefix tests.
+ *
+ * @see REQ-13: Numeric prefixes for command repetition (e.g., 5j, 3dd, 2x)
+ * @see TD-8: Numeric prefix handling
+ */
+describe("numeric prefixes", () => {
+  let textarea: HTMLTextAreaElement;
+  let textareaRef: React.RefObject<HTMLTextAreaElement>;
+
+  function createTextareaRef(ta: HTMLTextAreaElement) {
+    return { current: ta } as React.RefObject<HTMLTextAreaElement>;
+  }
+
+  beforeEach(() => {
+    textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+    textareaRef = createTextareaRef(textarea);
+  });
+
+  afterEach(() => {
+    textarea.remove();
+  });
+
+  function getOptionsWithTextarea(
+    onContentChange?: (content: string) => void
+  ): UseViModeOptions {
+    return {
+      enabled: true,
+      textareaRef,
+      onContentChange,
+    };
+  }
+
+  describe("count accumulation", () => {
+    it("starts with null pending count", () => {
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      expect(result.current.pendingCount).toBeNull();
+    });
+
+    it("accumulates digits 1-9 as count", () => {
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+
+      expect(result.current.pendingCount).toBe(5);
+    });
+
+    it("accumulates multiple digits", () => {
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("1"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("2"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("3"));
+      });
+
+      expect(result.current.pendingCount).toBe(123);
+    });
+
+    it("treats 0 as movement command when no count pending", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 7;
+      textarea.selectionEnd = 7;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      // Should move to line start, not set count
+      expect(result.current.pendingCount).toBeNull();
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("treats 0 as digit when count is pending (10j case)", () => {
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("1"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      expect(result.current.pendingCount).toBe(10);
+    });
+
+    it("prevents default for digit keys", () => {
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      const event = createKeyEvent("5");
+      act(() => {
+        result.current.handleKeyDown(event);
+      });
+
+      expect(event.defaultPrevented).toBe(true);
+    });
+
+    it("clears count when entering insert mode", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+      expect(result.current.pendingCount).toBe(5);
+
+      // Enter insert mode
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("i"));
+      });
+
+      // Count should be cleared when entering insert mode
+      expect(result.current.pendingCount).toBeNull();
+    });
+
+    it("clears count after command execution", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 4;
+      textarea.selectionEnd = 4;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("2"));
+      });
+      expect(result.current.pendingCount).toBe(2);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(result.current.pendingCount).toBeNull();
+      expect(textarea.selectionStart).toBe(2); // Moved 2 left
+    });
+  });
+
+  describe("movement with count", () => {
+    it("5h moves left 5 characters", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(textarea.selectionStart).toBe(5);
+    });
+
+    it("5l moves right 5 characters", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("l"));
+      });
+
+      expect(textarea.selectionStart).toBe(5);
+    });
+
+    it("3j moves down 3 lines", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3\nLine 4\nLine 5";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("3"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      // Should be on Line 4, column 3
+      expect(textarea.selectionStart).toBe(24); // "Line 1\nLine 2\nLine 3\n" = 21, + 3 = 24
+    });
+
+    it("3k moves up 3 lines", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3\nLine 4\nLine 5";
+      textarea.selectionStart = 24; // In "Line 4"
+      textarea.selectionEnd = 24;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("3"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      // Should be on Line 1, column 3
+      expect(textarea.selectionStart).toBe(3);
+    });
+
+    it("clamps h movement at beginning of text", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("clamps l movement at end of text", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("l"));
+      });
+
+      expect(textarea.selectionStart).toBe(5);
+    });
+
+    it("j stops at last line when count exceeds available lines", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("j"));
+      });
+
+      // Should be on Line 3 (last line), column 3
+      expect(textarea.selectionStart).toBe(17);
+    });
+
+    it("k stops at first line when count exceeds available lines", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 17; // In "Line 3"
+      textarea.selectionEnd = 17;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("k"));
+      });
+
+      // Should be on Line 1 (first line), column 3
+      expect(textarea.selectionStart).toBe(3);
+    });
+  });
+
+  describe("delete with count", () => {
+    it("3x deletes 3 characters", () => {
+      textarea.value = "Hello, world!";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("3"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("lo, world!");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("x clamps delete count to available characters", () => {
+      textarea.value = "Hi";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+
+      expect(textarea.value).toBe("");
+    });
+
+    it("3dd deletes 3 lines", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3\nLine 4\nLine 5";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("3"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("Line 4\nLine 5");
+      expect(textarea.selectionStart).toBe(0);
+    });
+
+    it("dd clamps line count to available lines", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("");
+    });
+
+    it("dd with count from middle of document", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3\nLine 4\nLine 5";
+      textarea.selectionStart = 10; // In "Line 2"
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("2"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 4\nLine 5");
+    });
+
+    it("dd with count from near end of document", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 17; // In "Line 3"
+      textarea.selectionEnd = 17;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+
+      // Should delete just Line 3 (only 1 line available)
+      expect(textarea.value).toBe("Line 1\nLine 2");
+    });
+  });
+
+  describe("yank with count", () => {
+    it("3yy yanks 3 lines", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3\nLine 4\nLine 5";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("3"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("Line 1\nLine 2\nLine 3");
+      // Text should be unchanged
+      expect(textarea.value).toBe("Line 1\nLine 2\nLine 3\nLine 4\nLine 5");
+    });
+
+    it("yy clamps line count to available lines", () => {
+      textarea.value = "Line 1\nLine 2";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("Line 1\nLine 2");
+    });
+
+    it("multi-line yank and paste works correctly", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3; // In "Line 1"
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Yank 2 lines
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("2"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+
+      expect(result.current.clipboard).toBe("Line 1\nLine 2");
+
+      // Move to Line 3 and paste after
+      textarea.selectionStart = 17;
+      textarea.selectionEnd = 17;
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("p"));
+      });
+
+      expect(textarea.value).toBe("Line 1\nLine 2\nLine 3\nLine 1\nLine 2");
+    });
+  });
+
+  describe("count with pending operator", () => {
+    it("count persists across first d key", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("2"));
+      });
+      expect(result.current.pendingCount).toBe(2);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      // Count should still be there, pending operator set
+      expect(result.current.pendingOperator).toBe("d");
+      expect(result.current.pendingCount).toBe(2);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("d"));
+      });
+      // Now both should be cleared
+      expect(result.current.pendingOperator).toBeNull();
+      expect(result.current.pendingCount).toBeNull();
+      expect(textarea.value).toBe("Line 3");
+    });
+
+    it("count persists across first y key", () => {
+      textarea.value = "Line 1\nLine 2\nLine 3";
+      textarea.selectionStart = 3;
+      textarea.selectionEnd = 3;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("2"));
+      });
+      expect(result.current.pendingCount).toBe(2);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      // Count should still be there, pending operator set
+      expect(result.current.pendingOperator).toBe("y");
+      expect(result.current.pendingCount).toBe(2);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("y"));
+      });
+      // Now both should be cleared
+      expect(result.current.pendingOperator).toBeNull();
+      expect(result.current.pendingCount).toBeNull();
+      expect(result.current.clipboard).toBe("Line 1\nLine 2");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("handles very large counts gracefully", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 2;
+      textarea.selectionEnd = 2;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Type 999
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("9"));
+      });
+
+      expect(result.current.pendingCount).toBe(999);
+
+      // Move left should clamp to start
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(textarea.selectionStart).toBe(0);
+      expect(result.current.pendingCount).toBeNull();
+    });
+
+    it("count clears when entering command mode", () => {
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+      expect(result.current.pendingCount).toBe(5);
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+
+      expect(result.current.mode).toBe("command");
+      expect(result.current.pendingCount).toBeNull();
+    });
+
+    it("count does not apply to 0 movement (0 is always line start)", () => {
+      textarea.value = "    Hello, world!";
+      textarea.selectionStart = 10;
+      textarea.selectionEnd = 10;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Start a count, then press 0
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("5"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("0"));
+      });
+
+      // Should have count 50 now, not moved
+      expect(result.current.pendingCount).toBe(50);
+      expect(textarea.selectionStart).toBe(10);
+
+      // Now press h to use the count
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("h"));
+      });
+
+      expect(textarea.selectionStart).toBe(0); // Clamped from 10-50
+      expect(result.current.pendingCount).toBeNull();
+    });
+
+    it("undo does not use count (just undoes once)", () => {
+      textarea.value = "Hello";
+      textarea.selectionStart = 0;
+      textarea.selectionEnd = 0;
+
+      const { result } = renderHook(() => useViMode(getOptionsWithTextarea()));
+
+      // Delete two characters separately to have two undo states
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+      expect(textarea.value).toBe("ello");
+
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+      expect(textarea.value).toBe("llo");
+
+      // Try 2u - should only undo once (count ignored for u in our impl)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("2"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("u"));
+      });
+
+      // Should only undo once
+      expect(textarea.value).toBe("ello");
+    });
+  });
+
+  /**
+   * Ex Command Execution Tests
+   *
+   * Tests for ex commands (:w, :wq, :q, :q!) that control save and exit.
+   *
+   * @see REQ-15: :w saves file, remains in Pair Writing
+   * @see REQ-16: :wq saves file and exits Pair Writing
+   * @see REQ-17: :q exits if no unsaved changes; shows confirmation dialog if unsaved
+   * @see REQ-18: :q! exits without saving (discards changes)
+   */
+  describe("ex command execution", () => {
+    it(":w calls onSave callback", () => {
+      let saveCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          saveCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :w
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(saveCalled).toBe(true);
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it(":w does not call onExit", () => {
+      let exitCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {},
+        onExit: () => {
+          exitCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :w
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(exitCalled).toBe(false);
+    });
+
+    it(":wq calls onSave then onExit", () => {
+      const callOrder: string[] = [];
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          callOrder.push("save");
+        },
+        onExit: () => {
+          callOrder.push("exit");
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :wq
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(callOrder).toEqual(["save", "exit"]);
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it(":x is alias for :wq (calls onSave then onExit)", () => {
+      const callOrder: string[] = [];
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          callOrder.push("save");
+        },
+        onExit: () => {
+          callOrder.push("exit");
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :x
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("x"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(callOrder).toEqual(["save", "exit"]);
+    });
+
+    it(":q calls onQuitWithUnsaved (parent handles unsaved check)", () => {
+      let quitWithUnsavedCalled = false;
+      let exitCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onQuitWithUnsaved: () => {
+          quitWithUnsavedCalled = true;
+        },
+        onExit: () => {
+          exitCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :q
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(quitWithUnsavedCalled).toBe(true);
+      expect(exitCalled).toBe(false); // :q does NOT call onExit directly
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it(":q! calls onExit directly (force quit)", () => {
+      let exitCalled = false;
+      let quitWithUnsavedCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onExit: () => {
+          exitCalled = true;
+        },
+        onQuitWithUnsaved: () => {
+          quitWithUnsavedCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :q!
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("!"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(exitCalled).toBe(true);
+      expect(quitWithUnsavedCalled).toBe(false); // :q! skips the unsaved check
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it("unknown command is silently ignored", () => {
+      let saveCalled = false;
+      let exitCalled = false;
+      let quitWithUnsavedCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          saveCalled = true;
+        },
+        onExit: () => {
+          exitCalled = true;
+        },
+        onQuitWithUnsaved: () => {
+          quitWithUnsavedCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type an unknown command
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("f"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("o"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(saveCalled).toBe(false);
+      expect(exitCalled).toBe(false);
+      expect(quitWithUnsavedCalled).toBe(false);
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it("empty command is silently ignored", () => {
+      let saveCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          saveCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and immediately press Enter (empty command)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(saveCalled).toBe(false);
+      expect(result.current.mode).toBe("normal");
+    });
+
+    it("command with leading/trailing whitespace is trimmed", () => {
+      let saveCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          saveCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type " w " (with spaces)
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(" "));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(" "));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(saveCalled).toBe(true);
+    });
+
+    it("Escape cancels command mode without executing", () => {
+      let saveCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          saveCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :w
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      // Press Escape instead of Enter
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Escape"));
+      });
+
+      expect(saveCalled).toBe(false);
+      expect(result.current.mode).toBe("normal");
+      expect(result.current.commandBuffer).toBe("");
+    });
+
+    it("Ctrl+C cancels command mode without executing", () => {
+      let saveCalled = false;
+      const options: UseViModeOptions = {
+        enabled: true,
+        onSave: () => {
+          saveCalled = true;
+        },
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and type :w
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      // Press Ctrl+C instead of Enter
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("c", { ctrlKey: true }));
+      });
+
+      expect(saveCalled).toBe(false);
+      expect(result.current.mode).toBe("normal");
+      expect(result.current.commandBuffer).toBe("");
+    });
+
+    it("callbacks are optional (no crash when undefined)", () => {
+      const options: UseViModeOptions = {
+        enabled: true,
+        // No callbacks defined
+      };
+
+      const { result } = renderHook(() => useViMode(options));
+
+      // Enter command mode and execute various commands
+      // Should not throw even without callbacks
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(result.current.mode).toBe("normal");
+
+      // Try :wq
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("w"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(result.current.mode).toBe("normal");
+
+      // Try :q
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(result.current.mode).toBe("normal");
+
+      // Try :q!
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent(":"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("q"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("!"));
+      });
+      act(() => {
+        result.current.handleKeyDown(createKeyEvent("Enter"));
+      });
+
+      expect(result.current.mode).toBe("normal");
+    });
+  });
+});
diff --git a/frontend/src/hooks/__tests__/useWebSocket.test.ts b/frontend/src/hooks/__tests__/useWebSocket.test.ts
index 357b6c6f..90f28385 100644
--- a/frontend/src/hooks/__tests__/useWebSocket.test.ts
+++ b/frontend/src/hooks/__tests__/useWebSocket.test.ts
@@ -265,6 +265,7 @@ describe("useWebSocket", () => {
             badges: [],
             order: 999999,
             cardsEnabled: true,
+      viMode: false,
           },
         ],
       };
diff --git a/frontend/src/hooks/useHasKeyboard.test.ts b/frontend/src/hooks/useHasKeyboard.test.ts
new file mode 100644
index 00000000..74e97a85
--- /dev/null
+++ b/frontend/src/hooks/useHasKeyboard.test.ts
@@ -0,0 +1,97 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { detectKeyboard } from "./useHasKeyboard";
+
+describe("detectKeyboard", () => {
+  // Store original values to restore after each test
+  let originalMatchMedia: typeof window.matchMedia;
+  let originalMaxTouchPoints: number;
+
+  beforeEach(() => {
+    originalMatchMedia = window.matchMedia;
+    originalMaxTouchPoints = navigator.maxTouchPoints;
+  });
+
+  afterEach(() => {
+    window.matchMedia = originalMatchMedia;
+    Object.defineProperty(navigator, "maxTouchPoints", {
+      value: originalMaxTouchPoints,
+      configurable: true,
+    });
+  });
+
+  function mockMatchMedia(matches: boolean) {
+    window.matchMedia = ((query: string) => ({
+      matches: query === "(pointer: fine)" ? matches : false,
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => true,
+    })) as typeof window.matchMedia;
+  }
+
+  function mockMaxTouchPoints(value: number) {
+    Object.defineProperty(navigator, "maxTouchPoints", {
+      value,
+      configurable: true,
+    });
+  }
+
+  describe("desktop with mouse/trackpad", () => {
+    test("returns true when fine pointer detected", () => {
+      mockMatchMedia(true);
+      mockMaxTouchPoints(0);
+
+      expect(detectKeyboard()).toBe(true);
+    });
+
+    test("returns true when fine pointer detected even with touch support", () => {
+      // Laptop with touchscreen: has fine pointer AND touch
+      mockMatchMedia(true);
+      mockMaxTouchPoints(10);
+
+      expect(detectKeyboard()).toBe(true);
+    });
+  });
+
+  describe("keyboard-only device", () => {
+    test("returns true when no touch points available", () => {
+      mockMatchMedia(false);
+      mockMaxTouchPoints(0);
+
+      expect(detectKeyboard()).toBe(true);
+    });
+  });
+
+  describe("touch-only device", () => {
+    test("returns false when coarse pointer and touch points present", () => {
+      // Phone or tablet without keyboard
+      mockMatchMedia(false);
+      mockMaxTouchPoints(5);
+
+      expect(detectKeyboard()).toBe(false);
+    });
+
+    test("returns false with high touch point count", () => {
+      // Typical mobile device
+      mockMatchMedia(false);
+      mockMaxTouchPoints(10);
+
+      expect(detectKeyboard()).toBe(false);
+    });
+  });
+
+  describe("error handling", () => {
+    test("returns true when matchMedia throws", () => {
+      window.matchMedia = () => {
+        throw new Error("Not supported");
+      };
+      mockMaxTouchPoints(5);
+
+      // Should not throw, should return true as safe fallback
+      expect(detectKeyboard()).toBe(true);
+    });
+  });
+});
diff --git a/frontend/src/hooks/useHasKeyboard.ts b/frontend/src/hooks/useHasKeyboard.ts
new file mode 100644
index 00000000..1b1cde0e
--- /dev/null
+++ b/frontend/src/hooks/useHasKeyboard.ts
@@ -0,0 +1,53 @@
+/**
+ * Hook to detect physical keyboard presence.
+ *
+ * Uses two heuristics:
+ * 1. `matchMedia('(pointer: fine)')` - true for mouse/trackpad (implies desktop with keyboard)
+ * 2. `navigator.maxTouchPoints === 0` - no touch capability (implies keyboard-only device)
+ *
+ * If either condition is true, we assume a keyboard is present.
+ * If detection fails or is uncertain, returns true (safe fallback: assume keyboard exists).
+ *
+ * This is not reactive; keyboard presence doesn't change mid-session.
+ */
+
+/**
+ * Detect keyboard presence. Exported for testing.
+ */
+export function detectKeyboard(): boolean {
+  // Server-side or unusual environment: assume keyboard exists
+  if (typeof window === "undefined") {
+    return true;
+  }
+
+  try {
+    // Fine pointer (mouse/trackpad) implies desktop with keyboard
+    const hasFinePointer = window.matchMedia("(pointer: fine)").matches;
+    if (hasFinePointer) {
+      return true;
+    }
+
+    // No touch capability implies keyboard-only device
+    const noTouchPoints = navigator.maxTouchPoints === 0;
+    if (noTouchPoints) {
+      return true;
+    }
+
+    // Touch-only device (no fine pointer, has touch points)
+    return false;
+  } catch {
+    // If detection fails, assume keyboard exists (safe fallback)
+    return true;
+  }
+}
+
+/**
+ * React hook that returns whether a physical keyboard is likely present.
+ *
+ * Used to enable/disable vi mode: vi mode requires a keyboard and is
+ * disabled on touch-only devices where it would be unusable.
+ */
+export function useHasKeyboard(): boolean {
+  // Detection happens once; result is stable for the session
+  return detectKeyboard();
+}
diff --git a/frontend/src/hooks/useViCursor.ts b/frontend/src/hooks/useViCursor.ts
new file mode 100644
index 00000000..33d0fe0a
--- /dev/null
+++ b/frontend/src/hooks/useViCursor.ts
@@ -0,0 +1,270 @@
+/**
+ * useViCursor Hook - Vi Mode Block Cursor Position
+ *
+ * Calculates pixel position for the block cursor overlay in vi normal mode
+ * using the mirror element technique. A hidden div copies the textarea's
+ * styling and content to measure where the cursor should appear.
+ *
+ * @see .lore/plans/vi-mode-pair-writing.md (TD-10)
+ * @see .lore/research/vi-mode-implementation.md (Cursor Rendering Research)
+ */
+
+import { useState, useEffect, useCallback, useRef } from "react";
+import type { ViMode } from "./useViMode";
+
+export interface UseViCursorOptions {
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+  cursorPosition: number; // selectionStart
+  mode: ViMode;
+  enabled: boolean;
+}
+
+export interface CursorPosition {
+  top: number;
+  left: number;
+  height: number;
+}
+
+export interface UseViCursorResult {
+  cursorStyle: React.CSSProperties; // position for overlay
+  showOverlay: boolean; // true in normal/command mode
+}
+
+/**
+ * CSS properties that must be copied from textarea to mirror element
+ * for accurate position calculation.
+ */
+const MIRROR_STYLE_PROPERTIES = [
+  "fontFamily",
+  "fontSize",
+  "fontWeight",
+  "fontStyle",
+  "letterSpacing",
+  "lineHeight",
+  "textTransform",
+  "wordWrap",
+  "wordSpacing",
+  "whiteSpace",
+  "overflowWrap",
+  "tabSize",
+  "padding",
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "borderWidth",
+  "borderTopWidth",
+  "borderRightWidth",
+  "borderBottomWidth",
+  "borderLeftWidth",
+  "boxSizing",
+  "width",
+] as const;
+
+/**
+ * Creates a mirror element for measuring cursor position.
+ * The mirror copies the textarea's styling so text wrapping matches.
+ */
+function createMirrorElement(): HTMLDivElement {
+  const mirror = document.createElement("div");
+  mirror.style.position = "absolute";
+  mirror.style.visibility = "hidden";
+  mirror.style.whiteSpace = "pre-wrap";
+  mirror.style.wordWrap = "break-word";
+  mirror.style.overflow = "hidden";
+  // Position off-screen
+  mirror.style.left = "-9999px";
+  mirror.style.top = "-9999px";
+  return mirror;
+}
+
+/**
+ * Converts camelCase to kebab-case for CSS property names.
+ */
+function toKebabCase(str: string): string {
+  return str.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+
+/**
+ * Copies relevant CSS properties from textarea to mirror element.
+ */
+function copyTextareaStyles(
+  textarea: HTMLTextAreaElement,
+  mirror: HTMLDivElement
+): void {
+  const computed = window.getComputedStyle(textarea);
+
+  for (const prop of MIRROR_STYLE_PROPERTIES) {
+    const kebabProp = toKebabCase(prop);
+    const value = computed.getPropertyValue(kebabProp);
+    mirror.style.setProperty(kebabProp, value);
+  }
+}
+
+/**
+ * Calculates cursor pixel position using the mirror element technique.
+ *
+ * Algorithm:
+ * 1. Create off-screen div with identical styling to textarea
+ * 2. Split content at cursor position
+ * 3. Insert span marker between text nodes
+ * 4. Measure span's position relative to the mirror
+ * 5. Account for textarea scroll offset
+ */
+export function calculateCursorPosition(
+  textarea: HTMLTextAreaElement,
+  cursorPos: number
+): CursorPosition {
+  // Create and configure mirror
+  const mirror = createMirrorElement();
+  copyTextareaStyles(textarea, mirror);
+  document.body.appendChild(mirror);
+
+  try {
+    // Split text at cursor position
+    const value = textarea.value;
+    const textBefore = value.substring(0, cursorPos);
+    const charAtCursor = value.charAt(cursorPos);
+
+    // Build mirror content using safe DOM methods
+    // Use a span to mark cursor position
+    const cursorSpan = document.createElement("span");
+    // Use the actual character at cursor, or non-breaking space if empty/newline
+    cursorSpan.textContent =
+      charAtCursor && charAtCursor !== "\n" ? charAtCursor : "\u00A0";
+    cursorSpan.style.display = "inline";
+
+    mirror.textContent = "";
+
+    // Handle the text before cursor, preserving whitespace
+    if (textBefore) {
+      // Use createTextNode to preserve whitespace properly
+      const beforeNode = document.createTextNode(textBefore);
+      mirror.appendChild(beforeNode);
+    }
+    mirror.appendChild(cursorSpan);
+
+    // Get positions - measure span relative to mirror, not viewport
+    const mirrorRect = mirror.getBoundingClientRect();
+    const spanRect = cursorSpan.getBoundingClientRect();
+
+    // Calculate position relative to mirror (which has same styling as textarea)
+    // Then account for scroll offset
+    const top = spanRect.top - mirrorRect.top - textarea.scrollTop;
+    const left = spanRect.left - mirrorRect.left - textarea.scrollLeft;
+
+    // Get line height from computed style for cursor height
+    const computed = window.getComputedStyle(textarea);
+    const lineHeight = parseFloat(computed.lineHeight) || 20;
+
+    return {
+      top,
+      left,
+      height: lineHeight,
+    };
+  } finally {
+    // Clean up mirror element
+    document.body.removeChild(mirror);
+  }
+}
+
+/**
+ * Hook for managing vi mode block cursor overlay position.
+ *
+ * Shows the overlay cursor in normal and command modes (when the native
+ * caret is hidden). Hides it in insert mode to let the native caret show.
+ *
+ * @example
+ * ```tsx
+ * const { cursorStyle, showOverlay } = useViCursor({
+ *   textareaRef,
+ *   cursorPosition: selectionStart,
+ *   mode: viMode,
+ *   enabled: viModeEnabled,
+ * });
+ *
+ * return (
+ *   <>
+ *     <textarea ref={textareaRef} />
+ *     {showOverlay && <div className="vi-cursor" style={cursorStyle} />}
+ *   </>
+ * );
+ * ```
+ */
+export function useViCursor(options: UseViCursorOptions): UseViCursorResult {
+  const { textareaRef, cursorPosition, mode, enabled } = options;
+
+  const [position, setPosition] = useState<CursorPosition>({
+    top: 0,
+    left: 0,
+    height: 20,
+  });
+
+  // Track scroll position to update cursor on scroll
+  const scrollTopRef = useRef(0);
+  const scrollLeftRef = useRef(0);
+
+  // Calculate cursor position
+  const updatePosition = useCallback(() => {
+    const textarea = textareaRef.current;
+    if (!textarea || !enabled) return;
+
+    const newPosition = calculateCursorPosition(textarea, cursorPosition);
+    setPosition(newPosition);
+
+    // Store current scroll for reference
+    scrollTopRef.current = textarea.scrollTop;
+    scrollLeftRef.current = textarea.scrollLeft;
+  }, [textareaRef, cursorPosition, enabled]);
+
+  // Update position when cursor moves
+  useEffect(() => {
+    updatePosition();
+  }, [updatePosition]);
+
+  // Update position on scroll
+  useEffect(() => {
+    const textarea = textareaRef.current;
+    if (!textarea || !enabled) return;
+
+    const handleScroll = () => {
+      // Recalculate position based on new scroll offset
+      const newPosition = calculateCursorPosition(textarea, cursorPosition);
+      setPosition(newPosition);
+    };
+
+    textarea.addEventListener("scroll", handleScroll);
+    return () => {
+      textarea.removeEventListener("scroll", handleScroll);
+    };
+  }, [textareaRef, cursorPosition, enabled]);
+
+  // Also update on window resize (textarea might reflow)
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleResize = () => {
+      updatePosition();
+    };
+
+    window.addEventListener("resize", handleResize);
+    return () => {
+      window.removeEventListener("resize", handleResize);
+    };
+  }, [enabled, updatePosition]);
+
+  // Show overlay in normal and command modes, not in insert mode
+  const showOverlay = enabled && (mode === "normal" || mode === "command");
+
+  // Convert position to CSS style
+  const cursorStyle: React.CSSProperties = {
+    top: position.top,
+    left: position.left,
+    height: position.height,
+  };
+
+  return {
+    cursorStyle,
+    showOverlay,
+  };
+}
diff --git a/frontend/src/hooks/useViMode.ts b/frontend/src/hooks/useViMode.ts
new file mode 100644
index 00000000..fc973ecf
--- /dev/null
+++ b/frontend/src/hooks/useViMode.ts
@@ -0,0 +1,1099 @@
+/**
+ * useViMode Hook - Vi Mode State Machine
+ *
+ * Implements core vi mode state management for the Pair Writing Editor.
+ * Handles mode transitions between normal, insert, and command modes,
+ * cursor movement commands, insert mode entry with cursor positioning,
+ * internal undo stack for the `u` command, delete commands, yank/put,
+ * numeric prefixes for command repetition, and ex command execution.
+ *
+ * @see .lore/plans/vi-mode-pair-writing.md (TD-1, TD-4, TD-6, TD-8, TD-9)
+ * @see REQ-7, REQ-8: Movement commands (h, j, k, l, 0, $)
+ * @see REQ-9: Insert mode entry commands (i, a, A, o, O)
+ * @see REQ-10: Delete commands (x, dd)
+ * @see REQ-11: Yank/put commands (yy, p, P)
+ * @see REQ-12: Undo: u undoes last edit operation
+ * @see REQ-13: Numeric prefixes (e.g., 5j, 3dd, 2x)
+ * @see REQ-15, REQ-16, REQ-17, REQ-18: Ex commands (:w, :wq, :q, :q!)
+ */
+
+import { useState, useCallback } from "react";
+
+export type ViMode = "normal" | "insert" | "command";
+
+/**
+ * Snapshot of editor state for undo functionality.
+ * Captures both content and cursor position to restore both on undo.
+ */
+export interface UndoState {
+  content: string;
+  cursorPosition: number;
+}
+
+/** Maximum number of undo entries to keep. Prevents unbounded memory growth. */
+const MAX_UNDO_STACK_SIZE = 100;
+
+export interface UseViModeOptions {
+  enabled: boolean;
+  textareaRef?: React.RefObject<HTMLTextAreaElement | null>;
+  onSave?: () => void;
+  onExit?: () => void;
+  onQuitWithUnsaved?: () => void;
+  onContentChange?: (content: string) => void;
+}
+
+export interface UseViModeResult {
+  mode: ViMode;
+  handleKeyDown: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
+  commandBuffer: string;
+  pendingCount: number | null;
+  pendingOperator: "d" | "y" | null;
+  clipboard: string | null;
+  /** Current undo stack depth (for debugging/testing) */
+  undoStackSize: number;
+  /** Push current state to undo stack (exposed for external edit operations) */
+  pushUndoState: () => void;
+}
+
+/**
+ * Keys that transition from normal mode to insert mode.
+ * Each key positions the cursor differently before entering insert mode:
+ * - i: Insert at current cursor position
+ * - a: Insert after cursor (append)
+ * - A: Insert at end of line
+ * - o: Open new line below
+ * - O: Open new line above
+ */
+const INSERT_MODE_KEYS = new Set(["i", "a", "A", "o", "O"]);
+
+/**
+ * Movement command keys handled in normal mode.
+ */
+const MOVEMENT_KEYS = new Set(["h", "j", "k", "l", "0", "$"]);
+
+/**
+ * Information about the current line at a given cursor position.
+ */
+export interface LineInfo {
+  /** Zero-based line number */
+  lineNumber: number;
+  /** Index of the first character of this line in the text */
+  lineStart: number;
+  /** Index of the last character of this line (before newline or end of text) */
+  lineEnd: number;
+  /** Current column position within the line */
+  column: number;
+}
+
+/**
+ * Get information about the line at the given cursor position.
+ *
+ * @param text - The full text content
+ * @param position - The cursor position (index into text)
+ * @returns Information about the current line
+ */
+export function getLineInfo(text: string, position: number): LineInfo {
+  // Find line boundaries by scanning for newlines
+  let lineStart = 0;
+  let lineNumber = 0;
+
+  // Find the start of the current line
+  for (let i = 0; i < position; i++) {
+    if (text[i] === "\n") {
+      lineStart = i + 1;
+      lineNumber++;
+    }
+  }
+
+  // Find the end of the current line
+  let lineEnd = text.indexOf("\n", lineStart);
+  if (lineEnd === -1) {
+    lineEnd = text.length;
+  }
+
+  const column = position - lineStart;
+
+  return { lineNumber, lineStart, lineEnd, column };
+}
+
+/**
+ * Count the total number of lines in the text.
+ *
+ * @param text - The full text content
+ * @returns The number of lines (minimum 1)
+ */
+export function getLineCount(text: string): number {
+  if (text.length === 0) return 1;
+  let count = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "\n") count++;
+  }
+  return count;
+}
+
+/**
+ * Get the start and end positions of a specific line.
+ *
+ * @param text - The full text content
+ * @param lineNumber - Zero-based line number
+ * @returns Object with lineStart and lineEnd, or null if line doesn't exist
+ */
+export function getLinePositions(
+  text: string,
+  lineNumber: number
+): { lineStart: number; lineEnd: number } | null {
+  let currentLine = 0;
+  let lineStart = 0;
+
+  for (let i = 0; i <= text.length; i++) {
+    if (currentLine === lineNumber) {
+      // Found the target line, now find its end
+      let lineEnd = text.indexOf("\n", lineStart);
+      if (lineEnd === -1) {
+        lineEnd = text.length;
+      }
+      return { lineStart, lineEnd };
+    }
+    if (i < text.length && text[i] === "\n") {
+      currentLine++;
+      lineStart = i + 1;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Move the cursor to a new position, collapsing any selection.
+ *
+ * @param textarea - The textarea element
+ * @param newPosition - The new cursor position
+ */
+export function moveCursor(
+  textarea: HTMLTextAreaElement,
+  newPosition: number
+): void {
+  const clamped = Math.max(0, Math.min(newPosition, textarea.value.length));
+  textarea.selectionStart = clamped;
+  textarea.selectionEnd = clamped;
+}
+
+/**
+ * Scroll the textarea to ensure the cursor is visible.
+ *
+ * Uses a mirror element technique to calculate the actual pixel position
+ * of the cursor, accounting for text wrapping. Then adjusts scrollTop
+ * if the cursor is outside the visible area.
+ *
+ * @param textarea - The textarea element
+ */
+export function scrollCursorIntoView(textarea: HTMLTextAreaElement): void {
+  const pos = textarea.selectionStart;
+  const text = textarea.value;
+
+  // Get computed styles
+  const computed = window.getComputedStyle(textarea);
+  const lineHeight = parseFloat(computed.lineHeight) || 20;
+
+  // Create mirror element to measure actual cursor position with wrapping
+  const mirror = document.createElement("div");
+  mirror.style.position = "absolute";
+  mirror.style.visibility = "hidden";
+  mirror.style.whiteSpace = "pre-wrap";
+  mirror.style.wordWrap = "break-word";
+  mirror.style.overflow = "hidden";
+  mirror.style.left = "-9999px";
+  mirror.style.top = "-9999px";
+
+  // Copy relevant styles from textarea
+  const stylesToCopy = [
+    "font-family", "font-size", "font-weight", "line-height",
+    "padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
+    "border-width", "box-sizing", "width", "letter-spacing", "word-spacing"
+  ];
+  for (const prop of stylesToCopy) {
+    mirror.style.setProperty(prop, computed.getPropertyValue(prop));
+  }
+
+  document.body.appendChild(mirror);
+
+  try {
+    // Insert text up to cursor with a marker span
+    const textBefore = text.substring(0, pos);
+    const cursorSpan = document.createElement("span");
+    cursorSpan.textContent = "\u00A0"; // Non-breaking space as marker
+
+    mirror.textContent = "";
+    if (textBefore) {
+      mirror.appendChild(document.createTextNode(textBefore));
+    }
+    mirror.appendChild(cursorSpan);
+
+    // Measure position relative to mirror
+    const mirrorRect = mirror.getBoundingClientRect();
+    const spanRect = cursorSpan.getBoundingClientRect();
+
+    // Cursor position relative to textarea content (not viewport)
+    const cursorTop = spanRect.top - mirrorRect.top;
+    const cursorBottom = cursorTop + lineHeight;
+
+    // Get the visible area
+    const visibleTop = textarea.scrollTop;
+    const visibleBottom = visibleTop + textarea.clientHeight;
+
+    // Margin to start scrolling before cursor goes off-screen
+    const scrollMargin = lineHeight * 2;
+
+    // Scroll if cursor is approaching edge of visible area
+    if (cursorTop < visibleTop + scrollMargin) {
+      // Cursor is approaching top - scroll to keep margin above cursor
+      textarea.scrollTop = Math.max(0, cursorTop - scrollMargin);
+    } else if (cursorBottom > visibleBottom - scrollMargin) {
+      // Cursor is approaching bottom - scroll to keep margin below cursor
+      textarea.scrollTop = cursorBottom - textarea.clientHeight + scrollMargin;
+    }
+  } finally {
+    document.body.removeChild(mirror);
+  }
+}
+
+export function useViMode(options: UseViModeOptions): UseViModeResult {
+  const { enabled, textareaRef, onContentChange, onSave, onExit, onQuitWithUnsaved } = options;
+
+  const [mode, setMode] = useState<ViMode>("normal");
+  const [commandBuffer, setCommandBuffer] = useState("");
+
+  // Pending operator for multi-key commands like 'dd', 'yy'
+  // Using state so changes trigger re-renders and can be observed by tests
+  const [pendingOperator, setPendingOperator] = useState<"d" | "y" | null>(
+    null
+  );
+
+  // Pending count for numeric prefixes (e.g., 5j, 3dd)
+  // Using state so changes trigger re-renders and can be observed by tests
+  const [pendingCount, setPendingCount] = useState<number | null>(null);
+
+  // Internal clipboard for yank/put operations (REQ-20, REQ-21)
+  // Using state so clipboard is observable in tests and persists within session
+  const [clipboard, setClipboard] = useState<string | null>(null);
+
+  // Undo stack: stores snapshots of content + cursor position
+  // Using state instead of ref so that undoStackSize triggers re-renders
+  const [undoStack, setUndoStack] = useState<UndoState[]>([]);
+
+  /**
+   * Push current editor state to undo stack.
+   * Called before any edit operation to enable undoing.
+   * Stack is capped at MAX_UNDO_STACK_SIZE to prevent memory issues.
+   */
+  const pushUndoState = useCallback(() => {
+    const textarea = textareaRef?.current;
+    if (!textarea) return;
+
+    const state: UndoState = {
+      content: textarea.value,
+      cursorPosition: textarea.selectionStart,
+    };
+
+    setUndoStack((prev) => {
+      const newStack = [...prev, state];
+      // Enforce stack size limit by removing oldest entries
+      if (newStack.length > MAX_UNDO_STACK_SIZE) {
+        return newStack.slice(-MAX_UNDO_STACK_SIZE);
+      }
+      return newStack;
+    });
+  }, [textareaRef]);
+
+  /**
+   * Pop and restore the most recent undo state.
+   * Does nothing if stack is empty or textarea is unavailable.
+   */
+  const popUndoState = useCallback((): void => {
+    const textarea = textareaRef?.current;
+    if (!textarea) return;
+
+    setUndoStack((prev) => {
+      if (prev.length === 0) return prev;
+
+      const newStack = prev.slice(0, -1);
+      const state = prev[prev.length - 1];
+
+      textarea.value = state.content;
+      moveCursor(textarea, state.cursorPosition);
+      onContentChange?.(state.content);
+
+      return newStack;
+    });
+  }, [textareaRef, onContentChange]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+      // When disabled, do nothing and let all keys through naturally
+      if (!enabled) {
+        return;
+      }
+
+      const { key } = e;
+      const textarea = textareaRef?.current ?? null;
+
+      switch (mode) {
+        case "normal":
+          handleNormalModeKey(
+            e,
+            key,
+            setMode,
+            setCommandBuffer,
+            textarea,
+            onContentChange,
+            pushUndoState,
+            popUndoState,
+            pendingOperator,
+            setPendingOperator,
+            clipboard,
+            setClipboard,
+            pendingCount,
+            setPendingCount
+          );
+          break;
+
+        case "insert":
+          handleInsertModeKey(e, key, setMode);
+          break;
+
+        case "command":
+          handleCommandModeKey(e, key, setMode, commandBuffer, setCommandBuffer, {
+            onSave,
+            onExit,
+            onQuitWithUnsaved,
+          });
+          break;
+      }
+    },
+    [
+      enabled,
+      mode,
+      textareaRef,
+      onContentChange,
+      pushUndoState,
+      popUndoState,
+      pendingOperator,
+      clipboard,
+      pendingCount,
+      commandBuffer,
+      onSave,
+      onExit,
+      onQuitWithUnsaved,
+    ]
+  );
+
+  return {
+    mode,
+    handleKeyDown,
+    commandBuffer,
+    pendingCount,
+    pendingOperator,
+    clipboard,
+    undoStackSize: undoStack.length,
+    pushUndoState,
+  };
+}
+
+/**
+ * Handle keystrokes in normal mode.
+ * In normal mode, we intercept all keys and prevent default to stop character insertion.
+ */
+function handleNormalModeKey(
+  e: React.KeyboardEvent<HTMLTextAreaElement>,
+  key: string,
+  setMode: React.Dispatch<React.SetStateAction<ViMode>>,
+  setCommandBuffer: React.Dispatch<React.SetStateAction<string>>,
+  textarea: HTMLTextAreaElement | null,
+  onContentChange?: (content: string) => void,
+  pushUndoState?: () => void,
+  popUndoState?: () => void,
+  pendingOperator?: "d" | "y" | null,
+  setPendingOperator?: React.Dispatch<React.SetStateAction<"d" | "y" | null>>,
+  clipboard?: string | null,
+  setClipboard?: React.Dispatch<React.SetStateAction<string | null>>,
+  pendingCount?: number | null,
+  setPendingCount?: React.Dispatch<React.SetStateAction<number | null>>
+): void {
+  // Handle digit accumulation for numeric prefixes (e.g., 5j, 10dd)
+  // Digits 1-9 start a count; digit 0 extends when count pending (otherwise line start)
+  if (/[1-9]/.test(key) && pendingCount === null) {
+    e.preventDefault();
+    setPendingCount?.(parseInt(key));
+    return;
+  }
+  if (/[0-9]/.test(key) && pendingCount != null) {
+    e.preventDefault();
+    setPendingCount?.(pendingCount * 10 + parseInt(key));
+    return;
+  }
+
+  // Get the effective count for this command (default to 1)
+  const count = pendingCount ?? 1;
+
+  // Helper to clear pending count after command execution
+  const clearPendingCount = () => setPendingCount?.(null);
+  // Handle 'd' key for delete operations (dd to delete line)
+  if (key === "d" && textarea) {
+    e.preventDefault();
+    if (pendingOperator === "d") {
+      // Second 'd' pressed - execute dd (delete line) with count
+      setPendingOperator?.(null);
+      clearPendingCount();
+      executeDeleteLine(textarea, onContentChange, pushUndoState, count);
+    } else {
+      // First 'd' pressed - set pending operator
+      setPendingOperator?.("d");
+    }
+    return;
+  }
+
+  // Handle 'y' key for yank operations (yy to yank line)
+  if (key === "y" && textarea) {
+    e.preventDefault();
+    if (pendingOperator === "y") {
+      // Second 'y' pressed - execute yy (yank line) with count
+      setPendingOperator?.(null);
+      clearPendingCount();
+      executeYankLine(textarea, setClipboard, count);
+    } else {
+      // First 'y' pressed - set pending operator
+      setPendingOperator?.("y");
+    }
+    return;
+  }
+
+  // Handle 'p' key for paste after current line
+  if (key === "p" && textarea) {
+    e.preventDefault();
+    clearPendingCount();
+    executePasteAfter(textarea, clipboard, onContentChange, pushUndoState);
+    return;
+  }
+
+  // Handle 'P' key for paste before current line
+  if (key === "P" && textarea) {
+    e.preventDefault();
+    clearPendingCount();
+    executePasteBefore(textarea, clipboard, onContentChange, pushUndoState);
+    return;
+  }
+
+  // Any other key clears the pending operator (unless it's a modifier key)
+  // Note: pending count is cleared when commands execute, not here
+  if (setPendingOperator && key.length === 1 && key !== "d" && key !== "y") {
+    setPendingOperator(null);
+  }
+
+  // Transition to insert mode with cursor positioning
+  if (INSERT_MODE_KEYS.has(key)) {
+    e.preventDefault();
+    clearPendingCount();
+    if (textarea) {
+      // Snapshot state before entering insert mode.
+      // This batches all insert mode changes into a single undo entry.
+      pushUndoState?.();
+      executeInsertModeEntry(key, textarea, onContentChange);
+    }
+    setMode("insert");
+    return;
+  }
+
+  // Transition to command mode
+  if (key === ":") {
+    e.preventDefault();
+    clearPendingCount();
+    setMode("command");
+    setCommandBuffer("");
+    return;
+  }
+
+  // Handle movement commands if we have a textarea
+  if (MOVEMENT_KEYS.has(key) && textarea) {
+    e.preventDefault();
+    clearPendingCount();
+    executeMovementCommand(key, textarea, count);
+    return;
+  }
+
+  // Handle undo command
+  if (key === "u") {
+    e.preventDefault();
+    clearPendingCount();
+    popUndoState?.();
+    return;
+  }
+
+  // Handle Escape in normal mode: cancel pending operator and count
+  // This provides a way to cancel partially-entered commands like "d" waiting for second key
+  if (key === "Escape") {
+    e.preventDefault();
+    setPendingOperator?.(null);
+    setPendingCount?.(null);
+    return;
+  }
+
+  // Handle delete character command (x)
+  if (key === "x" && textarea) {
+    e.preventDefault();
+    clearPendingCount();
+    executeDeleteCharacter(textarea, onContentChange, pushUndoState, count);
+    return;
+  }
+
+  // In normal mode, prevent default for all single-character keys to stop insertion
+  // Allow modifier keys and navigation keys to work naturally
+  if (key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+    e.preventDefault();
+  }
+}
+
+/**
+ * Execute a movement command on the textarea.
+ *
+ * @param key - The movement key pressed
+ * @param textarea - The textarea element to manipulate
+ * @param count - Number of times to repeat the movement (default 1)
+ */
+function executeMovementCommand(
+  key: string,
+  textarea: HTMLTextAreaElement,
+  count: number = 1
+): void {
+  const text = textarea.value;
+
+  switch (key) {
+    case "h": {
+      // Move left count characters, clamp at 0
+      const pos = textarea.selectionStart;
+      moveCursor(textarea, pos - count);
+      break;
+    }
+    case "l": {
+      // Move right count characters, clamp at end
+      const pos = textarea.selectionStart;
+      moveCursor(textarea, pos + count);
+      break;
+    }
+    case "j": {
+      // Move down count lines, trying to maintain column position
+      for (let i = 0; i < count; i++) {
+        const pos = textarea.selectionStart;
+        const currentLine = getLineInfo(text, pos);
+        const totalLines = getLineCount(text);
+
+        // If already on the last line, stop
+        if (currentLine.lineNumber >= totalLines - 1) {
+          break;
+        }
+
+        const nextLinePositions = getLinePositions(
+          text,
+          currentLine.lineNumber + 1
+        );
+        if (!nextLinePositions) break;
+
+        // Try to maintain column position, but clamp to next line's length
+        const nextLineLength =
+          nextLinePositions.lineEnd - nextLinePositions.lineStart;
+        const targetColumn = Math.min(currentLine.column, nextLineLength);
+        moveCursor(textarea, nextLinePositions.lineStart + targetColumn);
+      }
+      // Ensure cursor stays visible after vertical movement
+      scrollCursorIntoView(textarea);
+      break;
+    }
+    case "k": {
+      // Move up count lines, trying to maintain column position
+      for (let i = 0; i < count; i++) {
+        const pos = textarea.selectionStart;
+        const currentLine = getLineInfo(text, pos);
+
+        // If already on the first line, stop
+        if (currentLine.lineNumber === 0) {
+          break;
+        }
+
+        const prevLinePositions = getLinePositions(
+          text,
+          currentLine.lineNumber - 1
+        );
+        if (!prevLinePositions) break;
+
+        // Try to maintain column position, but clamp to previous line's length
+        const prevLineLength =
+          prevLinePositions.lineEnd - prevLinePositions.lineStart;
+        const targetColumn = Math.min(currentLine.column, prevLineLength);
+        moveCursor(textarea, prevLinePositions.lineStart + targetColumn);
+      }
+      // Ensure cursor stays visible after vertical movement
+      scrollCursorIntoView(textarea);
+      break;
+    }
+    case "0": {
+      // Move to start of current line (count is ignored for 0)
+      const pos = textarea.selectionStart;
+      const currentLine = getLineInfo(text, pos);
+      moveCursor(textarea, currentLine.lineStart);
+      break;
+    }
+    case "$": {
+      // Move to end of current line (count is ignored for $)
+      const pos = textarea.selectionStart;
+      const currentLine = getLineInfo(text, pos);
+      moveCursor(textarea, currentLine.lineEnd);
+      break;
+    }
+  }
+}
+
+/**
+ * Execute the 'x' command: delete characters at the cursor position.
+ *
+ * In vim, 'x' deletes the character under the cursor. With a count (e.g., 5x),
+ * it deletes count characters. If the cursor is at the end of a line (past
+ * the last character) or on an empty line, nothing happens. After deletion,
+ * the cursor stays at the same position, or moves left if it would be past
+ * the end of the text.
+ *
+ * @param textarea - The textarea element to manipulate
+ * @param onContentChange - Optional callback for content changes
+ * @param pushUndoState - Optional callback to push undo state before editing
+ * @param count - Number of characters to delete (default 1)
+ */
+function executeDeleteCharacter(
+  textarea: HTMLTextAreaElement,
+  onContentChange?: (content: string) => void,
+  pushUndoState?: () => void,
+  count: number = 1
+): void {
+  const text = textarea.value;
+  const pos = textarea.selectionStart;
+
+  // Nothing to delete if at end of text or text is empty
+  if (pos >= text.length || text.length === 0) {
+    return;
+  }
+
+  // Push undo state before making changes
+  pushUndoState?.();
+
+  // Delete count characters at cursor position, clamped to available text
+  const deleteCount = Math.min(count, text.length - pos);
+  const newText = text.slice(0, pos) + text.slice(pos + deleteCount);
+  textarea.value = newText;
+
+  // Keep cursor at same position, but clamp if needed
+  moveCursor(textarea, Math.min(pos, newText.length));
+
+  // Notify parent of content change
+  onContentChange?.(newText);
+}
+
+/**
+ * Execute the 'dd' command: delete lines starting from the current line.
+ *
+ * Behavior:
+ * - Deletes count lines starting from the cursor's line, including trailing newlines
+ * - If count exceeds available lines, deletes all remaining lines
+ * - If deleting all lines, leaves an empty document
+ * - Cursor moves to the start of the next remaining line, or previous line if at end
+ *
+ * @param textarea - The textarea element to manipulate
+ * @param onContentChange - Optional callback for content changes
+ * @param pushUndoState - Optional callback to push undo state before editing
+ * @param count - Number of lines to delete (default 1)
+ */
+function executeDeleteLine(
+  textarea: HTMLTextAreaElement,
+  onContentChange?: (content: string) => void,
+  pushUndoState?: () => void,
+  count: number = 1
+): void {
+  const text = textarea.value;
+  const pos = textarea.selectionStart;
+
+  // Empty document - nothing to delete
+  if (text.length === 0) {
+    return;
+  }
+
+  // Push undo state before making changes
+  pushUndoState?.();
+
+  const lineInfo = getLineInfo(text, pos);
+  const totalLines = getLineCount(text);
+
+  // Clamp count to available lines from current position
+  const linesToDelete = Math.min(count, totalLines - lineInfo.lineNumber);
+
+  // Calculate the end line (exclusive)
+  const endLineNumber = lineInfo.lineNumber + linesToDelete;
+
+  let deleteStart: number;
+  let deleteEnd: number;
+  let newCursorPos: number;
+
+  if (linesToDelete >= totalLines) {
+    // Deleting all lines - leave empty document
+    deleteStart = 0;
+    deleteEnd = text.length;
+    newCursorPos = 0;
+  } else if (endLineNumber >= totalLines) {
+    // Deleting to end of document - need to delete preceding newline
+    deleteStart = lineInfo.lineStart - (lineInfo.lineNumber > 0 ? 1 : 0);
+    deleteEnd = text.length;
+    // Cursor goes to start of what was the previous line
+    if (lineInfo.lineNumber > 0) {
+      const prevLinePositions = getLinePositions(text, lineInfo.lineNumber - 1);
+      newCursorPos = prevLinePositions ? prevLinePositions.lineStart : 0;
+    } else {
+      newCursorPos = 0;
+    }
+  } else {
+    // Deleting from middle - include trailing newline of last deleted line
+    deleteStart = lineInfo.lineStart;
+    const lastDeletedLine = getLinePositions(text, endLineNumber - 1);
+    deleteEnd = lastDeletedLine ? lastDeletedLine.lineEnd + 1 : text.length;
+    // Cursor stays at the start of the "next" line (which moves up)
+    newCursorPos = deleteStart;
+  }
+
+  const newText = text.slice(0, deleteStart) + text.slice(deleteEnd);
+  textarea.value = newText;
+
+  // Clamp cursor position to valid range
+  moveCursor(textarea, Math.min(newCursorPos, newText.length));
+
+  // Notify parent of content change
+  onContentChange?.(newText);
+}
+
+/**
+ * Execute the 'yy' command: yank (copy) lines starting from the current line.
+ *
+ * When yanking multiple lines, they are joined with newlines. The content is
+ * stored WITHOUT a trailing newline; the newline is added during paste operations.
+ * This matches vim behavior where yanking lines and pasting creates proper new lines.
+ *
+ * @param textarea - The textarea element to read from
+ * @param setClipboard - State setter to store the yanked content
+ * @param count - Number of lines to yank (default 1)
+ */
+function executeYankLine(
+  textarea: HTMLTextAreaElement,
+  setClipboard?: React.Dispatch<React.SetStateAction<string | null>>,
+  count: number = 1
+): void {
+  const text = textarea.value;
+  const pos = textarea.selectionStart;
+
+  const lineInfo = getLineInfo(text, pos);
+  const totalLines = getLineCount(text);
+
+  // Clamp count to available lines from current position
+  const linesToYank = Math.min(count, totalLines - lineInfo.lineNumber);
+
+  // Collect lines
+  const lines: string[] = [];
+  for (let i = 0; i < linesToYank; i++) {
+    const linePositions = getLinePositions(text, lineInfo.lineNumber + i);
+    if (linePositions) {
+      lines.push(text.slice(linePositions.lineStart, linePositions.lineEnd));
+    }
+  }
+
+  // Join lines with newlines (vim behavior for multi-line yank)
+  const yankedContent = lines.join("\n");
+
+  // Store in clipboard
+  setClipboard?.(yankedContent);
+}
+
+/**
+ * Execute the 'p' command: paste clipboard content after the current line.
+ *
+ * Creates a new line below the current line and inserts the clipboard content.
+ * Cursor is positioned at the start of the pasted line.
+ * Does nothing if clipboard is empty.
+ *
+ * @param textarea - The textarea element to manipulate
+ * @param clipboard - The current clipboard content
+ * @param onContentChange - Optional callback for content changes
+ * @param pushUndoState - Optional callback to push undo state before editing
+ */
+function executePasteAfter(
+  textarea: HTMLTextAreaElement,
+  clipboard: string | null | undefined,
+  onContentChange?: (content: string) => void,
+  pushUndoState?: () => void
+): void {
+  // Do nothing if clipboard is empty
+  if (clipboard === null || clipboard === undefined) {
+    return;
+  }
+
+  const text = textarea.value;
+  const pos = textarea.selectionStart;
+
+  // Push undo state before making changes
+  pushUndoState?.();
+
+  const lineInfo = getLineInfo(text, pos);
+
+  // Insert newline + clipboard content after current line end
+  const insertPos = lineInfo.lineEnd;
+  const newText =
+    text.slice(0, insertPos) + "\n" + clipboard + text.slice(insertPos);
+
+  textarea.value = newText;
+
+  // Position cursor at start of pasted line (after the newline)
+  moveCursor(textarea, insertPos + 1);
+
+  // Notify parent of content change
+  onContentChange?.(newText);
+}
+
+/**
+ * Execute the 'P' command: paste clipboard content before the current line.
+ *
+ * Creates a new line above the current line and inserts the clipboard content.
+ * Cursor is positioned at the start of the pasted line.
+ * Does nothing if clipboard is empty.
+ *
+ * @param textarea - The textarea element to manipulate
+ * @param clipboard - The current clipboard content
+ * @param onContentChange - Optional callback for content changes
+ * @param pushUndoState - Optional callback to push undo state before editing
+ */
+function executePasteBefore(
+  textarea: HTMLTextAreaElement,
+  clipboard: string | null | undefined,
+  onContentChange?: (content: string) => void,
+  pushUndoState?: () => void
+): void {
+  // Do nothing if clipboard is empty
+  if (clipboard === null || clipboard === undefined) {
+    return;
+  }
+
+  const text = textarea.value;
+  const pos = textarea.selectionStart;
+
+  // Push undo state before making changes
+  pushUndoState?.();
+
+  const lineInfo = getLineInfo(text, pos);
+
+  // Insert clipboard content + newline before current line start
+  const insertPos = lineInfo.lineStart;
+  const newText =
+    text.slice(0, insertPos) + clipboard + "\n" + text.slice(insertPos);
+
+  textarea.value = newText;
+
+  // Position cursor at start of pasted line (at the insertion point)
+  moveCursor(textarea, insertPos);
+
+  // Notify parent of content change
+  onContentChange?.(newText);
+}
+
+/**
+ * Execute an insert mode entry command, positioning the cursor appropriately.
+ *
+ * Commands:
+ * - `i`: Insert at current cursor position (no cursor movement needed)
+ * - `a`: Insert after current cursor position (move right one character)
+ * - `A`: Insert at end of current line
+ * - `o`: Open new line below current line, position cursor there
+ * - `O`: Open new line above current line, position cursor there
+ *
+ * @param key - The insert mode entry key pressed
+ * @param textarea - The textarea element to manipulate
+ * @param onContentChange - Optional callback for content changes (needed for o/O)
+ */
+function executeInsertModeEntry(
+  key: string,
+  textarea: HTMLTextAreaElement,
+  onContentChange?: (content: string) => void
+): void {
+  const text = textarea.value;
+  const pos = textarea.selectionStart;
+
+  switch (key) {
+    case "i": {
+      // Insert at current position - no cursor movement needed
+      // Cursor stays where it is
+      break;
+    }
+    case "a": {
+      // Insert after current position - move right one character
+      // Clamp at end of text (can position at the very end for appending)
+      const newPos = Math.min(pos + 1, text.length);
+      moveCursor(textarea, newPos);
+      break;
+    }
+    case "A": {
+      // Insert at end of current line
+      const currentLine = getLineInfo(text, pos);
+      moveCursor(textarea, currentLine.lineEnd);
+      break;
+    }
+    case "o": {
+      // Open new line below current line
+      const currentLine = getLineInfo(text, pos);
+      // Insert newline at end of current line
+      const insertPos = currentLine.lineEnd;
+      const newText =
+        text.slice(0, insertPos) + "\n" + text.slice(insertPos);
+      textarea.value = newText;
+      // Position cursor at start of new line (after the newline we just inserted)
+      moveCursor(textarea, insertPos + 1);
+      // Notify parent of content change
+      onContentChange?.(newText);
+      break;
+    }
+    case "O": {
+      // Open new line above current line
+      const currentLine = getLineInfo(text, pos);
+      // Insert newline at start of current line
+      const insertPos = currentLine.lineStart;
+      const newText =
+        text.slice(0, insertPos) + "\n" + text.slice(insertPos);
+      textarea.value = newText;
+      // Position cursor at the new blank line (which is now at lineStart)
+      moveCursor(textarea, insertPos);
+      // Notify parent of content change
+      onContentChange?.(newText);
+      break;
+    }
+  }
+}
+
+/**
+ * Handle keystrokes in insert mode.
+ * In insert mode, we only intercept Escape to return to normal mode.
+ * All other keys pass through naturally for text editing.
+ */
+function handleInsertModeKey(
+  e: React.KeyboardEvent<HTMLTextAreaElement>,
+  key: string,
+  setMode: React.Dispatch<React.SetStateAction<ViMode>>
+): void {
+  if (key === "Escape") {
+    e.preventDefault();
+    setMode("normal");
+  }
+  // All other keys pass through naturally
+}
+
+/**
+ * Callbacks for ex command execution.
+ */
+interface ExCommandCallbacks {
+  onSave?: () => void;
+  onExit?: () => void;
+  onQuitWithUnsaved?: () => void;
+}
+
+/**
+ * Execute an ex command (commands entered after ':' in command mode).
+ *
+ * Supported commands:
+ * - `:w` - Save file, remain in Pair Writing (REQ-15)
+ * - `:wq` or `:x` - Save file and exit Pair Writing (REQ-16)
+ * - `:q` - Exit if no unsaved changes; triggers confirmation if unsaved (REQ-17)
+ * - `:q!` - Exit without saving, discarding changes (REQ-18)
+ *
+ * Unknown commands are silently ignored (no-op).
+ *
+ * @param command - The command string (without the leading ':')
+ * @param callbacks - Callbacks for save/exit operations
+ */
+export function executeExCommand(
+  command: string,
+  callbacks: ExCommandCallbacks
+): void {
+  const { onSave, onExit, onQuitWithUnsaved } = callbacks;
+  const trimmed = command.trim();
+
+  switch (trimmed) {
+    case "w":
+      // :w - Save file, remain in Pair Writing
+      onSave?.();
+      break;
+
+    case "wq":
+    case "x":
+      // :wq or :x - Save file and exit Pair Writing
+      onSave?.();
+      onExit?.();
+      break;
+
+    case "q":
+      // :q - Exit if no unsaved changes; parent handles the check
+      // We call onQuitWithUnsaved and let the parent decide whether to show
+      // a confirmation dialog or exit directly based on unsaved state
+      onQuitWithUnsaved?.();
+      break;
+
+    case "q!":
+      // :q! - Exit without saving (force quit)
+      onExit?.();
+      break;
+
+    default:
+      // Unknown commands are silently ignored
+      break;
+  }
+}
+
+/**
+ * Handle keystrokes in command mode.
+ * Escape returns to normal mode.
+ * Enter executes the command and returns to normal mode.
+ * Other keys are captured in the command buffer.
+ */
+function handleCommandModeKey(
+  e: React.KeyboardEvent<HTMLTextAreaElement>,
+  key: string,
+  setMode: React.Dispatch<React.SetStateAction<ViMode>>,
+  commandBuffer: string,
+  setCommandBuffer: React.Dispatch<React.SetStateAction<string>>,
+  callbacks: ExCommandCallbacks
+): void {
+  // Escape or Ctrl+C aborts command mode (standard vi behavior)
+  if (key === "Escape" || (e.ctrlKey && key === "c")) {
+    e.preventDefault();
+    setMode("normal");
+    setCommandBuffer("");
+    return;
+  }
+
+  if (key === "Enter") {
+    e.preventDefault();
+    // Execute the command before returning to normal mode
+    executeExCommand(commandBuffer, callbacks);
+    setMode("normal");
+    setCommandBuffer("");
+    return;
+  }
+
+  // Prevent default for all keys in command mode to avoid inserting into textarea
+  if (key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+    e.preventDefault();
+    setCommandBuffer((prev) => prev + key);
+  }
+
+  // Handle backspace in command buffer
+  if (key === "Backspace") {
+    e.preventDefault();
+    setCommandBuffer((prev) => prev.slice(0, -1));
+  }
+}
diff --git a/frontend/src/test-helpers.ts b/frontend/src/test-helpers.ts
index 1914a7d0..7044c4f7 100644
--- a/frontend/src/test-helpers.ts
+++ b/frontend/src/test-helpers.ts
@@ -33,5 +33,7 @@ export function createMockVault(overrides: Partial<VaultInfo> = {}): VaultInfo {
     order: overrides.order ?? 999999,
     // Ensure cardsEnabled is always a boolean
     cardsEnabled: overrides.cardsEnabled ?? true,
+    // Ensure viMode is always a boolean
+    viMode: overrides.viMode ?? false,
   };
 }
diff --git a/shared/src/__tests__/protocol.test.ts b/shared/src/__tests__/protocol.test.ts
index a7475728..4ea699c4 100644
--- a/shared/src/__tests__/protocol.test.ts
+++ b/shared/src/__tests__/protocol.test.ts
@@ -91,6 +91,7 @@ describe("VaultInfoSchema", () => {
       badges: [],
       order: 0,
       cardsEnabled: true,
+      viMode: false,
     };
 
     const result = VaultInfoSchema.parse(validVault);
@@ -573,6 +574,7 @@ describe("Server -> Client Messages", () => {
             badges: [],
             order: 1,
             cardsEnabled: true,
+            viMode: false,
           },
         ],
       };
diff --git a/shared/src/protocol.ts b/shared/src/protocol.ts
index 3030b905..86f24ecb 100644
--- a/shared/src/protocol.ts
+++ b/shared/src/protocol.ts
@@ -68,6 +68,7 @@ export const EditableVaultConfigSchema = z.object({
   badges: z.array(EditableBadgeSchema).max(5).optional(),
   order: z.number().int().min(1).optional(),
   cardsEnabled: z.boolean().optional(),
+  viMode: z.boolean().optional(),
 });
 
 // =============================================================================
@@ -98,6 +99,7 @@ export const VaultInfoSchema = z.object({
   badges: z.array(BadgeSchema),
   order: z.number(), // Can be Infinity for unset vaults
   cardsEnabled: z.boolean(),
+  viMode: z.boolean(),
 });
 
 // =============================================================================
diff --git a/shared/src/types.ts b/shared/src/types.ts
index 6a742ed5..63672ab6 100644
--- a/shared/src/types.ts
+++ b/shared/src/types.ts
@@ -50,6 +50,7 @@ export interface Badge {
  * @property badges - Custom badges configured in .memory-loop.json
  * @property order - Display order for vault selection (lower values first, Infinity for unset)
  * @property cardsEnabled - Whether spaced repetition card discovery is enabled (default: true)
+ * @property viMode - Whether vi mode is enabled for Pair Writing editor (default: false)
  */
 export interface VaultInfo {
   id: string;
@@ -72,6 +73,7 @@ export interface VaultInfo {
   badges: Badge[];
   order: number;
   cardsEnabled: boolean;
+  viMode: boolean;
 }
 
 /**