pi-vim 0.1.7 → 0.1.9

package/README.md

@@ -1,35 +1,87 @@
-# vim-bindings — Pi REPL Vim Mode
+# pi-vim — Vim Mode for Pi REPL
 
-A modal vim-like editing extension for Pi's REPL prompt, covering the
-high-frequency ("90%") command surface without trying to clone full Vim.
+Modal vim-like editing for Pi's REPL prompt.
+Focus: the high-frequency 90% command surface, not full Vim.
 
-## Loading
+## TL;DR
 
+- 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`
+
+## Install
+
+```bash
+pi install npm:pi-vim
 ```
-pi --extension /path/to/vim-bindings/index.ts
+
+Restart Pi after install.
+
+### Local loading (dev)
+
+```bash
+pi --extension /path/to/pi-vim/index.ts
 ```
 
 Or add to `.pi/settings.json`:
 
 ```json
 {
-  "extensions": ["./pi-extensions/vim-bindings/index.ts"]
+  "extensions": ["./pi-extensions/pi-vim/index.ts"]
 }
 ```
 
-The mode indicator (`INSERT` / `NORMAL`) is shown in the bottom-right corner
-of the prompt.
+## 30-second quickstart
+
+Try on multi-line input:
+
+```text
+Esc        # NORMAL mode
+3gg        # jump to absolute line 3
+2dw        # delete two words
+u          # undo
+2}         # jump two paragraphs forward
+```
+
+Mode indicator (`INSERT` / `NORMAL`) appears at bottom-right.
+
+## 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
+
+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
+
+| Goal | Keys |
+|------|------|
+| Jump to exact line 25 | `25gg` (or `25G`) |
+| Delete two words | `2dw` |
+| Change to end of line | `C` |
+| Delete current + 2 lines below | `d2j` |
+| Yank 3 lines | `3yy` |
+| Join 3 lines with spacing | `3J` |
+| Jump 2 paragraphs forward | `2}` |
+| Undo last edit | `u` |
 
 ---
 
-## Supported command surface
+## Full reference
 
 ### Mode switching
 
 | Key      | Action                                 |
 |----------|----------------------------------------|
-| `Esc`    | Insert → Normal mode                   |
-| `Esc`    | Normal mode → pass to Pi (abort agent) |
+| `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          |
@@ -61,9 +113,12 @@ A `{count}` prefix can be prepended to any navigation key (max: `9999`).
 | `{count}h/l`  | Move left/right `{count}` cols  |
 | `{count}j/k`  | Move down/up `{count}` lines (clamped to buffer size) |
 | `0`           | Line start                    |
+| `^`           | First non-whitespace char of line |
 | `$`           | Line end                      |
 | `gg`          | Buffer start (line 1)         |
+| `{count}gg`   | Go to line `{count}` (1-indexed, clamped) |
 | `G`           | Buffer end (last line)        |
+| `{count}G`    | Go to line `{count}` (1-indexed, clamped) |
 | `w`           | Next `word` start (keyword/punctuation aware) |
 | `b`           | Previous `word` start         |
 | `e`           | `word` end (inclusive)        |
@@ -131,6 +186,7 @@ word, char-find, and linewise motions. Maximum total count: `9999`.
 | `d{count}W/E/B`   | Forward/backward `{count}` `WORD` motions                 |
 | `d$`              | To end of line                                            |
 | `d0`              | To start of line                                          |
+| `d^`              | To first non-whitespace char of line                      |
 | `dd`              | Current line (linewise)                                   |
 | `{count}dd`       | `{count}` lines (linewise)                                |
 | `d{count}j`       | Current line + `{count}` lines below (linewise)           |
@@ -160,7 +216,7 @@ 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$`            | Delete to EOL + Insert                        |
+| `c$` / `c0` / `c^` | Delete to EOL / BOL / first non-whitespace + Insert |
 | …               | All `d` motions apply                         |
 
 #### Single-key edits
@@ -197,6 +253,7 @@ Same motion set as `d`. Writes to register, **no text mutation**.
 | `yB`         | Backward to `WORD` start                          |
 | `y$`         | To end of line                                    |
 | `y0`         | To start of line                                  |
+| `y^`         | To first non-whitespace char of line              |
 | `yf{c}`      | To and including `char`                           |
 | `yiw`        | Inner word                                        |
 | `yaw`        | Around word (includes spaces)                     |
@@ -274,7 +331,7 @@ These are **explicitly deferred** and not planned for this feature:
 - Ex command surface (`:s`, `:g`, `:r`, …)
 - Search mode (`/`, `?`, `n`, `N`)
 - Repeat (`.`)
-- Extended count prefix beyond currently supported motions (e.g. counted `gg`, `:`, global operator counts)
+- Extended count prefix beyond currently supported motions (e.g. `:`, global operator counts)
 - Redo (`<C-r>`) — no native redo primitive in the underlying readline editor;
   deferred until a suitable hook is available.
 - Window / tab / buffer management
@@ -293,6 +350,6 @@ These are **explicitly deferred** and not planned for this feature:
 Run tests:
 
 ```
-cd vim-bindings
+cd pi-vim
 npm test
 ```

package/index.ts

@@ -3,7 +3,7 @@
  *
  * Usage: pi --extension ./index.ts
  *
- * - Escape: insert → normal mode (in normal mode, aborts agent)
+ * - Escape / ctrl+[: insert → normal mode (in normal mode, aborts agent)
  * - i: normal → insert mode (at cursor)
  * - a: insert after cursor
  * - A: insert at end of line
@@ -12,11 +12,12 @@
  * - O: open new line above (insert mode)
  * - hjkl: navigation in normal mode
  * - 0/$: line start/end
+ * - ^: first non-whitespace char of line
  * - 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`, `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
@@ -84,6 +85,7 @@ import {
   reverseCharMotion,
   findCharMotionTarget,
   findParagraphMotionTarget,
+  findFirstNonWhitespaceColumn,
   type WordMotionClass,
 } from "./motions.js";
 import {
@@ -134,6 +136,10 @@ export class ModalEditor extends CustomEditor {
     this.pendingGCount = "";
   }
 
+  private isEscapeLikeInput(data: string): boolean {
+    return matchesKey(data, "escape") || matchesKey(data, "ctrl+[");
+  }
+
   private stripBracketedPasteInNormalMode(data: string): { filtered: string | null; stripped: boolean } {
     let chunk = data;
     let stripped = false;
@@ -172,7 +178,7 @@ export class ModalEditor extends CustomEditor {
   handleInput(data: string): void {
     if (this.mode !== "insert") {
       if (this.discardingBracketedPasteInNormalMode) {
-        if (data === "\x1b") {
+        if (this.isEscapeLikeInput(data)) {
           if (this.pendingEscWhileDiscardingBracketedPasteInNormalMode) {
             this.pendingEscWhileDiscardingBracketedPasteInNormalMode = false;
             this.discardingBracketedPasteInNormalMode = false;
@@ -206,7 +212,7 @@ export class ModalEditor extends CustomEditor {
       data = filtered;
     }
 
-    if (matchesKey(data, "escape")) {
+    if (this.isEscapeLikeInput(data)) {
       return this.handleEscape();
     }
 
@@ -573,8 +579,8 @@ export class ModalEditor extends CustomEditor {
 
       if (!hadGCount) {
         if (data === "g") {
-          this.takeTotalCount(1);
-          this.moveCursorToBufferStart();
+          const count = this.takeTotalCount(1);
+          this.moveCursorToLineStart(count - 1);
           return;
         }
 
@@ -610,6 +616,12 @@ export class ModalEditor extends CustomEditor {
         return;
       }
 
+      if (data === "G") {
+        const count = this.takeTotalCount(1);
+        this.moveCursorToLineStart(count - 1);
+        return;
+      }
+
       const supportsCountedStandaloneEdit = (
         data === "x"
         || data === "s"
@@ -752,6 +764,11 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (data === "^") {
+      this.moveCursorToFirstNonWhitespace();
+      return;
+    }
+
     if (data === "w") {
       const count = this.takeTotalCount(1);
       return this.moveWord("forward", "start", count, "word");
@@ -914,6 +931,12 @@ export class ModalEditor extends CustomEditor {
     super.handleInput(CTRL_A);
   }
 
+  private moveCursorToFirstNonWhitespace(): void {
+    const { line, col } = this.getCurrentLineAndCol();
+    const targetCol = findFirstNonWhitespaceColumn(line);
+    this.moveCursorBy(targetCol - col);
+  }
+
   private moveCursorToBufferStart(): void {
     this.moveCursorToLineStart(0);
   }
@@ -1382,6 +1405,11 @@ export class ModalEditor extends CustomEditor {
       return true;
     }
 
+    if (motion === "^") {
+      this.deleteRange(col, findFirstNonWhitespaceColumn(this.getLines()[cursor.line] ?? ""), false);
+      return true;
+    }
+
     const wordMotion = this.resolveWordMotion(motion);
     if (wordMotion) {
       const lineLocalRange = this.tryWordMotionLineLocalRange(
@@ -1505,6 +1533,11 @@ export class ModalEditor extends CustomEditor {
       return true;
     }
 
+    if (motion === "^") {
+      this.yankRange(col, findFirstNonWhitespaceColumn(line), false);
+      return true;
+    }
+
     const wordMotion = this.resolveWordMotion(motion);
     if (wordMotion) {
       const lineLocalRange = this.tryWordMotionLineLocalRange(

package/motions.ts

@@ -30,6 +30,14 @@ function clampLineIndex(lines: readonly string[], lineIndex: number): number {
   return Math.max(0, Math.min(normalized, lines.length - 1));
 }
 
+/**
+ * Column of first non-whitespace char, or 0 for blank lines.
+ */
+export function findFirstNonWhitespaceColumn(line: string): number {
+  const match = line.search(/\S/);
+  return match === -1 ? 0 : match;
+}
+
 /**
  * True when line matches ^\s*$.
  */

package/package.json

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