pi-vim 0.2.0 → 0.3.0

package/README.md

@@ -1,16 +1,12 @@
-# pi-vim — Vim Mode for Pi REPL
+# pi-vim
 
-Modal vim-like editing for Pi's REPL prompt.
-Focus: the high-frequency 90% command surface, not full Vim.
+Modal vim-like editing for Pi's input prompt. Covers the high-frequency 90% command surface.
 
-## TL;DR
+## why
 
-- Problem: REPL editing is slow with only linear cursor movement.
-- Solution: modal editing (`INSERT`/`NORMAL`) with Vim-style motions,
-  operators, counts, and repeatable workflows.
-- Install: `pi install npm:pi-vim`
+You love Pi, you love Vim, you'll love pi-vim.
 
-## Install
+## install
 
 ```bash
 pi install npm:pi-vim
@@ -18,19 +14,11 @@ pi install npm:pi-vim
 
 Restart Pi after install.
 
-### Local loading (dev)
+## stats
 
-```bash
-pi --extension /path/to/pi-vim/index.ts
-```
-
-Or add to `.pi/settings.json`:
-
-```json
-{
-  "extensions": ["./pi-extensions/pi-vim/index.ts"]
-}
-```
+- **112 commands**: motions, operators, counts, text objects, undo/redo
+- **sub-µs word motions** via precomputed boundary cache (~4ms startup, ~150KB memory)
+- **0 dependencies**
 
 ## 30-second quickstart
 
@@ -46,23 +34,25 @@ u          # undo
 ```
 
 Mode indicator (`INSERT` / `NORMAL`) appears at bottom-right.
+Its label is theme-colored: reverse-video `borderMuted` for
+INSERT, `borderAccent` for NORMAL.
 
-## Why pi-vim
+## why pi-vim
 
 - Fast modal editing without leaving Pi.
 - Count-aware motions/operators (`2dw`, `3G`, `d2j`, `2}`).
 - Strong REPL-focused defaults; safe out-of-scope boundaries documented.
 - Clipboard/register behavior is explicit and tested.
 
-## For you / not for you
+## for you / not for you
 
 Use pi-vim if you want fast Vim muscle-memory in Pi prompts.
 Skip it if you need full Vim feature parity (visual mode, macros, search,
 ex-commands, etc.).
 
-## Common recipes
+## common recipes
 
-| Goal | Keys |
+| goal | keys |
 |------|------|
 | Jump to exact line 25 | `25gg` (or `25G`) |
 | Delete two words | `2dw` |
@@ -76,24 +66,24 @@ ex-commands, etc.).
 
 ---
 
-## Full reference
+## full reference
 
-### Mode switching
+### mode switching
 
-| Key      | Action                                 |
+| key      | action                                 |
 |----------|----------------------------------------|
 | `Esc` / `Ctrl+[` | Insert → Normal mode                   |
 | `Esc` / `Ctrl+[` | Normal mode → pass to Pi (abort agent) |
 | `i`      | Normal → Insert at cursor              |
 | `a`      | Normal → Insert after cursor           |
-| `I`      | Normal → Insert at line start          |
+| `I`      | Normal → Insert at first non-whitespace |
 | `A`      | Normal → Insert at line end            |
 | `o`      | Normal → open line below + Insert      |
 | `O`      | Normal → open line above + Insert      |
 
 Insert-mode shortcuts (stay in Insert mode):
 
-| Key             | Action                 |
+| key             | action                 |
 |-----------------|------------------------|
 | `Shift+Alt+A`   | Go to end of line      |
 | `Shift+Alt+I`   | Go to start of line    |
@@ -102,11 +92,11 @@ Insert-mode shortcuts (stay in Insert mode):
 
 ---
 
-### Navigation (Normal mode)
+### navigation (normal mode)
 
 A `{count}` prefix can be prepended to any navigation key (max: `9999`).
 
-| Key           | Action                        |
+| key           | action                        |
 |---------------|-------------------------------|
 | `h`           | Left                          |
 | `l`           | Right                         |
@@ -116,6 +106,7 @@ A `{count}` prefix can be prepended to any navigation key (max: `9999`).
 | `{count}j/k`  | Move down/up `{count}` lines (clamped to buffer size) |
 | `0`           | Line start                    |
 | `^`           | First non-whitespace char of line |
+| `_`           | First non-whitespace char; with `{count}`, move down `count - 1` lines first |
 | `$`           | Line end                      |
 | `gg`          | Buffer start (line 1)         |
 | `{count}gg`   | Go to line `{count}` (1-indexed, clamped) |
@@ -148,11 +139,11 @@ Operator forms with braces (`d{`, `d}`, `c{`, `c}`, `y{`, `y}`) are out of scope
 
 ---
 
-### Character-find motions (Normal mode)
+### character-find motions (normal mode)
 
 A `{count}` prefix finds the Nth occurrence of `{char}` on the line.
 
-| Key              | Action                                         |
+| key              | action                                         |
 |------------------|------------------------------------------------|
 | `f{char}`        | Jump forward to `char` (inclusive)             |
 | `F{char}`        | Jump backward to `char` (inclusive)            |
@@ -166,17 +157,17 @@ Char-find motions compose with operators: `df{char}`, `ct{char}`, `d{count}t{cha
 
 ---
 
-### Edit operators (Normal mode)
+### edit operators (normal mode)
 
 All operators write to the unnamed register and mirror to the system clipboard
 (best-effort; clipboard failure never breaks editing).
 
-#### Delete `d{motion}` / `dd`
+#### delete `d{motion}` / `dd`
 
 A `{count}` or dual-count prefix (`{pfx}d{op}{motion}`) is supported for
 word, char-find, and linewise motions. Maximum total count: `9999`.
 
-| Command           | Deletes                                                   |
+| command           | deletes                                                   |
 |-------------------|-----------------------------------------------------------|
 | `dw`              | Forward to next `word` start (exclusive, can cross lines) |
 | `de`              | Forward to `word` end (inclusive, can cross lines)        |
@@ -189,6 +180,8 @@ word, char-find, and linewise motions. Maximum total count: `9999`.
 | `d$`              | To end of line                                            |
 | `d0`              | To start of line                                          |
 | `d^`              | To first non-whitespace char of line                      |
+| `d_`              | Current line (linewise, same as `dd`)                     |
+| `d{count}_`       | `{count}` lines (linewise, same as `{count}dd`)           |
 | `dd`              | Current line (linewise)                                   |
 | `{count}dd`       | `{count}` lines (linewise)                                |
 | `d{count}j`       | Current line + `{count}` lines below (linewise)           |
@@ -203,11 +196,11 @@ word, char-find, and linewise motions. Maximum total count: `9999`.
 | `daw`             | Around word (includes surrounding spaces)                 |
 | `d{count}aw`      | Around `{count}` words                                    |
 
-#### Change `c{motion}` / `cc`
+#### change `c{motion}` / `cc`
 
 Same motion and count set as `d`. Deletes text then enters Insert mode.
 
-| Command         | Action                             |
+| command         | action                             |
 |-----------------|------------------------------------|
 | `cw`            | Change `word` + Insert                        |
 | `ce` / `cb`     | Change to `word` end / previous `word` start  |
@@ -218,14 +211,16 @@ Same motion and count set as `d`. Deletes text then enters Insert mode.
 | `ciw`           | Change inner word                             |
 | `caw`           | Change around word                            |
 | `cc`            | Delete line content + Insert                  |
+| `c_`            | Change line (linewise, same as `cc`)                  |
+| `c{count}_`     | Change `{count}` lines (linewise)                     |
 | `c$` / `c0` / `c^` | Delete to EOL / BOL / first non-whitespace + Insert |
 | …               | All `d` motions apply                         |
 
-#### Single-key edits
+#### single-key edits
 
 A `{count}` prefix is supported for `x`, `p`, `P`. Maximum: `9999`.
 
-| Key          | Action                                                        |
+| key          | action                                                        |
 |--------------|---------------------------------------------------------------|
 | `x`          | Delete char under cursor (no-op at/past EOL)                  |
 | `{count}x`   | Delete `{count}` chars                                        |
@@ -233,17 +228,21 @@ A `{count}` prefix is supported for `x`, `p`, `P`. Maximum: `9999`.
 | `S`          | Delete line content + Insert mode                             |
 | `D`          | Delete cursor to EOL (captures `\n` if at EOL with next line) |
 | `C`          | Delete cursor to EOL + Insert mode                            |
+| `r{char}`    | Replace char under cursor with `{char}` (stays in Normal)     |
+| `{count}r{char}` | Replace next `{count}` chars with `{char}`               |
 
 ---
 
-### Yank `y{motion}` / `yy`
+### yank `y{motion}` / `yy`
 
 Same motion set as `d`. Writes to register, **no text mutation**.
 
-| Command | Yanks                           |
+| command | yanks                           |
 |---------|---------------------------------|
 | `yy`         | Whole line + trailing `\n`                     |
+| `Y`          | Whole line + trailing `\n` (same as `yy`)      |
 | `{count}yy`  | `{count}` whole lines + trailing `\n`          |
+| `{count}Y`   | `{count}` whole lines + trailing `\n` (same as `{count}yy`) |
 | `y{count}j`  | Current line + `{count}` lines below (linewise) |
 | `y{count}k`  | Current line + `{count}` lines above (linewise) |
 | `yG`         | Current line to end of buffer (linewise)         |
@@ -256,6 +255,8 @@ Same motion set as `d`. Writes to register, **no text mutation**.
 | `y$`         | To end of line                                    |
 | `y0`         | To start of line                                  |
 | `y^`         | To first non-whitespace char of line              |
+| `y_`         | Whole line (linewise, same as `yy`)               |
+| `y{count}_`  | `{count}` whole lines (linewise)                  |
 | `yf{c}`      | To and including `char`                           |
 | `yiw`        | Inner word                                        |
 | `yaw`        | Around word (includes spaces)                     |
@@ -266,9 +267,9 @@ Linewise counted yank (`{count}yy`, `y{count}j/k`) remains supported.
 
 ---
 
-### Put / Paste
+### put / paste
 
-| Key          | Action                                                      |
+| key          | action                                                      |
 |--------------|-------------------------------------------------------------|
 | `p`          | Put after cursor (char-wise) / new line below (line-wise)   |
 | `P`          | Put before cursor (char-wise) / new line above (line-wise)  |
@@ -280,22 +281,23 @@ Line-wise detection: register content ending in `\n` is treated as line-wise.
 
 ---
 
-### Undo / Redo
+### undo / redo
 
-| Key | Action |
+| key | action |
 |-----|--------|
-| `u` | Undo in normal mode |
+| `u` | Undo one change in normal mode |
+| `{count}u` | Undo up to `{count}` changes in normal mode; clamps at available history |
 | `Ctrl+_` | Undo in normal mode (alias for `u`) |
 | `<C-r>` | Redo one undone change in normal mode; safe no-op when redo history is empty |
 | `{count}<C-r>` | Redo up to `{count}` undone changes in order; clamps at available history and consumes count state (no leak to the next command) |
 
 ---
 
-## Register and clipboard policy
+## register and clipboard policy
 
 - One unnamed register (like Vim's `""` register).
 - Every `d`, `c`, `x`, `s`, `S`, `D`, `C`, `y` operator form
-  (including `dd`, `{count}dd`, `d{count}j/k`, `dG`, `yy`, `{count}yy`,
+  (including `dd`/`d_`, `{count}dd`, `d{count}j/k`, `dG`, `yy`/`y_`, `{count}yy`,
   `y{count}j/k`, `yG`) writes to the register and mirrors to the OS clipboard
   (via `copyToClipboard`, best-effort).
 - `p` / `P` read from the unnamed register only (not the OS clipboard).
@@ -303,9 +305,9 @@ Line-wise detection: register content ending in `\n` is treated as line-wise.
 
 ---
 
-## Known differences from full Vim
+## known differences from full Vim
 
-| Area                  | This extension                         | Full Vim                      |
+| area                  | this extension                         | full Vim                      |
 |-----------------------|----------------------------------------|-------------------------------|
 | `$` motion            | Moves past last char (readline CTRL+E) | Moves to last char            |
 | `w` / `e` / `b` + `W` / `E` / `B` | Cross-line for `word` + `WORD` motions | Cross-line                    |
@@ -314,7 +316,7 @@ Line-wise detection: register content ending in `\n` is treated as line-wise.
 | Redo                  | Normal-mode `<C-r>` supported (safe no-op when empty; counted redo is stepwise, clamps to available history, and preserves single-step undo granularity) | `<C-r>`                       |
 | Visual mode           | Not implemented                        | `v`, `V`, `<C-v>`            |
 | Text objects          | Supports `iw`/`aw` only               | Full text-object set           |
-| Count prefix          | Supported for operators, word/char motions, navigation, and edits (`x`, `p`/`P`); capped at `MAX_COUNT=9999` to prevent abuse | Full support |
+| Count prefix          | Supported for operators, word/char motions, navigation, and edits (`x`, `r`, `p`/`P`); capped at `MAX_COUNT=9999` to prevent abuse | Full support |
 | Named registers       | Not implemented (`"a`, etc.)           | Supported                     |
 | Macros                | Not implemented (`q`, `@`)             | Supported                     |
 | Search                | Not implemented (`/`, `?`, `n`, `N`)   | Supported                     |
@@ -323,7 +325,7 @@ Line-wise detection: register content ending in `\n` is treated as line-wise.
 
 ---
 
-## Out of scope
+## out of scope
 
 These are **explicitly deferred** and not planned for this feature:
 
@@ -334,6 +336,7 @@ These are **explicitly deferred** and not planned for this feature:
 - Ex command surface (`:s`, `:g`, `:r`, …)
 - Search mode (`/`, `?`, `n`, `N`)
 - Repeat (`.`)
+- Replace mode (`R`) — only single-char `r{char}` is supported
 - Extended count prefix beyond currently supported motions (e.g. `:`, global operator counts)
 - No insert-mode `<C-r>` feature expansion beyond current underlying-editor behavior.
 - No cross-session redo persistence.
@@ -343,7 +346,7 @@ These are **explicitly deferred** and not planned for this feature:
 
 ---
 
-## Architecture notes
+## architecture notes
 
 - `index.ts` — `ModalEditor` subclass of `CustomEditor`; all key handling.
 - `motions.ts` — pure motion calculation helpers (`findWordMotionTarget`,

package/index.ts

@@ -13,11 +13,12 @@
  * - hjkl: navigation in normal mode
  * - 0/$: line start/end
  * - ^: first non-whitespace char of line
+ * - _: first non-whitespace (with count: down count-1 lines first); linewise with d/c/y
  * - x: delete char under cursor
  * - D: delete to end of line
  * - S: substitute line (delete line content + insert mode)
  * - s: substitute char (delete char + insert mode)
- * - d{motion}: delete with motion (`w/b/e` + `W/B/E`, `$`, `0`, `^`, `dd`, `f/t/F/T{char}`)
+ * - d{motion}: delete with motion (`w/b/e` + `W/B/E`, `$`, `0`, `^`, `dd`/`d_`, `f/t/F/T{char}`)
  * - c{motion}: change with same motion set as `d` (then enter insert mode)
  * - y{motion}: yank with same motion set as `d` (no text mutation)
  * - f{char}: jump to next {char} on line
@@ -72,7 +73,6 @@ import {
   CHAR_MOTION_KEYS,
   ESC_LEFT,
   ESC_RIGHT,
-  ESC_DELETE,
   ESC_UP,
   CTRL_A,
   CTRL_E,
@@ -87,6 +87,7 @@ import {
   findCharMotionTarget,
   findParagraphMotionTarget,
   findFirstNonWhitespaceColumn,
+  getLineGraphemes,
   type WordMotionClass,
 } from "./motions.js";
 import {
@@ -127,6 +128,7 @@ export class ModalEditor extends CustomEditor {
   private operatorCount: string = "";
   private pendingG: boolean = false;
   private pendingGCount: string = "";
+  private pendingReplace: boolean = false;
   private lastCharMotion: LastCharMotion | null = null;
   private discardingBracketedPasteInNormalMode: boolean = false;
   private pendingEscWhileDiscardingBracketedPasteInNormalMode: boolean = false;
@@ -134,6 +136,7 @@ export class ModalEditor extends CustomEditor {
   private readonly redoStack: EditorSnapshot[] = [];
   private currentTransition: TransitionState = "none";
   private onChangeHooked: boolean = false;
+  private readonly labelColorizers: { insert: (s: string) => string; normal: (s: string) => string } | null;
 
   // Unnamed register
   private unnamedRegister: string = "";
@@ -141,6 +144,16 @@ export class ModalEditor extends CustomEditor {
     try { copyToClipboard(text); } catch { /* best effort */ }
   };
 
+  constructor(
+    tui: any,
+    theme: any,
+    kb: any,
+    labelColorizers?: { insert: (s: string) => string; normal: (s: string) => string } | null,
+  ) {
+    super(tui, theme, kb);
+    this.labelColorizers = labelColorizers ?? null;
+  }
+
   // Test seams
   setClipboardFn(fn: (text: string) => void): void { this.clipboardFn = fn; }
   getRegister(): string { return this.unnamedRegister; }
@@ -218,16 +231,22 @@ export class ModalEditor extends CustomEditor {
     }
   }
 
-  private performUndo(): void {
-    this.withTransition("undo", () => {
-      const beforeUndo = this.captureSnapshot();
-      super.handleInput(CTRL_UNDERSCORE);
-      const afterUndo = this.captureSnapshot();
-
-      if (this.snapshotChanged(beforeUndo, afterUndo)) {
-        this.redoStack.push(beforeUndo);
-      }
-    });
+  private performUndo(count: number = this.takeTotalCount(1)): void {
+    const maxSteps = Math.max(1, Math.min(MAX_COUNT, count));
+    for (let i = 0; i < maxSteps; i++) {
+      let changed = false;
+      this.withTransition("undo", () => {
+        const beforeUndo = this.captureSnapshot();
+        super.handleInput(CTRL_UNDERSCORE);
+        const afterUndo = this.captureSnapshot();
+
+        if (this.snapshotChanged(beforeUndo, afterUndo)) {
+          this.redoStack.push(beforeUndo);
+          changed = true;
+        }
+      });
+      if (!changed) break;
+    }
   }
 
   private performRedo(count: number = this.takeTotalCount(1)): void {
@@ -333,6 +352,7 @@ export class ModalEditor extends CustomEditor {
     this.operatorCount = "";
     this.pendingG = false;
     this.pendingGCount = "";
+    this.pendingReplace = false;
   }
 
   private isEscapeLikeInput(data: string): boolean {
@@ -441,6 +461,32 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (this.pendingReplace) {
+      this.pendingReplace = false;
+      if (!this.isPrintableInput(data)) {
+        this.prefixCount = "";
+        this.operatorCount = "";
+        return;
+      }
+
+      const count = this.takeTotalCount(1);
+      const cursor = this.getCursor();
+      const line = this.getLines()[cursor.line] ?? "";
+      const range = this.getGraphemeRangeAtCol(line, cursor.col, count);
+      if (!range) return;
+
+      const before = line.slice(0, range.start);
+      const after = line.slice(range.end);
+      const replacement = data.repeat(count);
+      const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
+      const text = this.getText();
+      const newText = text.slice(0, lineStartAbs) + before + replacement + after
+        + text.slice(lineStartAbs + line.length);
+      const newCursorAbs = lineStartAbs + before.length + data.length * (count - 1);
+      this.replaceTextInBuffer(newText, newCursorAbs);
+      return;
+    }
+
     if (this.pendingTextObject) {
       return this.handlePendingTextObject(data);
     }
@@ -491,6 +537,7 @@ export class ModalEditor extends CustomEditor {
       || this.operatorCount
       || this.pendingG
       || this.pendingGCount
+      || this.pendingReplace
     ) {
       this.clearPendingState();
       return;
@@ -513,7 +560,7 @@ export class ModalEditor extends CustomEditor {
   }
 
   private isPrintableInput(data: string): boolean {
-    return this.isPrintableChunk(data) && Array.from(data).length === 1;
+    return this.isPrintableChunk(data) && getLineGraphemes(data).length === 1;
   }
 
   private isDigit(data: string): boolean {
@@ -663,6 +710,13 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (data === "_") {
+      const count = this.takeTotalCount(1);
+      this.deleteLinewiseByDelta(count - 1);
+      this.pendingOperator = null;
+      return;
+    }
+
     if (CHAR_MOTION_KEYS.has(data)) {
       this.pendingMotion = data as PendingMotion;
       return;
@@ -725,6 +779,28 @@ export class ModalEditor extends CustomEditor {
       this.mode = "insert";
       return;
     }
+
+    if (data === "_") {
+      const count = this.takeTotalCount(1);
+      if (count <= 1) {
+        this.cutLine();
+      } else {
+        const currentLine = this.getCursor().line;
+        const lines = this.getLines();
+        const clampedEnd = Math.min(currentLine + count - 1, lines.length - 1);
+        this.writeToRegister(this.getLinewisePayload(currentLine, clampedEnd));
+        const before = lines.slice(0, currentLine);
+        const after = lines.slice(clampedEnd + 1);
+        const newLines = [...before, "", ...after];
+        const newText = newLines.join("\n");
+        const cursorAbs = before.reduce((acc, l) => acc + l.length + 1, 0);
+        this.replaceTextInBuffer(newText, cursorAbs);
+      }
+      this.pendingOperator = null;
+      this.mode = "insert";
+      return;
+    }
+
     if (CHAR_MOTION_KEYS.has(data)) {
       this.pendingMotion = data as PendingMotion;
       return;
@@ -823,13 +899,18 @@ export class ModalEditor extends CustomEditor {
 
       const supportsCountedStandaloneEdit = (
         data === "x"
+        || data === "r"
         || data === "s"
         || data === "S"
         || data === "D"
         || data === "C"
         || data === "p"
         || data === "P"
+        || data === "Y"
         || data === "J"
+        || data === "u"
+        || data === CTRL_UNDERSCORE
+        || matchesKey(data, "ctrl+_")
         || data === CTRL_R
         || matchesKey(data, "ctrl+r")
       );
@@ -853,6 +934,7 @@ export class ModalEditor extends CustomEditor {
         || data === "k"
         || data === "l"
       );
+      const supportsCountedUnderscore = data === "_";
 
       if (supportsCountedNav) {
         const count = this.takeTotalCount(1);
@@ -862,16 +944,8 @@ export class ModalEditor extends CustomEditor {
         } else if (data === "l") {
           this.moveCursorBy(clamped);
         } else {
-          // j/k: clamp vertical nav to buffer size to prevent TUI stalls
-          const lines = this.getLines();
-          const cursorLine = this.getCursor().line;
-          const safeCount = data === "j"
-            ? Math.min(clamped, lines.length - 1 - cursorLine)
-            : Math.min(clamped, cursorLine);
-          const seq = data === "j" ? ESC_DOWN : ESC_UP;
-          for (let i = 0; i < safeCount; i++) {
-            super.handleInput(seq);
-          }
+          const delta = data === "j" ? clamped : -clamped;
+          this.moveCursorVertically(delta);
         }
         return;
       }
@@ -886,6 +960,7 @@ export class ModalEditor extends CustomEditor {
         && !supportsCountedCharMotion
         && !supportsCountedWordMotion
         && !supportsCountedParagraphMotion
+        && !supportsCountedUnderscore
       ) {
         // Unsupported prefixed forms: drop count and keep processing this key.
         this.prefixCount = "";
@@ -912,6 +987,11 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (data === "r") {
+      this.pendingReplace = true;
+      return;
+    }
+
     if (data === "d") {
       this.pendingOperator = "d";
       return;
@@ -937,6 +1017,12 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (data === "Y") {
+      const count = this.takeTotalCount(1);
+      this.yankLinewiseByDelta(count - 1);
+      return;
+    }
+
     if (CHAR_MOTION_KEYS.has(data)) {
       this.pendingMotion = data as PendingMotion;
       return;
@@ -975,6 +1061,15 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (data === "_") {
+      const count = this.takeTotalCount(1);
+      if (count > 1) {
+        this.moveCursorVertically(count - 1);
+      }
+      this.moveCursorToFirstNonWhitespace();
+      return;
+    }
+
     if (data === "w") {
       const count = this.takeTotalCount(1);
       return this.moveWord("forward", "start", count, "word");
@@ -1023,7 +1118,7 @@ export class ModalEditor extends CustomEditor {
         break;
       case "I":
         this.mode = "insert";
-        super.handleInput(CTRL_A);
+        this.moveCursorToFirstNonWhitespace();
         break;
       case "o":
         this.openLineBelow();
@@ -1054,6 +1149,12 @@ export class ModalEditor extends CustomEditor {
       case "x":
         this.cutCharUnderCursor();
         break;
+      case "j":
+        this.moveCursorVertically(1);
+        break;
+      case "k":
+        this.moveCursorVertically(-1);
+        break;
       default:
         if (seq) super.handleInput(seq);
     }
@@ -1070,7 +1171,7 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (targetCol !== null && targetCol !== col) {
-      this.moveCursorBy(targetCol - col);
+      this.moveCursorToCol(targetCol);
     }
   }
 
@@ -1098,10 +1199,12 @@ export class ModalEditor extends CustomEditor {
     const cursorLine = state.cursorLine as number;
     const cursorCol = state.cursorCol as number;
     const line = state.lines[cursorLine] ?? "";
+    if (this.hasMultiCodeUnitGraphemes(line)) return false;
+
     const target = cursorCol + delta;
 
-    // Only short-circuit line-local movement; preserve canonical key replay for
-    // any potential cross-line traversal semantics.
+    // Only short-circuit line-local movement when each grapheme is one code
+    // unit; otherwise let the base editor keep cursor boundaries valid.
     if (target < 0 || target > line.length) return false;
 
     state.cursorCol = target;
@@ -1121,38 +1224,100 @@ export class ModalEditor extends CustomEditor {
     }
   }
 
-  private moveCursorToLineStart(lineIndex: number): void {
-    const lines = this.getLines();
-    if (lines.length === 0) {
-      super.handleInput(CTRL_A);
-      return;
-    }
+  private moveCursorVertically(delta: number): void {
+    if (delta === 0) return;
 
-    const targetLine = Math.max(0, Math.min(lineIndex, lines.length - 1));
-    const currentLine = this.getCursor().line;
-    const delta = targetLine - currentLine;
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
 
-    if (delta > 0) {
-      for (let i = 0; i < delta; i++) {
-        super.handleInput(ESC_DOWN);
-      }
-    } else if (delta < 0) {
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines) || state.lines.length === 0) {
+      const seq = delta > 0 ? ESC_DOWN : ESC_UP;
       for (let i = 0; i < Math.abs(delta); i++) {
-        super.handleInput(ESC_UP);
+        super.handleInput(seq);
       }
+      return;
     }
 
-    super.handleInput(CTRL_A);
+    const currentLine = state.cursorLine ?? 0;
+    const targetLine = Math.max(0, Math.min(currentLine + delta, state.lines.length - 1));
+    if (targetLine === currentLine) return;
+
+    const preferredCol = editor.preferredVisualCol ?? state.cursorCol ?? 0;
+    const targetLineText = state.lines[targetLine] ?? "";
+    editor.lastAction = null;
+    state.cursorLine = targetLine;
+    state.cursorCol = Math.min(preferredCol, targetLineText.length);
+    editor.preferredVisualCol = preferredCol;
+    editor.tui?.requestRender?.();
+  }
+
+  private moveCursorToCol(col: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines)) return;
+
+    editor.lastAction = null;
+    state.cursorCol = col;
+    editor.preferredVisualCol = col;
+    editor.tui?.requestRender?.();
+  }
+
+  private moveCursorToAbsoluteIndex(abs: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines)) return;
+
+    const { line, col } = this.getCursorFromAbsoluteIndex(this.getText(), abs);
+    editor.lastAction = null;
+    state.cursorLine = line;
+    state.cursorCol = col;
+    editor.preferredVisualCol = col;
+    editor.tui?.requestRender?.();
+  }
+
+  private moveCursorToLineStart(lineIndex: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines) || state.lines.length === 0) {
+      super.handleInput(CTRL_A);
+      return;
+    }
+
+    const targetLine = Math.max(0, Math.min(lineIndex, state.lines.length - 1));
+    editor.lastAction = null;
+    state.cursorLine = targetLine;
+    state.cursorCol = 0;
+    editor.preferredVisualCol = null;
+    editor.tui?.requestRender?.();
   }
 
   private moveCursorToFirstNonWhitespace(): void {
     const { line, col } = this.getCurrentLineAndCol();
     const targetCol = findFirstNonWhitespaceColumn(line);
-    this.moveCursorBy(targetCol - col);
-  }
-
-  private moveCursorToBufferStart(): void {
-    this.moveCursorToLineStart(0);
+    this.moveCursorToCol(targetCol);
   }
 
   private moveCursorToBufferEnd(): void {
@@ -1343,7 +1508,6 @@ export class ModalEditor extends CustomEditor {
   private tryFindWordTargetLineLocal(
     direction: WordMotionDirection,
     target: WordMotionTarget,
-    allowSameColumn: boolean = false,
     semanticClass: WordMotionClass = "word",
   ): number | null {
     const cursor = this.getCursor();
@@ -1356,7 +1520,7 @@ export class ModalEditor extends CustomEditor {
       col,
       direction,
       target,
-      allowSameColumn,
+      false,
       semanticClass,
     );
     if (targetCol === null) return null;
@@ -1374,10 +1538,10 @@ export class ModalEditor extends CustomEditor {
     semanticClass: WordMotionClass = "word",
   ): boolean {
     const col = this.getCursor().col;
-    const targetCol = this.tryFindWordTargetLineLocal(direction, target, false, semanticClass);
+    const targetCol = this.tryFindWordTargetLineLocal(direction, target, semanticClass);
     if (targetCol === null || targetCol === col) return false;
 
-    this.moveCursorBy(targetCol - col);
+    this.moveCursorToCol(targetCol);
     return true;
   }
 
@@ -1445,7 +1609,7 @@ export class ModalEditor extends CustomEditor {
         semanticClass,
       );
       if (targetAbs !== currentAbs) {
-        this.moveCursorBy(targetAbs - currentAbs);
+        this.moveCursorToAbsoluteIndex(targetAbs);
       }
       return;
     }
@@ -1463,6 +1627,33 @@ export class ModalEditor extends CustomEditor {
     return { line, col };
   }
 
+  private hasMultiCodeUnitGraphemes(line: string): boolean {
+    return getLineGraphemes(line).some((segment) => segment.end - segment.start > 1);
+  }
+
+  private getGraphemeRangeAtCol(
+    line: string,
+    col: number,
+    count: number,
+    clampToLine: boolean = false,
+  ): { start: number; end: number } | null {
+    const clampedCol = Math.max(0, Math.min(col, line.length));
+    const segments = getLineGraphemes(line);
+    const startIndex = segments.findIndex((segment) => clampedCol < segment.end);
+    if (startIndex === -1) return null;
+
+    let endIndex = startIndex + Math.max(1, count) - 1;
+    if (endIndex >= segments.length) {
+      if (!clampToLine) return null;
+      endIndex = segments.length - 1;
+    }
+
+    return {
+      start: segments[startIndex]!.start,
+      end: segments[endIndex]!.end,
+    };
+  }
+
   private isCursorOnNonWhitespace(): boolean {
     const { line, col } = this.getCurrentLineAndCol();
     const ch = line[col];
@@ -1475,13 +1666,19 @@ export class ModalEditor extends CustomEditor {
   }
 
   private cutCharUnderCursor(): void {
-    const count = this.takeTotalCount(1);
-    const { line, col } = this.getCurrentLineAndCol();
-    if (line.length === 0) return; // Don't merge empty lines with x
-    if (col >= line.length) return; // Don't delete past end of line
+    const count = Math.max(1, Math.min(MAX_COUNT, this.takeTotalCount(1)));
+    const cursor = this.getCursor();
+    const line = this.getLines()[cursor.line] ?? "";
+    const range = this.getGraphemeRangeAtCol(line, cursor.col, count, true);
+    if (!range) return;
 
-    const boundedCount = Math.max(1, Math.min(MAX_COUNT, count));
-    this.deleteRange(col, col + boundedCount, false);
+    const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
+    const text = this.getText();
+    this.writeToRegister(line.slice(range.start, range.end));
+    this.replaceTextInBuffer(
+      text.slice(0, lineStartAbs + range.start) + text.slice(lineStartAbs + range.end),
+      lineStartAbs + range.start,
+    );
   }
 
   private cutToEndOfLine(): void {
@@ -1562,19 +1759,13 @@ export class ModalEditor extends CustomEditor {
     this.writeToRegister(payload);
 
     if (endAbs > startAbs) {
-      const cursor = this.getCursor();
-      const cursorAbs = this.getAbsoluteIndex(cursor.line, cursor.col);
-      if (cursorAbs !== startAbs) {
-        this.moveCursorBy(startAbs - cursorAbs);
-      }
+      const text = this.getText();
+      const newText = text.slice(0, startAbs) + text.slice(endAbs);
+      this.replaceTextInBuffer(newText, startAbs);
 
-      const count = endAbs - startAbs;
-      for (let i = 0; i < count; i++) {
-        super.handleInput(ESC_DELETE);
-      }
+      // Ensure cursor is at column 0 of the landing line
+      super.handleInput(CTRL_A);
     }
-
-    super.handleInput(CTRL_A);
   }
 
   private yankLineRange(startLine: number, endLine: number): void {
@@ -1637,7 +1828,7 @@ export class ModalEditor extends CustomEditor {
       }
 
       const text = this.getText();
-      const currentAbs = this.getAbsoluteIndex(cursor.line, col);
+      const currentAbs = this.getAbsoluteIndexFromCursor();
       const targetAbs = this.findWordTargetInText(
         text,
         currentAbs,
@@ -1705,6 +1896,13 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (data === "_") {
+      const count = this.takeTotalCount(1);
+      this.yankLinewiseByDelta(count - 1);
+      this.pendingOperator = null;
+      return;
+    }
+
     if (CHAR_MOTION_KEYS.has(data)) {
       this.pendingMotion = data as PendingMotion;
       return;
@@ -1765,7 +1963,7 @@ export class ModalEditor extends CustomEditor {
       }
 
       const text = this.getText();
-      const currentAbs = this.getAbsoluteIndex(cursor.line, col);
+      const currentAbs = this.getAbsoluteIndexFromCursor();
       const targetAbs = this.findWordTargetInText(
         text,
         currentAbs,
@@ -1797,7 +1995,12 @@ export class ModalEditor extends CustomEditor {
     const line = this.getLines()[this.getCursor().line] ?? "";
     const start = Math.min(col, targetCol);
     const rawEnd = Math.max(col, targetCol) + (inclusive ? 1 : 0);
-    const end = Math.min(rawEnd, line.length);
+    let end = Math.min(rawEnd, line.length);
+
+    if (inclusive) {
+      const targetRange = this.getGraphemeRangeAtCol(line, Math.max(col, targetCol), 1);
+      end = targetRange?.end ?? end;
+    }
 
     if (end <= start) return;
 
@@ -1814,6 +2017,47 @@ export class ModalEditor extends CustomEditor {
     this.writeToRegister(text.slice(start, end));
   }
 
+  private getCursorFromAbsoluteIndex(text: string, abs: number): { line: number; col: number } {
+    const lines = text.length === 0 ? [""] : text.split("\n");
+    let remaining = Math.max(0, Math.min(abs, text.length));
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+      const line = lines[lineIndex] ?? "";
+      if (remaining <= line.length) return { line: lineIndex, col: remaining };
+      remaining -= line.length + 1;
+    }
+    const lastLine = Math.max(0, lines.length - 1);
+    return { line: lastLine, col: (lines[lastLine] ?? "").length };
+  }
+
+  private replaceTextInBuffer(text: string, cursorAbs: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      historyIndex?: number;
+      lastAction?: string | null;
+      onChange?: (text: string) => void;
+      tui?: { requestRender?: () => void };
+      pushUndoSnapshot?: () => void;
+      autocompleteState?: unknown;
+      updateAutocomplete?: () => void;
+    };
+    const state = editor.state;
+    if (!state) return;
+    const currentText = this.getText();
+    if (currentText !== text) editor.pushUndoSnapshot?.();
+    const nextLines = text.length === 0 ? [""] : text.split("\n");
+    const { line, col } = this.getCursorFromAbsoluteIndex(text, cursorAbs);
+    editor.historyIndex = -1;
+    editor.lastAction = null;
+    state.lines = nextLines;
+    state.cursorLine = line;
+    state.cursorCol = col;
+    editor.preferredVisualCol = null;
+    editor.onChange?.(text);
+    if (editor.autocompleteState) editor.updateAutocomplete?.();
+    editor.tui?.requestRender?.();
+  }
+
   private deleteRangeByAbsolute(currentAbs: number, targetAbs: number, inclusive: boolean = false): void {
     const text = this.getText();
     const start = Math.min(currentAbs, targetAbs);
@@ -1824,16 +2068,7 @@ export class ModalEditor extends CustomEditor {
 
     this.writeToRegister(text.slice(start, end));
 
-    const cursor = this.getCursor();
-    const cursorAbs = this.getAbsoluteIndex(cursor.line, cursor.col);
-    if (cursorAbs !== start) {
-      this.moveCursorBy(start - cursorAbs);
-    }
-
-    const count = end - start;
-    for (let i = 0; i < count; i++) {
-      super.handleInput(ESC_DELETE);
-    }
+    this.replaceTextInBuffer(text.slice(0, start) + text.slice(end), start);
   }
 
   private getWordObjectRange(
@@ -1960,34 +2195,33 @@ export class ModalEditor extends CustomEditor {
   }
 
   private deleteRange(col: number, targetCol: number, inclusive: boolean): void {
-    const line = this.getLines()[this.getCursor().line] ?? "";
-
+    const cursor = this.getCursor();
+    const line = this.getLines()[cursor.line] ?? "";
+    const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
     const start = Math.min(col, targetCol);
     const rawEnd = Math.max(col, targetCol) + (inclusive ? 1 : 0);
-    const end = Math.min(rawEnd, line.length);
+    let end = Math.min(rawEnd, line.length);
 
-    if (end <= start) return;
-
-    this.writeToRegister(line.slice(start, end));
-
-    if (start !== col) {
-      this.moveCursorBy(start - col);
+    if (inclusive) {
+      const targetRange = this.getGraphemeRangeAtCol(line, Math.max(col, targetCol), 1);
+      end = targetRange?.end ?? end;
     }
 
-    const count = end - start;
-    for (let i = 0; i < count; i++) {
-      super.handleInput(ESC_DELETE);
-    }
+    this.deleteRangeByAbsolute(lineStartAbs + start, lineStartAbs + end);
   }
 
   render(width: number): string[] {
     const lines = super.render(width);
     if (lines.length === 0) return lines;
 
-    const label = this.getModeLabel();
+    const rawLabel = this.getModeLabel();
+    const colorize = this.labelColorizers
+      ? (this.mode === "insert" ? this.labelColorizers.insert : this.labelColorizers.normal)
+      : null;
+    const label = colorize ? colorize(rawLabel) : rawLabel;
     const last = lines.length - 1;
-    if (visibleWidth(lines[last]!) >= label.length) {
-      lines[last] = truncateToWidth(lines[last]!, width - label.length, "") + label;
+    if (visibleWidth(lines[last]!) >= visibleWidth(rawLabel)) {
+      lines[last] = truncateToWidth(lines[last]!, width - visibleWidth(rawLabel), "") + label;
     }
     return lines;
   }
@@ -1998,6 +2232,9 @@ export class ModalEditor extends CustomEditor {
     const prefixCount = this.prefixCount;
     const operatorCount = this.operatorCount;
 
+    if (this.pendingReplace) {
+      return prefixCount ? ` NORMAL ${prefixCount}r_ ` : " NORMAL r_ ";
+    }
     if (this.pendingOperator && this.pendingMotion) {
       return ` NORMAL ${prefixCount}${this.pendingOperator}${operatorCount}${this.pendingMotion}_ `;
     }
@@ -2019,6 +2256,11 @@ export class ModalEditor extends CustomEditor {
 
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
-    ctx.ui.setEditorComponent((tui, theme, kb) => new ModalEditor(tui, theme, kb));
+    const t = ctx.ui.theme;
+    const colorizers = t ? {
+      insert: (s: string) => t.fg("borderMuted", `\x1b[7m${s}\x1b[27m`),
+      normal: (s: string) => t.fg("borderAccent", `\x1b[7m${s}\x1b[27m`),
+    } : null;
+    ctx.ui.setEditorComponent((tui, theme, kb) => new ModalEditor(tui, theme, kb, colorizers));
   });
 }

package/motions.ts

@@ -125,6 +125,27 @@ export function reverseCharMotion(motion: CharMotion): CharMotion {
   return reverseMap[motion];
 }
 
+const GRAPHEME_SEGMENTER = typeof Intl !== "undefined"
+  && typeof Intl.Segmenter === "function"
+  ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+  : null;
+
+export function getLineGraphemes(line: string): Array<{ start: number; end: number }> {
+  const segments: Array<{ start: number; end: number }> = [];
+  if (GRAPHEME_SEGMENTER) {
+    for (const part of GRAPHEME_SEGMENTER.segment(line)) {
+      segments.push({ start: part.index, end: part.index + part.segment.length });
+    }
+    return segments;
+  }
+  let start = 0;
+  for (const text of Array.from(line)) {
+    segments.push({ start, end: start + text.length });
+    start += text.length;
+  }
+  return segments;
+}
+
 /**
  * Find target column for a character motion (f/F/t/T).
  * @returns target column or null if not found
@@ -141,7 +162,9 @@ export function findCharMotionTarget(
   const isTill = motion === "t" || motion === "T";
   const steps = Number.isFinite(count) && count > 0 ? Math.floor(count) : 1;
 
-  let currentPos = col;
+  const graphemes = getLineGraphemes(line);
+  let currentIndex = graphemes.findIndex(g => col < g.end);
+  if (currentIndex === -1) currentIndex = graphemes.length;
 
   for (let i = 0; i < steps; i++) {
     const isFirst = i === 0;
@@ -149,19 +172,38 @@ export function findCharMotionTarget(
     const tillRepeatOffset = isFirst && isTill && isRepeat ? 1 : 0;
 
     if (isForward) {
-      const searchStart = currentPos + 1 + tillRepeatOffset;
-      const idx = line.indexOf(targetChar, searchStart);
-      if (idx === -1) return null;
-      if (isFinal) return isTill ? idx - 1 : idx;
-      currentPos = idx;
-      continue;
+      let nextIndex = currentIndex + 1 + tillRepeatOffset;
+      let found = -1;
+      for (let j = nextIndex; j < graphemes.length; j++) {
+        const g = graphemes[j]!;
+        // Use startsWith to allow matching base chars if targetChar lacks combining marks,
+        // or just exact match since targetChar is typically a full grapheme.
+        if (line.slice(g.start, g.end) === targetChar || line.slice(g.start, g.end).startsWith(targetChar)) {
+          found = j;
+          break;
+        }
+      }
+      if (found === -1) return null;
+      if (isFinal) return isTill ? graphemes[found - 1]!.start : graphemes[found]!.start;
+      currentIndex = found;
+    } else {
+      let nextIndex = currentIndex - 1 - tillRepeatOffset;
+      let found = -1;
+      for (let j = nextIndex; j >= 0; j--) {
+        const g = graphemes[j]!;
+        if (line.slice(g.start, g.end) === targetChar || line.slice(g.start, g.end).startsWith(targetChar)) {
+          found = j;
+          break;
+        }
+      }
+      if (found === -1) return null;
+      if (isFinal) {
+        if (!isTill) return graphemes[found]!.start;
+        const afterTarget = graphemes[found + 1];
+        return afterTarget ? afterTarget.start : line.length;
+      }
+      currentIndex = found;
     }
-
-    const searchStart = currentPos - 1 - tillRepeatOffset;
-    const idx = line.lastIndexOf(targetChar, searchStart);
-    if (idx === -1) return null;
-    if (isFinal) return isTill ? idx + 1 : idx;
-    currentPos = idx;
   }
 
   return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-vim",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Vim-style modal editing for Pi's TUI editor",
   "type": "module",
   "keywords": [

package/types.ts

@@ -39,7 +39,6 @@ export const CHAR_MOTION_KEYS = new Set<string>(["f", "F", "t", "T"]);
 // Escape sequences
 export const ESC_LEFT = "\x1b[D";
 export const ESC_RIGHT = "\x1b[C";
-export const ESC_DELETE = "\x1b[3~";
 export const CTRL_A = "\x01"; // line start
 export const CTRL_E = "\x05"; // line end
 export const CTRL_K = "\x0b"; // kill to end of line