pi-vim 0.1.9 → 0.2.1

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
 
@@ -41,27 +29,28 @@ Esc        # NORMAL mode
 3gg        # jump to absolute line 3
 2dw        # delete two words
 u          # undo
+<C-r>      # redo last undone edit (safe no-op when empty)
 2}         # jump two paragraphs forward
 ```
 
 Mode indicator (`INSERT` / `NORMAL`) appears at bottom-right.
 
-## 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` |
@@ -71,14 +60,15 @@ ex-commands, etc.).
 | Join 3 lines with spacing | `3J` |
 | Jump 2 paragraphs forward | `2}` |
 | Undo last edit | `u` |
+| Redo last undone edit | `<C-r>` |
 
 ---
 
-## 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) |
@@ -91,7 +81,7 @@ ex-commands, etc.).
 
 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    |
@@ -100,11 +90,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                         |
@@ -114,6 +104,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) |
@@ -146,11 +137,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)            |
@@ -164,17 +155,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)        |
@@ -187,6 +178,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)           |
@@ -201,11 +194,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  |
@@ -216,14 +209,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                                        |
@@ -231,14 +226,16 @@ 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`                     |
 | `{count}yy`  | `{count}` whole lines + trailing `\n`          |
@@ -254,6 +251,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)                     |
@@ -264,9 +263,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)  |
@@ -278,21 +277,22 @@ Line-wise detection: register content ending in `\n` is treated as line-wise.
 
 ---
 
-### Undo
-
-| Key | Action                                          |
-|-----|-------------------------------------------------|
-| `u` | Undo — sends `ctrl+_` (`\x1f`) to the underlying readline editor |
+### undo / redo
 
-Redo (`<C-r>`) is **not implemented** — see [Out of scope](#out-of-scope).
+| key | action |
+|-----|--------|
+| `u` | Undo in normal mode |
+| `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).
@@ -300,18 +300,18 @@ Redo (`<C-r>`) is **not implemented** — see [Out of scope](#out-of-scope).
 
 ---
 
-## 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                    |
 | `0` / `$` operators   | Exclusive of anchor col                | `0` inclusive of col 0        |
 | Undo depth            | Delegates to underlying readline undo  | Full per-change undo tree     |
-| Redo                  | Not implemented                        | `<C-r>`                       |
+| 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                     |
@@ -320,7 +320,7 @@ Redo (`<C-r>`) is **not implemented** — see [Out of scope](#out-of-scope).
 
 ---
 
-## Out of scope
+## out of scope
 
 These are **explicitly deferred** and not planned for this feature:
 
@@ -331,15 +331,17 @@ 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)
-- Redo (`<C-r>`) — no native redo primitive in the underlying readline editor;
-  deferred until a suitable hook is available.
+- No insert-mode `<C-r>` feature expansion beyond current underlying-editor behavior.
+- No cross-session redo persistence.
+- No upstream `pi-tui` redo prerequisite in this wave.
 - Window / tab / buffer management
 - Plugin / runtime ecosystem compatibility
 
 ---
 
-## Architecture notes
+## architecture notes
 
 - `index.ts` — `ModalEditor` subclass of `CustomEditor`; all key handling.
 - `motions.ts` — pure motion calculation helpers (`findWordMotionTarget`,