opencode-vim 0.0.18 → 0.0.20

package/README.md

@@ -22,7 +22,19 @@ opencode plugin opencode-vim@latest --global
 | `x`, `d`, `c`, `y`, `p`, `u`, `<C-r>` | Edit, yank, paste, undo, redo |
 | `v`, `V` | Visual and visual-line selection |
 | `3w`, `diw`, `ci"`, `yiq`, `dip`, `yib` | Counts and text objects |
-| `<CR>` in normal mode | Submit the prompt |
+| `k`, `j` on an empty prompt | Browse previous and next prompts |
+| `<CR>` in normal mode | Submit the prompt (configurable) |
 | `/vim` | Toggle Vim mode on or off |
 
-See [docs/configuration.md](./docs/configuration.md) for configuration options and keymap examples.
+## Custom Keymaps
+
+Keymaps can change modes, submit the prompt, run Vim key sequences, or dispatch active OpenCode commands with the `command:` prefix.
+
+```jsonc
+"normal": {
+  "Y": "y$",
+  "q": "command:session.new"
+}
+```
+
+See [Keymap Actions](./docs/keymap-actions.md) for available actions and commands, or [Configuration](./docs/configuration.md) for all options.

package/docs/configuration.md

@@ -246,12 +246,14 @@ Use an absolute path in config. `~` is not expanded inside `debugPath`.
 
 ### `keymaps`
 
-Custom keymaps for insert mode and normal mode.
+Custom keymaps for each Vim mode.
 
 Allowed modes:
 
 - `"insert"`
 - `"normal"`
+- `"visual"`
+- `"visual-line"`
 
 Each keymap entry maps a key sequence to an action:
 
@@ -272,6 +274,8 @@ Supported built-in actions:
 - `"insert"` enters insert mode.
 - `"submit"` submits the OpenCode prompt.
 
+Use `"command:<name>"` to dispatch an active OpenCode command. See [Keymap Actions](./keymap-actions.md) for the full action and command reference.
+
 Any other action string is treated as a Vim key sequence. For example, this maps `Y` to yank from the cursor to the end of the line:
 
 ```jsonc
@@ -282,6 +286,10 @@ Any other action string is treated as a Vim key sequence. For example, this maps
 }
 ```
 
+Unlike other keys, `<CR>` in normal mode defaults to `"submit"` when no mapping is configured. A mode-specific mapping overrides that default. In insert mode, an unmapped `<CR>` passes through to OpenCode's `input_submit` and `input_newline` keybinds.
+
+When `input_submit` is not `"return"`, map `input_newline` to `"return"` for insert-mode newlines.
+
 ## Keymap Syntax
 
 Key sequences can contain printable ASCII characters, except literal spaces. Use `<Space>` for the space key.
@@ -307,6 +315,8 @@ Supported special keys:
 
 Ctrl key names must be lowercase. Use `<C-s>`, not `<C-S>`.
 
+`<CR>` can be mapped directly or end a sequence, but cannot start a multi-key sequence.
+
 Unsupported examples:
 
 ```jsonc
@@ -331,7 +341,7 @@ Use `kj` or `jk` to leave insert mode:
 }
 ```
 
-Submit the prompt with Enter in normal mode:
+Submit with `<CR>` in normal mode is the default, so this keymap is optional:
 
 ```jsonc
 "keymaps": {
@@ -407,7 +417,7 @@ Use a leader-style sequence:
 
 If a keymap does not work, check these first:
 
-- The mode is either `insert` or `normal`.
+- The mode is `insert`, `normal`, `visual`, or `visual-line`.
 - The key sequence does not contain a literal space.
 - Special keys use one of the supported names exactly.
 - Ctrl keys use lowercase letters, such as `<C-s>`.

package/docs/keymap-actions.md

@@ -0,0 +1,213 @@
+# Keymap Actions
+
+Each keymap entry maps a key sequence to an action in one Vim mode:
+
+```jsonc
+"keymaps": {
+  "normal": {
+    "q": "command:session.new"
+  }
+}
+```
+
+## Modes
+
+| Mode | Keymaps apply while |
+| --- | --- |
+| `insert` | Typing text |
+| `normal` | Navigating and editing |
+| `visual` | Selecting characters |
+| `visual-line` | Selecting lines |
+
+All action types below can be configured in any mode.
+
+## Actions
+
+| Action | Behavior |
+| --- | --- |
+| `normal` | Enter normal mode |
+| `insert` | Enter insert mode |
+| `submit` | Submit the prompt |
+| `command:<name>` | Dispatch an active OpenCode command |
+| Any other string | Run it as a Vim key sequence, such as `y$` |
+
+An unmapped `<CR>` submits in normal mode and passes through to OpenCode in insert mode. `<CR>` can be mapped directly or end a sequence, but cannot start a multi-key sequence.
+
+## OpenCode Commands
+
+Command mappings use the command ID, not a slash command. For example, use `command:session.new`, not `command:/new`.
+
+Commands are provided by OpenCode and installed plugins. They may change between versions and only run when their UI context is active. The commands below are available from a focused prompt in the current OpenCode release.
+
+### Application
+
+| Command | Behavior |
+| --- | --- |
+| `command.palette.show` | Open the command palette |
+| `session.list` | Open the session list |
+| `session.new` | Start a new session |
+| `session.quick_switch.1` through `.9` | Switch to a numbered recent session |
+| `workspace.copy_path` | Copy the current worktree path |
+| `workspace.list` | Open workspace management |
+| `model.list` | Open model selection |
+| `model.cycle_recent` | Select the next recent model |
+| `model.cycle_recent_reverse` | Select the previous recent model |
+| `model.cycle_favorite` | Select the next favorite model |
+| `model.cycle_favorite_reverse` | Select the previous favorite model |
+| `agent.list` | Open agent selection |
+| `agent.cycle` | Select the next agent |
+| `agent.cycle.reverse` | Select the previous agent |
+| `mcp.list` | Open MCP management |
+| `variant.cycle` | Select the next model variant |
+| `variant.list` | Open variant selection |
+| `provider.connect` | Connect a provider |
+| `console.org.switch` | Switch organizations |
+| `opencode.status` | Open status information |
+| `opencode.debug` | Open debug information |
+| `theme.switch` | Select a theme |
+| `theme.switch_mode` | Toggle light and dark mode |
+| `theme.mode.lock` | Lock automatic theme changes |
+| `help.show` | Open help |
+| `docs.open` | Open OpenCode documentation |
+| `app.exit` | Exit OpenCode |
+| `app.debug` | Toggle the debug overlay |
+| `app.console` | Toggle the renderer console |
+| `app.heap_snapshot` | Write a heap snapshot |
+| `terminal.suspend` | Suspend OpenCode |
+| `terminal.title.toggle` | Toggle terminal title updates |
+| `app.toggle.animations` | Toggle TUI animations |
+| `app.toggle.file_context` | Toggle automatic file context |
+| `app.toggle.diffwrap` | Toggle diff wrapping |
+| `app.toggle.paste_summary` | Toggle pasted-text summaries |
+| `app.toggle.session_directory_filter` | Toggle session directory filtering |
+| `permission.mode` | Toggle permission auto-approval |
+
+### Prompt
+
+| Command | Behavior |
+| --- | --- |
+| `prompt.clear` | Clear the prompt |
+| `prompt.submit` | Submit the prompt |
+| `prompt.editor_context.clear` | Remove attached editor context |
+| `prompt.paste` | Paste clipboard text or an image |
+| `session.interrupt` | Interrupt the active session |
+| `prompt.editor` | Edit the prompt in an external editor |
+| `prompt.skills` | Open skill selection |
+| `workspace.set` | Switch workspace |
+| `session.move` | Move the session to another project |
+| `prompt.stash` | Stash and clear the prompt |
+| `prompt.stash.pop` | Restore the latest prompt stash |
+| `prompt.stash.list` | Open prompt stash selection |
+| `prompt.history.previous` | Load the previous prompt |
+| `prompt.history.next` | Load the next prompt |
+
+### Autocomplete
+
+These commands are active while prompt autocomplete is visible.
+
+| Command | Behavior |
+| --- | --- |
+| `prompt.autocomplete.prev` | Select the previous item |
+| `prompt.autocomplete.next` | Select the next item |
+| `prompt.autocomplete.hide` | Hide autocomplete |
+| `prompt.autocomplete.select` | Accept the selected item |
+| `prompt.autocomplete.complete` | Complete or expand the selected item |
+
+### Input
+
+These commands act on the focused prompt input.
+
+| Command | Behavior |
+| --- | --- |
+| `input.move.left` | Move left |
+| `input.move.right` | Move right |
+| `input.move.up` | Move up |
+| `input.move.down` | Move down |
+| `input.select.left` | Select left |
+| `input.select.right` | Select right |
+| `input.select.up` | Select up |
+| `input.select.down` | Select down |
+| `input.line.home` | Move to logical line start |
+| `input.line.end` | Move to logical line end |
+| `input.select.line.home` | Select to logical line start |
+| `input.select.line.end` | Select to logical line end |
+| `input.visual.line.home` | Move to visual line start |
+| `input.visual.line.end` | Move to visual line end |
+| `input.select.visual.line.home` | Select to visual line start |
+| `input.select.visual.line.end` | Select to visual line end |
+| `input.buffer.home` | Move to the start of the prompt |
+| `input.buffer.end` | Move to the end of the prompt |
+| `input.select.buffer.home` | Select to the start of the prompt |
+| `input.select.buffer.end` | Select to the end of the prompt |
+| `input.delete.line` | Delete the current line |
+| `input.delete.to.line.end` | Delete to line end |
+| `input.delete.to.line.start` | Delete to line start |
+| `input.backspace` | Delete backward |
+| `input.delete` | Delete forward |
+| `input.newline` | Insert a newline |
+| `input.undo` | Undo an edit |
+| `input.redo` | Redo an edit |
+| `input.word.forward` | Move forward one word |
+| `input.word.backward` | Move backward one word |
+| `input.select.word.forward` | Select forward one word |
+| `input.select.word.backward` | Select backward one word |
+| `input.delete.word.forward` | Delete forward one word |
+| `input.delete.word.backward` | Delete backward one word |
+| `input.select.all` | Select the entire prompt |
+| `input.submit` | Submit the prompt input |
+
+### Session
+
+These commands are active in a session.
+
+| Command | Behavior |
+| --- | --- |
+| `session.share` | Share the session or copy its URL |
+| `session.rename` | Rename the session |
+| `session.timeline` | Open the message timeline |
+| `session.fork` | Fork from the timeline |
+| `session.compact` | Summarize the session |
+| `session.unshare` | Stop sharing the session |
+| `session.undo` | Undo the latest user message |
+| `session.redo` | Redo an undone message |
+| `session.sidebar.toggle` | Toggle the session sidebar |
+| `session.toggle.conceal` | Toggle code concealment |
+| `session.toggle.timestamps` | Toggle message timestamps |
+| `session.toggle.thinking` | Toggle expanded thinking |
+| `session.toggle.actions` | Toggle tool action details |
+| `session.toggle.scrollbar` | Toggle the session scrollbar |
+| `session.toggle.generic_tool_output` | Toggle generic tool output |
+| `session.page.up` | Scroll up half a page |
+| `session.page.down` | Scroll down half a page |
+| `session.line.up` | Scroll up one line |
+| `session.line.down` | Scroll down one line |
+| `session.half.page.up` | Scroll up a quarter page |
+| `session.half.page.down` | Scroll down a quarter page |
+| `session.first` | Jump to the first message |
+| `session.last` | Jump to the last message |
+| `session.messages_last_user` | Jump to the latest user message |
+| `session.message.next` | Jump to the next message |
+| `session.message.previous` | Jump to the previous message |
+| `messages.copy` | Copy the latest assistant message |
+| `session.copy` | Copy the session transcript |
+| `session.export` | Export the session transcript |
+| `session.background` | Background active subagents |
+| `session.child.first` | Open the first child session |
+| `session.parent` | Open the parent session |
+| `session.child.next` | Open the next child session |
+| `session.child.previous` | Open the previous child session |
+
+### Plugins
+
+| Command | Behavior | Requirement |
+| --- | --- | --- |
+| `opencode-vim.toggle` | Toggle Vim mode | Always available |
+| `snippets.reload` | Reload snippets | Snippets plugin installed |
+| `snippets.insert` | Open snippet selection | Snippets plugin installed |
+| `snippets.accept` | Accept the active snippet field | Snippets plugin installed |
+| `plugins.list` | Open plugin management | Built-in plugin manager enabled |
+| `plugins.install` | Open plugin installation | Built-in plugin manager enabled |
+| `diff.open` | Open the diff viewer | Built-in diff viewer enabled |
+| `tips.toggle` | Toggle home-screen tips | Home screen visible |
+
+Other plugins can register additional commands. A command that is unavailable in the current context is ignored.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-vim",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "repository": {
     "type": "git",
     "url": "https://github.com/Tarquinen/opencode-vim"

package/src/modules/vim/index.tsx

@@ -7,6 +7,7 @@ import type { SnippetController } from "../snippets/types"
 import { applyVimCursorStyle, focusedInput } from "./actions"
 import type { VimConfig } from "./config"
 import { createVimConfig } from "./config"
+import { displayToChar } from "./map"
 import { keyNotation } from "./keys"
 import { createVimLog } from "./log"
 import type { VimLog } from "./log"
@@ -38,17 +39,9 @@ export function createVimModule(options?: unknown, enabled: Accessor<boolean> =
 function VimKeyboard(props: { ctx: PromptContext; config: VimConfig; state: ReturnType<typeof createVimState>; snippets?: SnippetController; enabled: Accessor<boolean>; log: VimLog }) {
     let cursorStyleMode = ""
     const vimee = createVimeeAdapter(props.state, props.config, props.log)
-    const preparedEvents = new WeakSet<KeyEvent>()
     props.log("keyboard.mount", { kind: props.ctx.kind })
 
     const cursorStyleTimer = setInterval(syncCursorStyle, 50)
-    const offKeyIntercept = props.ctx.api.keymap.intercept("key", ({ event }) => {
-        if (!canHandleKeys(props)) return
-        const key = keyNotation(event)
-        if (!key || !passThroughKey(event, key, props.state.mode())) return
-        if (preparePassThroughKey(props.ctx, key, props.state.mode())) preparedEvents.add(event)
-    }, { priority: 100 })
-
     const offKeyboard = props.ctx.api.keymap.intercept("key", ({ event }) => {
         props.log("keyboard.event", {
             name: event.name,
@@ -72,8 +65,10 @@ function VimKeyboard(props: { ctx: PromptContext; config: VimConfig; state: Retu
             return
         }
 
-        if (passThroughKey(event, key, props.state.mode())) {
-            if (!preparedEvents.delete(event)) preparePassThroughKey(props.ctx, key, props.state.mode())
+        if (passThroughKey(event, key, props.state.mode())) return
+
+        if (key === "<Esc>" && props.state.mode() === "normal" && !props.state.pending()) {
+            props.log("keyboard.fallthrough", { key, mode: props.state.mode() })
             return
         }
 
@@ -83,10 +78,17 @@ function VimKeyboard(props: { ctx: PromptContext; config: VimConfig; state: Retu
             return
         }
 
-        const consumed = vimee.handle(event, key, props.ctx)
+        const modeBefore = props.state.mode()
+        let consumed = false
+        try {
+            consumed = vimee.handle(event, key, props.ctx)
+        } finally {
+            if (consumed || props.state.mode() !== modeBefore) {
+                event.preventDefault()
+                event.stopPropagation()
+            }
+        }
         if (consumed) {
-            event.preventDefault()
-            event.stopPropagation()
             syncCursorStyle(true)
             props.ctx.requestRender()
         }
@@ -94,7 +96,6 @@ function VimKeyboard(props: { ctx: PromptContext; config: VimConfig; state: Retu
 
     onCleanup(() => {
         props.log("keyboard.cleanup", { kind: props.ctx.kind })
-        offKeyIntercept()
         offKeyboard()
         vimee.cleanup()
         clearInterval(cursorStyleTimer)
@@ -123,15 +124,7 @@ function readablePending(sequence: string) {
 
 function passThroughKey(event: KeyEvent, key: string, mode: string) {
     if (mode !== "normal") return false
-    return event.super === true || isArrowKey(key) || key === "<CR>" || key === "<C-c>"
-}
-
-function preparePassThroughKey(ctx: PromptContext, key: string, mode: string) {
-    if (mode !== "normal" || key !== "<CR>") return false
-    const input = focusedInput(ctx)
-    if (!input?.plainText || input.cursorOffset === undefined) return false
-    input.cursorOffset = Math.min(input.cursorOffset + 1, input.plainText.length)
-    return true
+    return event.super === true || isArrowKey(key) || key === "<C-c>"
 }
 
 function sendNavigationKey(event: KeyEvent, ctx: PromptContext, key: string, mode: string, snippets?: SnippetController) {
@@ -173,8 +166,8 @@ function isPromptFocused(ctx: PromptContext) {
 function isNativeCompletionToken(ctx: PromptContext) {
     const text = ctx.prompt()?.current.input ?? focusedInput(ctx)?.plainText ?? ""
     const input = focusedInput(ctx)
-    const offset = Math.max(0, input?.cursorOffset ?? text.length)
-    const beforeCursor = text.slice(0, Math.min(offset + 1, text.length))
+    const charIdx = displayToChar(text, Math.max(0, input?.cursorOffset ?? 0))
+    const beforeCursor = text.slice(0, Math.min(charIdx + 1, text.length))
     return /^\/\S*$/.test(beforeCursor) || /(?:^|\s)@\S*$/.test(beforeCursor)
 }
 

package/src/modules/vim/map.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test"
+import { charToDisplay, displayToChar, displayWidth } from "./map"
+
+describe("vim display offsets", () => {
+    test("maps ASCII and CJK offsets", () => {
+        const text = "a中b"
+
+        expect(displayWidth(text)).toBe(4)
+        expect(charToDisplay(text, 2)).toBe(3)
+        expect(displayToChar(text, 2)).toBe(1)
+        expect(displayToChar(text, 3)).toBe(2)
+    })
+
+    test("does not split supplementary characters", () => {
+        const text = "𠀀x"
+
+        expect(displayWidth(text)).toBe(3)
+        expect(charToDisplay(text, 1)).toBe(0)
+        expect(charToDisplay(text, 2)).toBe(2)
+        expect(displayToChar(text, 1)).toBe(0)
+        expect(displayToChar(text, 2)).toBe(2)
+    })
+
+    test("does not split grapheme clusters", () => {
+        const emoji = "👨‍👩‍👧‍👦"
+        const accent = "e\u0301"
+
+        expect(displayWidth(emoji)).toBe(2)
+        expect(charToDisplay(emoji, 1)).toBe(0)
+        expect(displayToChar(emoji, 1)).toBe(0)
+        expect(displayToChar(emoji, 2)).toBe(emoji.length)
+        expect(displayWidth(accent)).toBe(1)
+        expect(charToDisplay(accent, 1)).toBe(0)
+        expect(displayToChar(accent, 1)).toBe(accent.length)
+    })
+
+    test("counts newlines as textarea offsets", () => {
+        const text = "中\nx"
+
+        expect(displayWidth(text)).toBe(4)
+        expect(displayToChar(text, 2)).toBe(1)
+        expect(displayToChar(text, 3)).toBe(2)
+        expect(charToDisplay(text, 2)).toBe(3)
+    })
+})

package/src/modules/vim/map.ts

@@ -1,6 +1,37 @@
 import type { CursorPosition } from "@vimee/core"
 import type { EditBufferLike } from "./actions"
 
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" })
+
+function graphemeWidth(value: string) {
+    // Textarea offsets count newlines as one position; Bun.stringWidth counts them as zero.
+    return value === "\n" ? 1 : Bun.stringWidth(value)
+}
+
+export function charToDisplay(text: string, charIndex: number): number {
+    let width = 0
+    const limit = Math.max(0, Math.min(charIndex, text.length))
+    for (const part of graphemes.segment(text)) {
+        if (part.index + part.segment.length > limit) break
+        width += graphemeWidth(part.segment)
+    }
+    return width
+}
+
+export function displayToChar(text: string, displayOffset: number): number {
+    let width = 0
+    for (const part of graphemes.segment(text)) {
+        const next = width + graphemeWidth(part.segment)
+        if (next > displayOffset) return part.index
+        width = next
+    }
+    return text.length
+}
+
+export function displayWidth(text: string): number {
+    return charToDisplay(text, text.length)
+}
+
 export type PromptMap = {
     hostText: string
     vimText: string
@@ -37,12 +68,14 @@ function preserveSynthetic(vimOffset: number, prefix: number, suffix: number, vi
     return vimOffset !== prefix - 1 && vimOffset !== vimLength - suffix
 }
 
-export function hostPosition(map: PromptMap, hostOffset: number): CursorPosition {
-    return positionFromOffset(map.vimText, map.hostToVim[clamp(hostOffset, 0, map.hostText.length)] ?? 0)
+export function hostPosition(map: PromptMap, hostDisplayOffset: number): CursorPosition {
+    const charIdx = displayToChar(map.hostText, hostDisplayOffset)
+    return positionFromOffset(map.vimText, map.hostToVim[clamp(charIdx, 0, map.hostText.length)] ?? 0)
 }
 
 export function hostOffset(map: PromptMap, position: CursorPosition, bias: "previous" | "next" = "next") {
-    return hostOffsetFromVimOffset(map, offsetFromPosition(map.vimText, position), bias)
+    const charIdx = hostOffsetFromVimOffset(map, offsetFromPosition(map.vimText, position), bias)
+    return charToDisplay(map.hostText, charIdx)
 }
 
 function buildPromptMap(hostText: string, wraps: number[]): PromptMap {
@@ -99,14 +132,14 @@ function visualWrapOffsets(input: EditBufferLike, text: string) {
     const wraps: number[] = []
     let previousRow: number | undefined
 
-    for (let offset = 0; offset <= text.length; offset++) {
-        input.cursorOffset = offset
+    for (let charIdx = 0; charIdx <= text.length; charIdx++) {
+        input.cursorOffset = charToDisplay(text, charIdx)
         const row = input.visualCursor?.visualRow
         if (row === undefined) {
             wraps.length = 0
             break
         }
-        if (previousRow !== undefined && row > previousRow && text[offset - 1] !== "\n") wraps.push(offset)
+        if (previousRow !== undefined && row > previousRow && text[charIdx - 1] !== "\n") wraps.push(charIdx)
         previousRow = row
     }
 

package/src/modules/vim/state.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "bun:test"
+import { createVimState } from "./state"
+
+describe("vim state", () => {
+    test("isolates listener errors", () => {
+        const events: string[] = []
+        const state = createVimState("normal", (event) => events.push(event))
+        state.subscribe(() => {
+            throw new Error("stale renderable")
+        })
+        state.subscribe(() => events.push("listener.complete"))
+
+        expect(() => state.setMode("insert")).not.toThrow()
+        expect(state.mode()).toBe("insert")
+        expect(events).toContain("state.listener.error")
+        expect(events).toContain("listener.complete")
+    })
+})

package/src/modules/vim/state.ts

@@ -33,6 +33,12 @@ export function createVimState(defaultMode: VimMode, log: VimLog = () => {}) {
     }
 
     function notify() {
-        for (const listener of listeners) listener()
+        for (const listener of listeners) {
+            try {
+                listener()
+            } catch (error) {
+                log("state.listener.error", { error: error instanceof Error ? error.message : String(error) })
+            }
+        }
     }
 }

package/src/modules/vim/view.tsx

@@ -58,6 +58,8 @@ export function VimStatus(props: VimStatusProps) {
         unsubscribe()
         clearInterval(timer)
         if (pendingTimer) clearTimeout(pendingTimer)
+        modeText = undefined
+        pendingText = undefined
     })
 
     return (

package/src/modules/vim/vimee.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, test } from "bun:test"
+import type { KeyEvent } from "@opentui/core"
+import type { PromptContext } from "../../prompt/types"
+import { createVimConfig } from "./config"
+import type { VimLog } from "./log"
+import { createVimState, type VimMode } from "./state"
+import { createVimeeAdapter } from "./vimee"
+
+describe("vim command keymaps", () => {
+    test("does not restore stale cursor state after a normal command", () => {
+        const fixture = createFixture("normal", "command:test.run")
+        fixture.dispatch = () => {
+            fixture.input.plainText = "updated"
+            fixture.input.cursorOffset = 7
+        }
+
+        expect(fixture.handle()).toBe(true)
+        expect(fixture.commands).toEqual(["test.run"])
+        expect(fixture.input.cursorOffset).toBe(7)
+    })
+
+    test("uses the host history boundary and restores display width", () => {
+        const fixture = createFixture("normal", "command:prompt.history.next", "中")
+        let boundary = -1
+        fixture.dispatch = () => {
+            boundary = fixture.input.cursorOffset
+            fixture.input.plainText = "中中"
+            fixture.input.cursorOffset = 2
+        }
+
+        expect(fixture.handle()).toBe(true)
+        expect(boundary).toBe(1)
+        expect(fixture.input.cursorOffset).toBe(4)
+    })
+
+    test("dispatches commands in insert mode", () => {
+        const fixture = createFixture("insert", "command:test.run")
+
+        expect(fixture.handle()).toBe(true)
+        expect(fixture.commands).toEqual(["test.run"])
+    })
+
+    test("rejects an empty command name", () => {
+        const logs: Array<[string, unknown]> = []
+        createFixture("normal", "command:   ", "", (event, data) => logs.push([event, data]))
+
+        expect(logs.some(([event]) => event === "vimee.keymap.invalid")).toBe(true)
+    })
+})
+
+describe("vim enter keymaps", () => {
+    test("submits unmapped Enter in normal mode without moving the cursor", () => {
+        const fixture = createFixture("normal", undefined, "中")
+        fixture.input.cursorOffset = 2
+
+        expect(fixture.handle("<CR>")).toBe(true)
+        expect(fixture.submissions).toHaveLength(1)
+        expect(fixture.input.cursorOffset).toBe(2)
+    })
+
+    test("passes unmapped Enter through in insert mode", () => {
+        const fixture = createFixture("insert", undefined)
+
+        expect(fixture.handle("<CR>")).toBe(false)
+        expect(fixture.submissions).toHaveLength(0)
+    })
+
+    test("does not submit a matched mapping with no immediate actions", () => {
+        const fixture = createFixture("normal", "d", "text", () => {}, "<CR>")
+
+        expect(fixture.handle("<CR>")).toBe(true)
+        expect(fixture.submissions).toHaveLength(0)
+    })
+
+    test("runs an Enter command mapping", () => {
+        const fixture = createFixture("normal", "command:test.run", "", () => {}, "<CR>")
+
+        expect(fixture.handle("<CR>")).toBe(true)
+        expect(fixture.commands).toEqual(["test.run"])
+        expect(fixture.submissions).toHaveLength(0)
+    })
+
+    test("applies mode and submit mappings", () => {
+        const normal = createFixture("normal", "insert", "", () => {}, "<CR>")
+        const insert = createFixture("insert", "submit", "", () => {}, "<CR>")
+
+        expect(normal.handle("<CR>")).toBe(true)
+        expect(normal.handle("a")).toBe(false)
+        expect(insert.handle("<CR>")).toBe(true)
+        expect(insert.submissions).toHaveLength(1)
+    })
+
+    test("allows Enter to finish a multi-key mapping", () => {
+        const fixture = createFixture("normal", "command:test.run", "", () => {}, "g<CR>")
+
+        expect(fixture.handle("g")).toBe(true)
+        expect(fixture.handle("<CR>")).toBe(true)
+        expect(fixture.commands).toEqual(["test.run"])
+        expect(fixture.submissions).toHaveLength(0)
+    })
+
+    test("rejects mappings that defer Enter", () => {
+        const logs: Array<[string, unknown]> = []
+        const fixture = createFixture("normal", "command:test.run", "", (event, data) => logs.push([event, data]), "<CR>x")
+
+        expect(fixture.handle("<CR>")).toBe(true)
+        expect(fixture.submissions).toHaveLength(1)
+        expect(logs.some(([event]) => event === "vimee.keymap.invalid")).toBe(true)
+    })
+})
+
+describe("vim prompt history", () => {
+    test("starts from an empty prompt and continues through history", () => {
+        const fixture = createFixture("normal", undefined, "")
+        const entries = ["newest", "older", ""]
+        fixture.dispatch = (command) => {
+            fixture.input.plainText = entries.shift() ?? ""
+            fixture.input.cursorOffset = command === "prompt.history.previous" ? 0 : fixture.input.plainText.length
+        }
+
+        expect(fixture.handle("k")).toBe(true)
+        expect(fixture.handle("k")).toBe(true)
+        expect(fixture.handle("j")).toBe(true)
+        expect(fixture.commands).toEqual([
+            "prompt.history.previous",
+            "prompt.history.previous",
+            "prompt.history.next",
+        ])
+    })
+
+    test("keeps normal movement for a nonempty prompt", () => {
+        const fixture = createFixture("normal", undefined, "text")
+
+        expect(fixture.handle("k")).toBe(true)
+        expect(fixture.handle("j")).toBe(true)
+        expect(fixture.commands).toEqual([])
+    })
+
+    test("stops history navigation after another normal key", () => {
+        const fixture = createFixture("normal", undefined, "")
+        fixture.dispatch = () => {
+            fixture.input.plainText = "recalled"
+        }
+
+        expect(fixture.handle("k")).toBe(true)
+        expect(fixture.handle("h")).toBe(true)
+        expect(fixture.handle("k")).toBe(true)
+        expect(fixture.commands).toEqual(["prompt.history.previous"])
+    })
+
+    test("prefers configured keymaps", () => {
+        const fixture = createFixture("normal", "command:test.run", "", () => {}, "k")
+
+        expect(fixture.handle()).toBe(true)
+        expect(fixture.commands).toEqual(["test.run"])
+    })
+
+    test("completes a pending keymap before history navigation", () => {
+        const fixture = createFixture("normal", "command:test.run", "", () => {}, "gk")
+
+        expect(fixture.handle("g")).toBe(true)
+        expect(fixture.handle("k")).toBe(true)
+        expect(fixture.commands).toEqual(["test.run"])
+    })
+})
+
+function createFixture(mode: VimMode, action: string | undefined, text = "text", log: VimLog = () => {}, mappedKey = "Q") {
+    const input = {
+        plainText: text,
+        cursorOffset: 0,
+        visualCursor: { visualRow: 0, visualCol: 0, offset: 0 },
+        moveCursorLeft: () => false,
+    }
+    const commands: string[] = []
+    const submissions: true[] = []
+    const prompt = {
+        current: { input: text, mode: "normal", parts: [] },
+        set() {},
+        submit() {
+            submissions.push(true)
+        },
+        blur() {},
+    }
+    const fixture = {
+        input,
+        commands,
+        submissions,
+        dispatch: (_command: string) => {},
+        handle: (key = mappedKey) => adapter.handle({ name: key } as KeyEvent, key, ctx),
+    }
+    const ctx = {
+        api: {
+            renderer: { currentFocusedRenderable: input },
+            keymap: {
+                dispatchCommand(command: string) {
+                    commands.push(command)
+                    fixture.dispatch(command)
+                    return { ok: true as const }
+                },
+            },
+        },
+        prompt: () => prompt,
+        requestRender() {},
+    } as unknown as PromptContext
+    const config = createVimConfig({
+        defaultMode: mode,
+        keymaps: action ? { [mode]: { [mappedKey]: action } } : undefined,
+    })
+    const adapter = createVimeeAdapter(createVimState(mode), config, log)
+    return fixture
+}

package/src/modules/vim/vimee.ts

@@ -5,13 +5,13 @@ import type { PromptContext } from "../../prompt/types"
 import { focusedInput, setInput, type EditBufferLike } from "./actions"
 import type { VimConfig } from "./config"
 import type { VimLog } from "./log"
-import { createPromptMap, derivePromptMap, hostOffset, hostPosition, type PromptMap } from "./map"
+import { charToDisplay, displayToChar, displayWidth, createPromptMap, derivePromptMap, hostOffset, hostPosition, type PromptMap } from "./map"
 import type { createVimState } from "./state"
 
 type VimState = ReturnType<typeof createVimState>
-type HostAction = VimeeAction | { type: "submit" }
-type HostKeybindAction = "normal" | "submit"
-type HostKeybindDefinition = KeybindDefinition & { hostAction?: HostKeybindAction }
+type HostAction = VimeeAction | { type: "submit" } | { type: "command"; command: string }
+type HostKeybindAction = "normal" | "submit" | "command"
+type HostKeybindDefinition = KeybindDefinition & { hostAction?: HostKeybindAction; command?: string }
 type HostRange = { start: number; end: number }
 
 const YANK_FLASH_MS = 250
@@ -29,6 +29,11 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
     let yankFlashActive = false
     let pendingInsert = ""
     let nativeInsertUndoSaved = false
+    let historyText: string | undefined
+    const defaultHistoryKeys = {
+        k: !hasNormalKeyPrefix(config, "k"),
+        j: !hasNormalKeyPrefix(config, "j"),
+    }
 
     return {
         handle(event: KeyEvent, key: string, ctx: PromptContext) {
@@ -38,16 +43,7 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
             let vimeeKey = keyForVimee(event, key)
             if (!vimeeKey) return false
 
-            if (state.mode() === "normal" && key === "<CR>") {
-                ref.submit()
-                return true
-            }
-
             if (state.mode() === "insert") {
-                if (key === "<CR>") {
-                    cancelPendingInsert(ctx)
-                    return false
-                }
                 if (vimeeKey === "Escape") {
                     cancelPendingInsert(ctx, undefined, false)
                     enterNormal(ctx)
@@ -61,10 +57,24 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
 
             const input = focusedInput(ctx)
             const text = input?.plainText ?? ref.current.input
-            const offset = clamp(input?.cursorOffset ?? text.length, 0, text.length)
+            const dw = displayWidth(text)
+            const displayOff = clamp(input?.cursorOffset ?? dw, 0, dw)
+            const charOff = displayToChar(text, displayOff)
+
+            const canBrowseHistory = vim.phase === "idle" && vim.count === 0 && !keybinds?.isPending()
+            const historyCommand = canBrowseHistory ? defaultHistoryCommand(vimeeKey, text, historyText, defaultHistoryKeys) : undefined
+            if (historyCommand) {
+                const result = dispatchCommand(historyCommand, ctx)
+                historyText = result.ok ? (focusedInput(ctx)?.plainText ?? ref.current.input) : undefined
+                state.setPending("")
+                updateTimeout(ctx)
+                log("vimee.history", { key, command: historyCommand, handled: result.ok })
+                return true
+            }
+            historyText = undefined
 
             const map = mapForHostText(text, input)
-            const cursor = hostPosition(map, offset)
+            const cursor = hostPosition(map, displayOff)
 
             const wasPending = keybinds?.isPending() ?? false
             const pendingBefore = pendingInsert
@@ -77,35 +87,60 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
                 return true
             }
 
-            const hostEnd = vimeeKey === "e" ? endMotionOffset(map.hostText, offset, vim.count || 1) : undefined
+            const hostEnd = vimeeKey === "e" ? endMotionOffset(map.hostText, charOff, vim.count || 1) : undefined
             const shouldFlashYank = shouldFlashYankFor(vimeeKey)
             const visualYankRange = visualYankRangeFor(map)
             vimeeKey = textObjectAlias(vimeeKey, vim) ?? vimeeKey
             const textObjectHandled = handleTextObject(vimeeKey, ctx, map)
             if (textObjectHandled !== undefined) return textObjectHandled
-            const result = processKeystroke(vimeeKey, vim, buffer, event.ctrl, false, keybinds)
+            const resolved = keybinds?.resolve(vimeeKey, vim.mode, event.ctrl)
+            if (resolved?.status === "pending") {
+                vim = { ...vim, statusMessage: resolved.display }
+                state.setPending(resolved.display)
+                updateTimeout(ctx)
+                log("vimee.key", { key, vimeeKey, mode: vim.mode, phase: vim.phase, cursor: vim.cursor, actions: [] })
+                return true
+            }
+            if (vimeeKey === "Enter" && state.mode() === "normal" && vim.phase === "idle" && !wasPending && resolved?.status !== "matched") {
+                ref.submit()
+                state.setPending("")
+                updateTimeout(ctx)
+                log("vimee.key", { key, vimeeKey, mode: vim.mode, phase: vim.phase, cursor: vim.cursor, actions: ["submit"] })
+                return true
+            }
+
+            let result
+            if (resolved?.status === "matched") {
+                const actions = applyKeybind(resolved.definition, map)
+                result = { newCtx: vim, actions }
+            } else {
+                result = processKeystroke(vimeeKey, vim, buffer, event.ctrl, false)
+            }
             vim = result.newCtx
-            if (hostEnd !== undefined && result.actions.every((action) => action.type === "cursor-move") && hostEnd > hostOffset(map, vim.cursor, "previous")) vim = { ...vim, cursor: hostPosition(map, hostEnd) }
+            const actions = result.actions as HostAction[]
+            if (hostEnd !== undefined && actions.every((action) => action.type === "cursor-move") && hostEnd > hostOffset(map, vim.cursor, "previous")) vim = { ...vim, cursor: hostPosition(map, hostEnd) }
             let clampFinalCursor = true
-            const content = result.actions.find((action) => action.type === "content-change")?.content
+            const content = actions.find((action) => action.type === "content-change")?.content
             if (vimeeKey === "x" && content !== undefined) {
                 const next = nextMap(map, content)
-                const target = clamp(offset, 0, Math.max(0, next.hostText.length - 1))
-                if (offset < map.hostText.length - 1 && map.hostText[offset + 1] !== "\n" && hostOffset(next, vim.cursor, "previous") < target) {
+                const nextDW = displayWidth(next.hostText)
+                const target = clamp(displayOff, 0, Math.max(0, nextDW - 1))
+                if (charOff < map.hostText.length - 1 && map.hostText[charOff + 1] !== "\n" && hostOffset(next, vim.cursor, "previous") < target) {
                     vim = { ...vim, cursor: hostPosition(next, target) }
                     clampFinalCursor = false
                 }
             }
-            applyActions(result.actions as HostAction[], ctx, map, clampFinalCursor)
-            if (shouldFlashYank) flashYank(ctx, activeMap, yankAction(result.actions), visualYankRange)
+            applyActions(actions, ctx, map, clampFinalCursor)
+            if (shouldFlashYank) flashYank(ctx, activeMap, yankAction(actions), visualYankRange)
             syncMode(state, vim.mode)
+
             const keybindPending = keybinds?.isPending() ?? false
-            if (wasPending && !keybindPending && pendingBefore && state.mode() === "insert") flushPendingInsert(ctx, pendingBefore, offset)
+            if (wasPending && !keybindPending && pendingBefore && state.mode() === "insert") flushPendingInsert(ctx, pendingBefore, charOff)
             pendingInsert = keybindPending && state.mode() === "insert" ? plainPending(vim.statusMessage) : ""
             state.setPending(pendingDisplay(vim, keybindPending))
             updateTimeout(ctx)
-            log("vimee.key", { key, vimeeKey, mode: vim.mode, phase: vim.phase, cursor: vim.cursor, actions: result.actions.map((action) => action.type) })
-            return consumesKey(vimeeKey, result.actions, vim, keybindPending)
+            log("vimee.key", { key, vimeeKey, mode: vim.mode, phase: vim.phase, cursor: vim.cursor, actions: actions.map((action) => action.type) })
+            return consumesKey(vimeeKey, actions, vim, keybindPending)
         },
         cleanup() {
             if (timer) clearTimeout(timer)
@@ -175,6 +210,9 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
                 case "submit":
                     ref.submit()
                     break
+                case "command":
+                    dispatchCommand(action.command, ctx)
+                    return
             }
         }
 
@@ -228,6 +266,9 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
             case "submit":
                 ctx.prompt()?.submit()
                 return true
+            case "command":
+                dispatchCommand((definition as HostKeybindDefinition).command!, ctx)
+                return true
             default:
                 return false
         }
@@ -237,9 +278,10 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
         const ref = ctx.prompt()
         const input = focusedInput(ctx)
         const text = input?.plainText ?? ref?.current.input ?? ""
-        const offset = clamp(input?.cursorOffset ?? text.length, 0, text.length)
 
         if (input && text.length > 0) {
+            const dw = displayWidth(text)
+            const offset = clamp(input?.cursorOffset ?? dw, 0, dw)
             input.cursorOffset = Math.max(0, offset - 1)
             clampNormalCursor(input)
         }
@@ -329,18 +371,19 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
         state.setPending("")
     }
 
-    function flushPendingInsert(ctx: PromptContext, value: string, offset?: number) {
+    function flushPendingInsert(ctx: PromptContext, value: string, charOffset?: number) {
         if (!value || state.mode() !== "insert") return
         const ref = ctx.prompt()
         if (!ref) return
         const input = focusedInput(ctx)
         const text = input?.plainText ?? ref.current.input
-        const insertAt = clamp(offset ?? input?.cursorOffset ?? text.length, 0, text.length)
-        const currentOffset = input?.cursorOffset ?? insertAt
-        const next = text.slice(0, insertAt) + value + text.slice(insertAt)
+        const currentDisplayOff = input?.cursorOffset ?? 0
+        const currentCharOff = displayToChar(text, currentDisplayOff)
+        const insertAtChar = charOffset ?? currentCharOff
+        const next = text.slice(0, insertAtChar) + value + text.slice(insertAtChar)
         setInput(ref, next)
-        const nextOffset = currentOffset >= insertAt ? currentOffset + value.length : currentOffset
-        if (input) input.cursorOffset = nextOffset
+        const nextCharOff = currentCharOff >= insertAtChar ? currentCharOff + value.length : currentCharOff
+        if (input) input.cursorOffset = displayWidth(next.slice(0, nextCharOff))
     }
 
     function cursorOffset(map: PromptMap, position: CursorPosition) {
@@ -357,7 +400,7 @@ export function createVimeeAdapter(state: VimState, config: VimConfig, log: VimL
         if (!input?.gotoVisualLineEnd) return false
         clearVisualSelection(input)
         input.gotoVisualLineEnd()
-        vim = { ...vim, cursor: hostPosition(map, input.cursorOffset ?? map.hostText.length), mode: "insert", phase: "idle", count: 0, operator: null, statusMessage: "-- INSERT --" }
+        vim = { ...vim, cursor: hostPosition(map, input.cursorOffset ?? displayWidth(map.hostText)), mode: "insert", phase: "idle", count: 0, operator: null, statusMessage: "-- INSERT --" }
         nativeInsertUndoSaved = false
         syncMode(state, "insert")
         return true
@@ -457,14 +500,15 @@ function vimOffsetRange(map: PromptMap, left: number, right: number): HostRange
 
 function hostRange(map: PromptMap, left: number, right: number): HostRange | undefined {
     if (!map.hostText) return undefined
-    const start = clamp(Math.min(left, right), 0, Math.max(0, map.hostText.length - 1))
-    const end = clamp(Math.max(left, right), 0, Math.max(0, map.hostText.length - 1))
+    const dw = displayWidth(map.hostText)
+    const start = clamp(Math.min(left, right), 0, Math.max(0, dw - 1))
+    const end = clamp(Math.max(left, right), 0, Math.max(0, dw - 1))
     return { start, end }
 }
 
 type YankAction = Extract<VimeeAction, { type: "yank" }>
 
-function yankAction(actions: VimeeAction[]): YankAction | undefined {
+function yankAction(actions: HostAction[]): YankAction | undefined {
     return actions.find((action): action is YankAction => action.type === "yank")
 }
 
@@ -521,32 +565,71 @@ function vimOffsetFromPosition(text: string, position: CursorPosition) {
 
 function hostFromVimOffset(map: PromptMap, offset: number, bias: "previous" | "next") {
     const current = clamp(offset, 0, map.vimText.length)
-    if (current === map.vimText.length) return map.hostText.length
+    if (current === map.vimText.length) return displayWidth(map.hostText)
 
     const host = map.vimToHost[current]
-    if (host !== undefined) return host
+    if (host !== undefined) return charToDisplay(map.hostText, host)
 
     if (bias === "previous") {
         for (let previous = current - 1; previous >= 0; previous--) {
             const previousHost = map.vimToHost[previous]
-            if (previousHost !== undefined) return previousHost
+            if (previousHost !== undefined) return charToDisplay(map.hostText, previousHost)
         }
     }
 
     for (let next = current + 1; next < map.vimToHost.length; next++) {
         const nextHost = map.vimToHost[next]
-        if (nextHost !== undefined) return nextHost
+        if (nextHost !== undefined) return charToDisplay(map.hostText, nextHost)
     }
-    return map.hostText.length
+    return displayWidth(map.hostText)
 }
 
 function clampNormalCursor(input: EditBufferLike) {
     const cursor = input.visualCursor
-    const eol = input.editorView?.getVisualEOL?.()
     const offset = input.cursorOffset
-    if (!cursor || !eol || offset === undefined) return
+    const text = input.plainText
+    if (!cursor || offset === undefined || text === undefined) return
     if (cursor.visualCol === 0) return
-    if (cursor.visualRow === eol.visualRow && (cursor.offset === eol.offset || offset === eol.offset)) input.cursorOffset = Math.max(0, offset - 1)
+    const dw = displayWidth(text)
+    if (offset >= dw) {
+        input.cursorOffset = Math.max(0, dw - 1)
+        return
+    }
+    const charIdx = displayToChar(text, offset)
+    if (charIdx < text.length && text[charIdx] === '\n') {
+        input.cursorOffset = Math.max(0, offset - 1)
+    }
+}
+
+function dispatchCommand(command: string, ctx: PromptContext) {
+    const input = focusedInput(ctx)
+    if (command === "prompt.history.previous" && input) input.cursorOffset = 0
+    if (command === "prompt.history.next" && input) input.cursorOffset = input.plainText?.length ?? 0
+
+    const result = ctx.api.keymap.dispatchCommand(command)
+
+    // The host currently checks history-next using character length, then leaves
+    // the cursor in that unit. Restore the display-width offset after dispatch.
+    if (command !== "prompt.history.next" || !result.ok) return result
+    const nextInput = focusedInput(ctx)
+    if (nextInput?.plainText !== undefined) nextInput.cursorOffset = displayWidth(nextInput.plainText)
+    return result
+}
+
+function defaultHistoryCommand(key: string, text: string, historyText: string | undefined, enabled: Record<"j" | "k", boolean>) {
+    if (key !== "j" && key !== "k") return
+    if (!enabled[key]) return
+    if (text.length > 0 && text !== historyText) return
+    return key === "k" ? "prompt.history.previous" : "prompt.history.next"
+}
+
+function hasNormalKeyPrefix(config: VimConfig, key: "j" | "k") {
+    for (const sequence of Object.keys(config.keymaps.normal ?? {})) {
+        try {
+            if (keyToken(parseKeySequence(sequence)[0] ?? "") === key) return true
+        } catch {}
+    }
+    return false
 }
 
 function endMotionOffset(text: string, offset: number, count: number) {
@@ -578,6 +661,8 @@ function createKeybinds(config: VimConfig, log: VimLog): KeybindMap | undefined
         if (!keymaps) continue
         for (const [keys, action] of Object.entries(keymaps)) {
             try {
+                const tokens = parseKeySequence(keys)
+                if (tokens.length > 1 && tokens[0] === "<CR>") throw new Error("<CR> cannot start a multi-key mapping")
                 map.addKeybind(mode, keys as ValidKeySequence<typeof keys>, keybindAction(action))
                 count++
             } catch (error) {
@@ -590,6 +675,15 @@ function createKeybinds(config: VimConfig, log: VimLog): KeybindMap | undefined
 }
 
 function keybindAction(action: string): HostKeybindDefinition {
+    if (action.startsWith("command:")) {
+        const command = action.slice(8).trim()
+        if (!command) throw new Error("Command name is required")
+        return {
+            execute: () => [{ type: "command", command } as unknown as VimeeAction],
+            hostAction: "command",
+            command,
+        }
+    }
     switch (action) {
         case "normal":
             return { keys: "<Esc>", hostAction: "normal" }
@@ -644,7 +738,7 @@ function plainPending(value: string) {
     return value.includes("<") || value.includes(">") ? "" : value
 }
 
-function consumesKey(key: string, actions: VimeeAction[], ctx: VimContext, keybindPending: boolean) {
+function consumesKey(key: string, actions: HostAction[], ctx: VimContext, keybindPending: boolean) {
     if (actions.length > 0) return true
     if (keybindPending) return true
     if (ctx.phase !== "idle") return true