pi-vim 0.8.0 → 0.10.0

package/index.ts

@@ -1,9 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
 
-import {
-  CustomEditor,
-  type ExtensionAPI,
-} from "@mariozechner/pi-coding-agent";
+import { CustomEditor, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import {
   CURSOR_MARKER,
   Key,
@@ -11,55 +8,54 @@ import {
   truncateToWidth,
   visibleWidth,
 } from "@mariozechner/pi-tui";
-
+import {
+  type ClipboardMirrorPolicy,
+  DEFAULT_CLIPBOARD_MIRROR_POLICY,
+  type RegisterWriteSource,
+  resolveClipboardMirrorPolicy,
+} from "./clipboard-policy.js";
+import {
+  findCharMotionTarget,
+  findFirstNonWhitespaceColumn,
+  findParagraphMotionTarget,
+  getLineGraphemes,
+  reverseCharMotion,
+  type WordMotionClass,
+} from "./motions.js";
+import { type ModeColorSettings, readPiVimSettings } from "./settings.js";
+import {
+  resolveDelimitedTextObjectRange,
+  resolveWordTextObjectRange,
+  type TextObjectKind,
+  type TextObjectRange,
+  type WordTextObjectClass,
+} from "./text-objects.js";
 import type {
-  Mode,
   CharMotion,
+  LastCharMotion,
+  Mode,
   PendingMotion,
   PendingOperator,
-  LastCharMotion,
 } from "./types.js";
 import {
-  NORMAL_KEYS,
   CHAR_MOTION_KEYS,
-  ESC_LEFT,
-  ESC_RIGHT,
-  ESC_UP,
   CTRL_A,
   CTRL_E,
   CTRL_K,
   CTRL_R,
   CTRL_UNDERSCORE,
-  NEWLINE,
   ESC_DOWN,
+  ESC_LEFT,
+  ESC_RIGHT,
+  ESC_UP,
+  NEWLINE,
+  NORMAL_KEYS,
 } from "./types.js";
-import {
-  reverseCharMotion,
-  findCharMotionTarget,
-  findParagraphMotionTarget,
-  findFirstNonWhitespaceColumn,
-  getLineGraphemes,
-  type WordMotionClass,
-} from "./motions.js";
 import {
   WordBoundaryCache,
   type WordMotionDirection,
   type WordMotionTarget,
 } from "./word-boundary-cache.js";
-import {
-  DEFAULT_CLIPBOARD_MIRROR_POLICY,
-  readPiVimSettings,
-  resolveClipboardMirrorPolicy,
-  type ClipboardMirrorPolicy,
-  type RegisterWriteSource,
-} from "./clipboard-policy.js";
-import {
-  resolveDelimitedTextObjectRange,
-  resolveWordTextObjectRange,
-  type TextObjectKind,
-  type TextObjectRange,
-  type WordTextObjectClass,
-} from "./text-objects.js";
 
 const BRACKETED_PASTE_START = "\x1b[200~";
 const BRACKETED_PASTE_END = "\x1b[201~";
@@ -71,12 +67,16 @@ const SOFTWARE_CURSOR_RESETS = ["\x1b[0m", "\x1b[27m"] as const;
 const INSERT_CURSOR_SHAPE = "\x1b[5 q";
 const BLOCK_CURSOR_SHAPE = "\x1b[1 q";
 const RESET_CURSOR_SHAPE = "\x1b[0 q";
-// Pi emits OSC52 before its native clipboard fallback. Give that 5s fallback
-// a small grace so the parent does not kill the helper and discard stdout.
 const CLIPBOARD_WRITE_TIMEOUT_MS = PI_NATIVE_CLIPBOARD_TIMEOUT_MS + 500;
 const CLIPBOARD_SPAWN_FAILURE_LIMIT = 3;
 const CLIPBOARD_READ_TIMEOUT_MS = 750;
 const CLIPBOARD_READ_MAX_BUFFER_BYTES = 1024 * 1024;
+const MODE_COLORS = {
+  insert: "borderMuted",
+  normal: "borderAccent",
+  ex: "warning",
+} as const;
+const TOKEN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 
 type EditorSnapshot = {
   text: string;
@@ -101,11 +101,13 @@ type ClipboardWriteFn = (text: string, signal: AbortSignal) => Promise<void>;
 type ClipboardReadFn = () => string | null;
 type ClipboardProcess = ReturnType<typeof spawn>;
 
-type ModeLabelColorizers = {
-  insert: (s: string) => string;
-  normal: (s: string) => string;
-  ex: (s: string) => string;
+type ModeColorKey = keyof typeof MODE_COLORS;
+type ModeColorizers = Record<ModeColorKey, (s: string) => string>;
+type ModalEditorOptions = {
+  labelColorizers?: ModeColorizers | null;
+  borderColorizers?: ModeColorizers | null;
 };
+type ThemeLike = { fg(token: string, text: string): string };
 
 type CursorShapeSequence =
   | typeof INSERT_CURSOR_SHAPE
@@ -120,6 +122,45 @@ type CursorShapeRuntime = {
 
 type CursorShapeCleanup = () => void;
 
+function resolveModeColors(
+  colors?: ModeColorSettings,
+): Required<ModeColorSettings> {
+  return {
+    insert: colors?.insert ?? MODE_COLORS.insert,
+    normal: colors?.normal ?? MODE_COLORS.normal,
+    ex: colors?.ex ?? MODE_COLORS.ex,
+  };
+}
+function colorizeWithTheme(
+  theme: ThemeLike,
+  token: string,
+  fallback: string,
+  text: string,
+): string {
+  const trimmedToken = token.trim();
+  if (TOKEN.test(trimmedToken)) {
+    try {
+      return theme.fg(trimmedToken, text);
+    } catch {
+      return theme.fg(fallback, text);
+    }
+  }
+  return theme.fg(fallback, text);
+}
+function buildModeColorizers(
+  theme: ThemeLike,
+  colors: Required<ModeColorSettings>,
+  transform: (text: string) => string = (text) => text,
+): ModeColorizers {
+  const colorizer = (mode: ModeColorKey) => (text: string) =>
+    colorizeWithTheme(theme, colors[mode], MODE_COLORS[mode], transform(text));
+  return {
+    insert: colorizer("insert"),
+    normal: colorizer("normal"),
+    ex: colorizer("ex"),
+  };
+}
+
 type CursorShapeTuiCandidate = {
   terminal?: { write?: unknown };
   setShowHardwareCursor?: unknown;
@@ -135,7 +176,10 @@ function getCursorShapeRuntime(tui: unknown): CursorShapeRuntime | null {
 
   const write = terminal.write;
   const setShowHardwareCursor = candidate.setShowHardwareCursor;
-  if (typeof write !== "function" || typeof setShowHardwareCursor !== "function") {
+  if (
+    typeof write !== "function" ||
+    typeof setShowHardwareCursor !== "function"
+  ) {
     return null;
   }
 
@@ -178,7 +222,10 @@ function findSoftwareCursorReset(
   line: string,
   startIndex: number,
 ): { index: number; sequence: (typeof SOFTWARE_CURSOR_RESETS)[number] } | null {
-  let firstReset: { index: number; sequence: (typeof SOFTWARE_CURSOR_RESETS)[number] } | null = null;
+  let firstReset: {
+    index: number;
+    sequence: (typeof SOFTWARE_CURSOR_RESETS)[number];
+  } | null = null;
 
   for (const sequence of SOFTWARE_CURSOR_RESETS) {
     const index = line.indexOf(sequence, startIndex);
@@ -203,9 +250,11 @@ function stripSoftwareCursorAfterMarker(line: string): string {
   const reset = findSoftwareCursorReset(line, cursorContentStart);
   if (!reset) return line;
 
-  return line.slice(0, cursorStart)
-    + line.slice(cursorContentStart, reset.index)
-    + line.slice(reset.index + reset.sequence.length);
+  return (
+    line.slice(0, cursorStart) +
+    line.slice(cursorContentStart, reset.index) +
+    line.slice(reset.index + reset.sequence.length)
+  );
 }
 
 type ClipboardCircuitBreaker = {
@@ -236,17 +285,21 @@ function isNodeSpawnErrno(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
 
   const candidate = error as SpawnErrnoLike;
-  return typeof candidate.code === "string"
-    && candidate.code.length > 0
-    && typeof candidate.syscall === "string"
-    && candidate.syscall.startsWith("spawn");
+  return (
+    typeof candidate.code === "string" &&
+    candidate.code.length > 0 &&
+    typeof candidate.syscall === "string" &&
+    candidate.syscall.startsWith("spawn")
+  );
 }
 
 function isClipboardEnvironmentFailure(error: unknown): boolean {
   return error instanceof ClipboardSpawnError || isNodeSpawnErrno(error);
 }
 
-const PI_CODING_AGENT_MODULE_URL = import.meta.resolve("@mariozechner/pi-coding-agent");
+const PI_CODING_AGENT_MODULE_URL = import.meta.resolve(
+  "@mariozechner/pi-coding-agent",
+);
 const CLIPBOARD_HELPER_SOURCE = `
 import { copyToClipboard } from ${JSON.stringify(PI_CODING_AGENT_MODULE_URL)};
 
@@ -257,10 +310,7 @@ for await (const chunk of process.stdin) {
 
 try {
   await Promise.resolve(copyToClipboard(Buffer.concat(chunks).toString("utf8")));
-} catch {
-  // Pi clipboard writes are best-effort. Backend failures must not make the
-  // helper exit non-zero and trip the parent spawn/environment breaker.
-}
+} catch {}
 `;
 
 const CLIPBOARD_READ_HELPER_SOURCE = `
@@ -316,11 +366,14 @@ function killClipboardProcess(child: ClipboardProcess): void {
   try {
     child.kill("SIGKILL");
   } catch {
-    // Best effort only; clipboard mirroring must not affect editing.
+    return;
   }
 }
 
-function writeClipboardInChildProcess(text: string, signal: AbortSignal): Promise<void> {
+function writeClipboardInChildProcess(
+  text: string,
+  signal: AbortSignal,
+): Promise<void> {
   return new Promise<void>((resolve, reject) => {
     if (signal.aborted) {
       reject(getAbortError(signal));
@@ -350,12 +403,20 @@ function writeClipboardInChildProcess(text: string, signal: AbortSignal): Promis
     }
 
     try {
-      child = spawn(process.execPath, ["--input-type=module", "-e", CLIPBOARD_HELPER_SOURCE], {
-        stdio: ["pipe", "pipe", "ignore"],
-        windowsHide: true,
-      });
+      child = spawn(
+        process.execPath,
+        ["--input-type=module", "-e", CLIPBOARD_HELPER_SOURCE],
+        {
+          stdio: ["pipe", "pipe", "ignore"],
+          windowsHide: true,
+        },
+      );
     } catch (error) {
-      finish(new ClipboardSpawnError("clipboard helper spawn failed", { cause: error }));
+      finish(
+        new ClipboardSpawnError("clipboard helper spawn failed", {
+          cause: error,
+        }),
+      );
       return;
     }
 
@@ -369,7 +430,11 @@ function writeClipboardInChildProcess(text: string, signal: AbortSignal): Promis
     });
 
     child.once("error", (error) => {
-      finish(new ClipboardSpawnError("clipboard helper spawn failed", { cause: error }));
+      finish(
+        new ClipboardSpawnError("clipboard helper spawn failed", {
+          cause: error,
+        }),
+      );
     });
 
     child.once("close", (code) => {
@@ -393,7 +458,11 @@ function writeClipboardInChildProcess(text: string, signal: AbortSignal): Promis
         return;
       }
 
-      finish(new ClipboardSpawnError(`clipboard helper failed with exit code ${code ?? "null"}`));
+      finish(
+        new ClipboardSpawnError(
+          `clipboard helper failed with exit code ${code ?? "null"}`,
+        ),
+      );
     });
 
     if (!child.stdin) {
@@ -436,7 +505,9 @@ class ClipboardMirror {
   ) {}
 
   setWriteFn(writeFn: ClipboardWriteFn): void {
-    this.activeController?.abort(createClipboardAbortError("clipboard writer replaced"));
+    this.activeController?.abort(
+      createClipboardAbortError("clipboard writer replaced"),
+    );
     this.writeFn = writeFn;
     resetClipboardCircuitBreaker();
   }
@@ -446,7 +517,9 @@ class ClipboardMirror {
   }
 
   hasPendingWrite(): boolean {
-    return this.activeText !== null || this.pendingText !== null || this.draining;
+    return (
+      this.activeText !== null || this.pendingText !== null || this.draining
+    );
   }
 
   mirror(text: string): void {
@@ -476,7 +549,6 @@ class ClipboardMirror {
           this.circuitBreaker.consecutiveEnvironmentFailures = 0;
         } catch (error) {
           this.recordWriteFailure(error);
-          // Clipboard mirroring is best-effort; the register is authoritative.
         } finally {
           if (this.activeController === controller) {
             this.activeController = null;
@@ -503,13 +575,19 @@ class ClipboardMirror {
     }
 
     this.circuitBreaker.consecutiveEnvironmentFailures += 1;
-    if (this.circuitBreaker.consecutiveEnvironmentFailures >= CLIPBOARD_SPAWN_FAILURE_LIMIT) {
+    if (
+      this.circuitBreaker.consecutiveEnvironmentFailures >=
+      CLIPBOARD_SPAWN_FAILURE_LIMIT
+    ) {
       this.circuitBreaker.disabled = true;
       this.pendingText = null;
     }
   }
 
-  private async writeWithTimeout(text: string, controller: AbortController): Promise<void> {
+  private async writeWithTimeout(
+    text: string,
+    controller: AbortController,
+  ): Promise<void> {
     const timeoutError = createClipboardAbortError("clipboard write timed out");
     const timeoutId = setTimeout(() => {
       controller.abort(timeoutError);
@@ -548,14 +626,18 @@ export class ModalEditor extends CustomEditor {
   private readonly redoStack: EditorSnapshot[] = [];
   private currentTransition: TransitionState = "none";
   private onChangeHooked: boolean = false;
-  private readonly labelColorizers: ModeLabelColorizers | null;
+  private readonly labelColorizers: ModeColorizers | null;
+  private readonly borderColorizers: ModeColorizers | null;
   private readonly cursorShapeRuntime: CursorShapeRuntime | null;
   private lastCursorShapeSequence: CursorShapeSequence | null = null;
 
-  // Unnamed register
   private unnamedRegister: string = "";
-  private clipboardMirrorPolicy: ClipboardMirrorPolicy = DEFAULT_CLIPBOARD_MIRROR_POLICY;
-  private readonly clipboardMirror = new ClipboardMirror(writeClipboardInChildProcess);
+  private preferRegisterForPut = false;
+  private clipboardMirrorPolicy: ClipboardMirrorPolicy =
+    DEFAULT_CLIPBOARD_MIRROR_POLICY;
+  private readonly clipboardMirror = new ClipboardMirror(
+    writeClipboardInChildProcess,
+  );
   private clipboardReadFn: ClipboardReadFn = readClipboardInChildProcess;
   private quitFn: () => void = () => {};
   private notifyFn: (message: string) => void = () => {};
@@ -564,18 +646,21 @@ export class ModalEditor extends CustomEditor {
     tui: CustomEditorConstructorArgs[0],
     theme: CustomEditorConstructorArgs[1],
     kb: CustomEditorConstructorArgs[2],
-    labelColorizers?: ModeLabelColorizers | null,
+    opts?: ModalEditorOptions,
   ) {
     super(tui, theme, kb);
     this.cursorShapeRuntime = getCursorShapeRuntime(tui);
-    this.labelColorizers = labelColorizers ?? null;
+    this.labelColorizers = opts?.labelColorizers ?? null;
+    this.borderColorizers = opts?.borderColorizers ?? null;
+    this.installModeBorderColorizer();
   }
 
-  // Test seams
   setClipboardFn(fn: (text: string, signal?: AbortSignal) => unknown): void {
-    this.clipboardMirror.setWriteFn(async (text: string, signal: AbortSignal) => {
-      await fn(text, signal);
-    });
+    this.clipboardMirror.setWriteFn(
+      async (text: string, signal: AbortSignal) => {
+        await fn(text, signal);
+      },
+    );
   }
   setClipboardWriteTimeoutMs(timeoutMs: number): void {
     this.clipboardMirror.setTimeoutMs(timeoutMs);
@@ -589,12 +674,51 @@ export class ModalEditor extends CustomEditor {
   getClipboardMirrorPolicy(): ClipboardMirrorPolicy {
     return this.clipboardMirrorPolicy;
   }
-  setQuitFn(fn: () => void): void { this.quitFn = fn; }
-  setNotifyFn(fn: (message: string) => void): void { this.notifyFn = fn; }
-  getRegister(): string { return this.unnamedRegister; }
-  setRegister(text: string): void { this.unnamedRegister = text; }
-  getMode(): Mode { return this.mode; }
-  getText(): string { return this.getLines().join("\n"); }
+  setQuitFn(fn: () => void): void {
+    this.quitFn = fn;
+  }
+  setNotifyFn(fn: (message: string) => void): void {
+    this.notifyFn = fn;
+  }
+  getRegister(): string {
+    return this.unnamedRegister;
+  }
+  setRegister(text: string): void {
+    this.unnamedRegister = text;
+    this.preferRegisterForPut = false;
+  }
+  getMode(): Mode {
+    return this.mode;
+  }
+  getText(): string {
+    return this.getLines().join("\n");
+  }
+
+  private getActiveMode(): Mode | "ex" {
+    if (this.pendingExCommand !== null) return "ex";
+    return this.mode;
+  }
+
+  private installModeBorderColorizer(): void {
+    if (!this.borderColorizers) return;
+    let base = this.borderColor;
+    const modeBorderColor = (text: string) =>
+      (this.borderColorizers?.[this.getActiveMode()] ?? base)(text);
+    // Pi assigns its default border color after extension editor construction.
+    // Keep a mode-aware getter installed and treat later assignments as the
+    // fallback/base color, otherwise syncBorderColorWithMode is overwritten in
+    // real sessions even though direct editor tests pass.
+    Object.defineProperty(this, "borderColor", {
+      get: () => modeBorderColor,
+      set(next: unknown) {
+        if (typeof next === "function") base = next as typeof base;
+      },
+    });
+  }
+
+  private setMode(mode: Mode = "insert"): void {
+    this.mode = mode;
+  }
 
   override setText(text: string): void {
     this.clearRedoStack();
@@ -609,14 +733,20 @@ export class ModalEditor extends CustomEditor {
     };
   }
 
-  private requireRedoRestoreState(
-    editor: ModalEditorInternals,
-  ): { lines: string[]; cursorLine?: number; cursorCol?: number } {
+  private requireRedoRestoreState(editor: ModalEditorInternals): {
+    lines: string[];
+    cursorLine?: number;
+    cursorCol?: number;
+  } {
     const state = editor.state;
     if (!state || !Array.isArray(state.lines)) {
       throw new Error("Redo restore prerequisite: editor state unavailable");
     }
-    return state as { lines: string[]; cursorLine?: number; cursorCol?: number };
+    return state as {
+      lines: string[];
+      cursorLine?: number;
+      cursorCol?: number;
+    };
   }
 
   private restoreSnapshot(snapshot: EditorSnapshot): void {
@@ -648,9 +778,11 @@ export class ModalEditor extends CustomEditor {
   }
 
   private snapshotChanged(a: EditorSnapshot, b: EditorSnapshot): boolean {
-    return a.text !== b.text
-      || a.cursor.line !== b.cursor.line
-      || a.cursor.col !== b.cursor.col;
+    return (
+      a.text !== b.text ||
+      a.cursor.line !== b.cursor.line ||
+      a.cursor.col !== b.cursor.col
+    );
   }
 
   private withTransition<T>(
@@ -737,9 +869,7 @@ export class ModalEditor extends CustomEditor {
   private applySyntheticEdit(mutation: () => void): void {
     const editor = this as unknown as ModalEditorInternals;
     if (!editor.state || !Array.isArray(editor.state.lines)) {
-      throw new Error(
-        "Synthetic edit prerequisite: editor state unavailable",
-      );
+      throw new Error("Synthetic edit prerequisite: editor state unavailable");
     }
 
     if (typeof editor.pushUndoSnapshot !== "function") {
@@ -756,9 +886,6 @@ export class ModalEditor extends CustomEditor {
 
     if (this.getText() === textBefore) return;
 
-    // Text changed — push undo boundary for pre-mutation state.
-    // Briefly swap pre-mutation state in for the snapshot, then
-    // restore the post-mutation result.
     const postLines = editor.state.lines.slice();
     const postCursorLine = editor.state.cursorLine;
     const postCursorCol = editor.state.cursorCol;
@@ -786,8 +913,9 @@ export class ModalEditor extends CustomEditor {
   }
 
   private clearPendingExCommand(): void {
-    const shouldDiscardBracketedPasteTail = this.acceptingBracketedPasteInExCommand
-      || this.pendingEscWhileAcceptingBracketedPasteInExCommand;
+    const shouldDiscardBracketedPasteTail =
+      this.acceptingBracketedPasteInExCommand ||
+      this.pendingEscWhileAcceptingBracketedPasteInExCommand;
 
     this.pendingExCommand = null;
     this.acceptingBracketedPasteInExCommand = false;
@@ -871,7 +999,10 @@ export class ModalEditor extends CustomEditor {
     }
   }
 
-  private stripBracketedPasteInNormalMode(data: string): { filtered: string | null; stripped: boolean } {
+  private stripBracketedPasteInNormalMode(data: string): {
+    filtered: string | null;
+    stripped: boolean;
+  } {
     let chunk = data;
     let stripped = false;
 
@@ -894,14 +1025,18 @@ export class ModalEditor extends CustomEditor {
       }
 
       stripped = true;
-      const end = chunk.indexOf(BRACKETED_PASTE_END, start + BRACKETED_PASTE_START.length);
+      const end = chunk.indexOf(
+        BRACKETED_PASTE_END,
+        start + BRACKETED_PASTE_START.length,
+      );
       if (end === -1) {
         this.discardingBracketedPasteInNormalMode = true;
         const leading = chunk.slice(0, start);
         return { filtered: leading.length > 0 ? leading : null, stripped };
       }
 
-      chunk = chunk.slice(0, start) + chunk.slice(end + BRACKETED_PASTE_END.length);
+      chunk =
+        chunk.slice(0, start) + chunk.slice(end + BRACKETED_PASTE_END.length);
       if (!chunk) return { filtered: null, stripped };
     }
   }
@@ -954,24 +1089,19 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    if (this.mode === "insert") {
-      // Shift+Alt+A: go to end of line (like Esc -> A but stay in insert)
+    if ("insert" === this.mode) {
       if (matchesKey(data, Key.shiftAlt("a")) || data === "\x1bA") {
         super.handleInput(CTRL_E);
         return;
       }
-      // Shift+Alt+I: go to start of line (like Esc -> I but stay in insert)
       if (matchesKey(data, Key.shiftAlt("i")) || data === "\x1bI") {
         super.handleInput(CTRL_A);
         return;
       }
-      // Alt+o: open new line below (stay in insert mode)
       if (matchesKey(data, Key.alt("o")) || data === "\x1bo") {
         this.openLineBelow();
         return;
       }
-      // Alt+Shift+o: open new line above (stay in insert mode)
-      // \x1bO is the legacy sequence for Alt+Shift+O (VT100 SS3 prefix in non-Kitty terminals)
       if (matchesKey(data, Key.shiftAlt("o")) || data === "\x1bO") {
         this.openLineAbove();
         return;
@@ -999,9 +1129,14 @@ export class ModalEditor extends CustomEditor {
       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);
+      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;
     }
@@ -1064,32 +1199,42 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (
-      this.pendingMotion
-      || this.pendingTextObject
-      || this.pendingOperator
-      || this.prefixCount
-      || this.operatorCount
-      || this.pendingG
-      || this.pendingGCount
-      || this.pendingReplace
+      this.pendingMotion ||
+      this.pendingTextObject ||
+      this.pendingOperator ||
+      this.prefixCount ||
+      this.operatorCount ||
+      this.pendingG ||
+      this.pendingGCount ||
+      this.pendingReplace
     ) {
       this.clearPendingState();
       return;
     }
-    if (this.mode === "insert") {
+    if ("insert" === this.mode) {
       this.clearUnderlyingPasteStateIfActive();
-      this.mode = "normal";
+      this.setMode("normal");
     } else {
       super.handleInput("\x1b"); // pass escape to abort agent
     }
   }
 
   private isEnterLikeInput(data: string): boolean {
-    return data === "\r" || data === "\n" || matchesKey(data, "enter") || matchesKey(data, "return");
+    return (
+      data === "\r" ||
+      data === "\n" ||
+      matchesKey(data, "enter") ||
+      matchesKey(data, "return")
+    );
   }
 
   private isBackspaceLikeInput(data: string): boolean {
-    return data === "\x7f" || data === "\x08" || matchesKey(data, "backspace") || matchesKey(data, "ctrl+h");
+    return (
+      data === "\x7f" ||
+      data === "\x08" ||
+      matchesKey(data, "backspace") ||
+      matchesKey(data, "ctrl+h")
+    );
   }
 
   private deleteLastPendingExCommandGrapheme(): void {
@@ -1112,10 +1257,10 @@ export class ModalEditor extends CustomEditor {
 
   private handlePendingExCommandControlChunk(data: string): boolean {
     if (
-      !data.includes("\r")
-      && !data.includes("\n")
-      && !data.includes("\x7f")
-      && !data.includes("\x08")
+      !data.includes("\r") &&
+      !data.includes("\n") &&
+      !data.includes("\x7f") &&
+      !data.includes("\x08")
     ) {
       return false;
     }
@@ -1212,7 +1357,8 @@ export class ModalEditor extends CustomEditor {
     if (data.length === 0) return false;
     for (const char of data) {
       const codePoint = char.codePointAt(0);
-      if (codePoint === undefined || codePoint < 32 || codePoint === 127) return false;
+      if (codePoint === undefined || codePoint < 32 || codePoint === 127)
+        return false;
     }
     return true;
   }
@@ -1249,9 +1395,10 @@ export class ModalEditor extends CustomEditor {
 
     if (prefix === null && operator === null) return defaultValue;
 
-    const total = prefix !== null && operator !== null
-      ? prefix * operator
-      : prefix ?? operator ?? defaultValue;
+    const total =
+      prefix !== null && operator !== null
+        ? prefix * operator
+        : (prefix ?? operator ?? defaultValue);
 
     if (!Number.isFinite(total) || total <= 0) return defaultValue;
     return Math.min(MAX_COUNT, total);
@@ -1286,7 +1433,7 @@ export class ModalEditor extends CustomEditor {
     } else if (this.pendingOperator === "c") {
       this.deleteWithCharMotion(pendingMotion, data);
       this.pendingOperator = null;
-      this.mode = "insert";
+      this.setMode();
     } else if (this.pendingOperator === "y") {
       this.yankWithCharMotion(pendingMotion, data);
       this.pendingOperator = null;
@@ -1315,7 +1462,11 @@ export class ModalEditor extends CustomEditor {
     if (data === "w" || data === "W") {
       const semanticClass: WordTextObjectClass = data === "W" ? "WORD" : "word";
       const count = this.takeTotalCount(1);
-      const range = this.getWordObjectRange(pendingTextObject, count, semanticClass);
+      const range = this.getWordObjectRange(
+        pendingTextObject,
+        count,
+        semanticClass,
+      );
       if (!range || !this.pendingOperator) {
         this.pendingOperator = null;
         return;
@@ -1353,7 +1504,7 @@ export class ModalEditor extends CustomEditor {
     if (range.endAbs === range.startAbs) {
       if (pendingOperator === "c") {
         this.moveCursorToAbsoluteIndex(range.startAbs);
-        this.mode = "insert";
+        this.setMode();
       }
       return;
     }
@@ -1365,7 +1516,7 @@ export class ModalEditor extends CustomEditor {
 
     if (pendingOperator === "c") {
       this.deleteRangeByAbsolute(range.startAbs, range.endAbs);
-      this.mode = "insert";
+      this.setMode();
       return;
     }
 
@@ -1395,7 +1546,8 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (data === "j" || data === "k") {
-      const hasDualCount = this.prefixCount.length > 0 && this.operatorCount.length > 0;
+      const hasDualCount =
+        this.prefixCount.length > 0 && this.operatorCount.length > 0;
       const count = this.takeTotalCount(1);
       const delta = hasDualCount ? Math.max(0, count - 1) : count;
       this.deleteLinewiseByDelta(data === "j" ? delta : -delta);
@@ -1426,20 +1578,18 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    const hasCount = this.prefixCount.length > 0 || this.operatorCount.length > 0;
-    const supportsCountedWordMotion = (
-      data === "w"
-      || data === "e"
-      || data === "b"
-      || data === "W"
-      || data === "E"
-      || data === "B"
-    );
+    const hasCount =
+      this.prefixCount.length > 0 || this.operatorCount.length > 0;
+    const supportsCountedWordMotion =
+      data === "w" ||
+      data === "e" ||
+      data === "b" ||
+      data === "W" ||
+      data === "E" ||
+      data === "B";
     const supportsCountedTextObject = data === "i" || data === "a";
 
     if (hasCount && !supportsCountedWordMotion && !supportsCountedTextObject) {
-      // Counted forms beyond dd, d{count}j/k, d{count}{f/F/t/T}, and
-      // d{count}{w/e/b/W/E/B}/{i/a}w are out of scope.
       this.cancelPendingOperator(data);
       return;
     }
@@ -1455,7 +1605,6 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    // Invalid motion: cancel operator to avoid sticky surprising deletes.
     this.cancelPendingOperator(data);
   }
 
@@ -1480,7 +1629,7 @@ export class ModalEditor extends CustomEditor {
 
       this.cutLine();
       this.pendingOperator = null;
-      this.mode = "insert";
+      this.setMode();
       return;
     }
 
@@ -1501,7 +1650,7 @@ export class ModalEditor extends CustomEditor {
         this.replaceTextInBuffer(newText, cursorAbs);
       }
       this.pendingOperator = null;
-      this.mode = "insert";
+      this.setMode();
       return;
     }
 
@@ -1510,15 +1659,15 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    const hasCount = this.prefixCount.length > 0 || this.operatorCount.length > 0;
-    const supportsCountedWordMotion = (
-      data === "w"
-      || data === "e"
-      || data === "b"
-      || data === "W"
-      || data === "E"
-      || data === "B"
-    );
+    const hasCount =
+      this.prefixCount.length > 0 || this.operatorCount.length > 0;
+    const supportsCountedWordMotion =
+      data === "w" ||
+      data === "e" ||
+      data === "b" ||
+      data === "W" ||
+      data === "E" ||
+      data === "B";
     const supportsCountedTextObject = data === "i" || data === "a";
 
     if (hasCount && !supportsCountedWordMotion && !supportsCountedTextObject) {
@@ -1532,16 +1681,14 @@ export class ModalEditor extends CustomEditor {
     }
 
     const motionCount = supportsCountedWordMotion ? this.takeTotalCount(1) : 1;
-    const effectiveMotion = data === "W" && this.isCursorOnNonWhitespace()
-      ? "E"
-      : data;
+    const effectiveMotion =
+      data === "W" && this.isCursorOnNonWhitespace() ? "E" : data;
     if (this.deleteWithMotion(effectiveMotion, motionCount)) {
       this.pendingOperator = null;
-      this.mode = "insert";
+      this.setMode();
       return;
     }
 
-    // Invalid motion: cancel operator to avoid sticky surprising changes.
     this.cancelPendingOperator(data);
   }
 
@@ -1601,43 +1748,34 @@ export class ModalEditor extends CustomEditor {
         return;
       }
 
-      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")
-      );
-      const supportsCountedCharMotion = (
-        CHAR_MOTION_KEYS.has(data)
-        || data === ";"
-        || data === ","
-      );
-      const supportsCountedWordMotion = (
-        data === "w"
-        || data === "e"
-        || data === "b"
-        || data === "W"
-        || data === "E"
-        || data === "B"
-      );
+      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");
+      const supportsCountedCharMotion =
+        CHAR_MOTION_KEYS.has(data) || data === ";" || data === ",";
+      const supportsCountedWordMotion =
+        data === "w" ||
+        data === "e" ||
+        data === "b" ||
+        data === "W" ||
+        data === "E" ||
+        data === "B";
       const supportsCountedParagraphMotion = data === "{" || data === "}";
-      const supportsCountedNav = (
-        data === "h"
-        || data === "j"
-        || data === "k"
-        || data === "l"
-      );
+      const supportsCountedNav =
+        data === "h" || data === "j" || data === "k" || data === "l";
       const supportsCountedUnderscore = data === "_";
 
       if (supportsCountedNav) {
@@ -1660,13 +1798,12 @@ export class ModalEditor extends CustomEditor {
       }
 
       if (
-        !supportsCountedStandaloneEdit
-        && !supportsCountedCharMotion
-        && !supportsCountedWordMotion
-        && !supportsCountedParagraphMotion
-        && !supportsCountedUnderscore
+        !supportsCountedStandaloneEdit &&
+        !supportsCountedCharMotion &&
+        !supportsCountedWordMotion &&
+        !supportsCountedParagraphMotion &&
+        !supportsCountedUnderscore
       ) {
-        // Unsupported prefixed forms: drop count and keep processing this key.
         this.prefixCount = "";
         this.operatorCount = "";
       }
@@ -1738,7 +1875,11 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (data === ";" && this.lastCharMotion) {
-      this.executeCharMotion(this.lastCharMotion.motion, this.lastCharMotion.char, false);
+      this.executeCharMotion(
+        this.lastCharMotion.motion,
+        this.lastCharMotion.char,
+        false,
+      );
       return;
     }
     if (data === "," && this.lastCharMotion) {
@@ -1750,7 +1891,11 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    if (data === "u" || data === CTRL_UNDERSCORE || matchesKey(data, "ctrl+_")) {
+    if (
+      data === "u" ||
+      data === CTRL_UNDERSCORE ||
+      matchesKey(data, "ctrl+_")
+    ) {
       this.performUndo();
       return;
     }
@@ -1810,7 +1955,6 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    // Pass control sequences (ctrl+c, etc.) to super, ignore printable chars
     if (this.isPrintableChunk(data)) return;
     super.handleInput(data);
   }
@@ -1830,29 +1974,29 @@ export class ModalEditor extends CustomEditor {
     const seq = NORMAL_KEYS[key];
     switch (key) {
       case "i":
-        this.mode = "insert";
+        this.setMode();
         break;
       case "a":
-        this.mode = "insert";
+        this.setMode();
         if (!this.isCursorAtOrPastEol()) {
           super.handleInput(ESC_RIGHT);
         }
         break;
       case "A":
-        this.mode = "insert";
+        this.setMode();
         super.handleInput(CTRL_E);
         break;
       case "I":
-        this.mode = "insert";
+        this.setMode();
         this.moveCursorToFirstNonWhitespace();
         break;
       case "o":
         this.openLineBelow();
-        this.mode = "insert";
+        this.setMode();
         break;
       case "O":
         this.openLineAbove();
-        this.mode = "insert";
+        this.setMode();
         break;
       case "D":
         this.takeTotalCount(1);
@@ -1861,16 +2005,16 @@ export class ModalEditor extends CustomEditor {
       case "C":
         this.takeTotalCount(1);
         this.cutToEndOfLine();
-        this.mode = "insert";
+        this.setMode();
         break;
       case "S":
         this.takeTotalCount(1);
         this.cutCurrentLineContent();
-        this.mode = "insert";
+        this.setMode();
         break;
       case "s":
         this.cutCharUnderCursor();
-        this.mode = "insert";
+        this.setMode();
         break;
       case "x":
         this.cutCharUnderCursor();
@@ -1886,11 +2030,22 @@ export class ModalEditor extends CustomEditor {
     }
   }
 
-  private executeCharMotion(motion: CharMotion, targetChar: string, saveMotion: boolean = true): void {
+  private executeCharMotion(
+    motion: CharMotion,
+    targetChar: string,
+    saveMotion: boolean = true,
+  ): void {
     const line = this.getLines()[this.getCursor().line] ?? "";
     const col = this.getCursor().col;
     const count = this.takeTotalCount(1);
-    const targetCol = findCharMotionTarget(line, col, motion, targetChar, !saveMotion, count);
+    const targetCol = findCharMotionTarget(
+      line,
+      col,
+      motion,
+      targetChar,
+      !saveMotion,
+      count,
+    );
 
     if (targetCol !== null && saveMotion) {
       this.lastCharMotion = { motion, char: targetChar };
@@ -1905,7 +2060,12 @@ export class ModalEditor extends CustomEditor {
     const lines = this.getLines();
     const fromLine = this.getCursor().line;
     const count = this.takeTotalCount(1);
-    const targetLine = findParagraphMotionTarget(lines, fromLine, direction, count);
+    const targetLine = findParagraphMotionTarget(
+      lines,
+      fromLine,
+      direction,
+      count,
+    );
     this.moveCursorToLineStart(targetLine);
   }
 
@@ -1920,7 +2080,11 @@ export class ModalEditor extends CustomEditor {
 
     const state = editor.state;
     if (!state || !Array.isArray(state.lines)) return false;
-    if (!Number.isInteger(state.cursorLine) || !Number.isInteger(state.cursorCol)) return false;
+    if (
+      !Number.isInteger(state.cursorLine) ||
+      !Number.isInteger(state.cursorCol)
+    )
+      return false;
 
     const cursorLine = state.cursorLine as number;
     const cursorCol = state.cursorCol as number;
@@ -1929,8 +2093,6 @@ export class ModalEditor extends CustomEditor {
 
     const target = cursorCol + delta;
 
-    // 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;
@@ -1970,7 +2132,10 @@ export class ModalEditor extends CustomEditor {
     }
 
     const currentLine = state.cursorLine ?? 0;
-    const targetLine = Math.max(0, Math.min(currentLine + delta, state.lines.length - 1));
+    const targetLine = Math.max(
+      0,
+      Math.min(currentLine + delta, state.lines.length - 1),
+    );
     if (targetLine === currentLine) return;
 
     const preferredCol = editor.preferredVisualCol ?? state.cursorCol ?? 0;
@@ -2074,9 +2239,12 @@ export class ModalEditor extends CustomEditor {
         if (normalize) {
           const trimmedRight = right.trimStart();
           const leftLastChar = left[left.length - 1];
-          const leftEndsWithSpace = leftLastChar !== undefined && /\s/.test(leftLastChar);
+          const leftEndsWithSpace =
+            leftLastChar !== undefined && /\s/.test(leftLastChar);
           const needsSeparator = !leftEndsWithSpace && trimmedRight.length > 0;
-          joined = needsSeparator ? `${left} ${trimmedRight}` : left + trimmedRight;
+          joined = needsSeparator
+            ? `${left} ${trimmedRight}`
+            : left + trimmedRight;
           joinPoint = left.length;
         } else {
           joined = left + right;
@@ -2170,25 +2338,43 @@ export class ModalEditor extends CustomEditor {
         } else if (target === "start") {
           const startType = this.charType(text[next], semanticClass);
           if (startType !== "space") {
-            while (next < len && this.charType(text[next], semanticClass) === startType) next++;
+            while (
+              next < len &&
+              this.charType(text[next], semanticClass) === startType
+            )
+              next++;
           }
-          while (next < len && this.charType(text[next], semanticClass) === "space") next++;
+          while (
+            next < len &&
+            this.charType(text[next], semanticClass) === "space"
+          )
+            next++;
         } else {
           if (next < len - 1) next++;
-          while (next < len && this.charType(text[next], semanticClass) === "space") next++;
+          while (
+            next < len &&
+            this.charType(text[next], semanticClass) === "space"
+          )
+            next++;
           if (next >= len) {
             next = len;
           } else {
             const t = this.charType(text[next], semanticClass);
-            while (next < len - 1 && this.charType(text[next + 1], semanticClass) === t) next++;
+            while (
+              next < len - 1 &&
+              this.charType(text[next + 1], semanticClass) === t
+            )
+              next++;
           }
         }
       } else {
         if (next >= len) next = len - 1;
         if (next > 0) next--;
-        while (next > 0 && this.charType(text[next], semanticClass) === "space") next--;
+        while (next > 0 && this.charType(text[next], semanticClass) === "space")
+          next--;
         const t = this.charType(text[next], semanticClass);
-        while (next > 0 && this.charType(text[next - 1], semanticClass) === t) next--;
+        while (next > 0 && this.charType(text[next - 1], semanticClass) === t)
+          next--;
       }
 
       if (next === i) break;
@@ -2277,7 +2463,11 @@ export class ModalEditor extends CustomEditor {
     semanticClass: WordMotionClass = "word",
   ): boolean {
     const col = this.getCursor().col;
-    const targetCol = this.tryFindWordTargetLineLocal(direction, target, semanticClass);
+    const targetCol = this.tryFindWordTargetLineLocal(
+      direction,
+      target,
+      semanticClass,
+    );
     if (targetCol === null || targetCol === col) return false;
 
     this.moveCursorToCol(targetCol);
@@ -2293,7 +2483,8 @@ export class ModalEditor extends CustomEditor {
     const lineIndex = cursor.line;
     const col = cursor.col;
     const lineSnapshot = this.getLines()[lineIndex] ?? "";
-    const direction: WordMotionDirection = motion === "b" ? "backward" : "forward";
+    const direction: WordMotionDirection =
+      motion === "b" ? "backward" : "forward";
     const target: WordMotionTarget = motion === "e" ? "end" : "start";
     const steps = Math.max(1, Math.min(MAX_COUNT, count));
 
@@ -2360,10 +2551,14 @@ export class ModalEditor extends CustomEditor {
     return true;
   }
 
-  private writeToRegister(text: string, source: RegisterWriteSource = "mutation"): void {
+  private writeToRegister(
+    text: string,
+    source: RegisterWriteSource = "mutation",
+  ): void {
     this.unnamedRegister = text;
-    if (!text) return;
-    if (!this.shouldMirrorRegisterWrite(source)) return;
+    const shouldMirror = text !== "" && this.shouldMirrorRegisterWrite(source);
+    this.preferRegisterForPut = text !== "" && !shouldMirror;
+    if (!shouldMirror) return;
 
     this.clipboardMirror.mirror(text);
   }
@@ -2375,7 +2570,9 @@ export class ModalEditor extends CustomEditor {
   }
 
   private hasMultiCodeUnitGraphemes(line: string): boolean {
-    return getLineGraphemes(line).some((segment) => segment.end - segment.start > 1);
+    return getLineGraphemes(line).some(
+      (segment) => segment.end - segment.start > 1,
+    );
   }
 
   private getGraphemeRangeAtCol(
@@ -2386,7 +2583,9 @@ export class ModalEditor extends CustomEditor {
   ): { 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);
+    const startIndex = segments.findIndex(
+      (segment) => clampedCol < segment.end,
+    );
     if (startIndex === -1) return null;
 
     let endIndex = startIndex + Math.max(1, count) - 1;
@@ -2427,7 +2626,8 @@ export class ModalEditor extends CustomEditor {
     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),
+      text.slice(0, lineStartAbs + range.start) +
+        text.slice(lineStartAbs + range.end),
       lineStartAbs + range.start,
     );
   }
@@ -2438,7 +2638,8 @@ export class ModalEditor extends CustomEditor {
     const { line, col } = this.getCurrentLineAndCol();
 
     const hasNextLine = cursorLine < lines.length - 1;
-    const deleted = col < line.length ? line.slice(col) : hasNextLine ? "\n" : "";
+    const deleted =
+      col < line.length ? line.slice(col) : hasNextLine ? "\n" : "";
 
     this.writeToRegister(deleted);
     super.handleInput(CTRL_K);
@@ -2461,7 +2662,10 @@ export class ModalEditor extends CustomEditor {
     this.cutCurrentLineContent();
   }
 
-  private getNormalizedLineRange(startLine: number, endLine: number): { start: number; end: number } {
+  private getNormalizedLineRange(
+    startLine: number,
+    endLine: number,
+  ): { start: number; end: number } {
     const lines = this.getLines();
     const last = Math.max(0, lines.length - 1);
     const clampedStart = Math.max(0, Math.min(startLine, last));
@@ -2478,7 +2682,10 @@ export class ModalEditor extends CustomEditor {
     return `${lines.slice(start, end + 1).join("\n")}\n`;
   }
 
-  private getLineDeleteAbsoluteRange(startLine: number, endLine: number): { startAbs: number; endAbs: number } {
+  private getLineDeleteAbsoluteRange(
+    startLine: number,
+    endLine: number,
+  ): { startAbs: number; endAbs: number } {
     const lines = this.getLines();
     const text = this.getText();
     const { start, end } = this.getNormalizedLineRange(startLine, endLine);
@@ -2505,7 +2712,10 @@ export class ModalEditor extends CustomEditor {
     if (lines.length === 0) return;
 
     const payload = this.getLinewisePayload(startLine, endLine);
-    const { startAbs, endAbs } = this.getLineDeleteAbsoluteRange(startLine, endLine);
+    const { startAbs, endAbs } = this.getLineDeleteAbsoluteRange(
+      startLine,
+      endLine,
+    );
 
     this.writeToRegister(payload);
 
@@ -2514,7 +2724,6 @@ export class ModalEditor extends CustomEditor {
       const newText = text.slice(0, startAbs) + text.slice(endAbs);
       this.replaceTextInBuffer(newText, startAbs);
 
-      // Ensure cursor is at column 0 of the landing line
       super.handleInput(CTRL_A);
     }
   }
@@ -2547,7 +2756,6 @@ export class ModalEditor extends CustomEditor {
     const col = cursor.col;
 
     if (motion === "$") {
-      // Match D/C behavior exactly, including newline kill at EOL.
       this.cutToEndOfLine();
       return true;
     }
@@ -2558,7 +2766,11 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (motion === "^") {
-      this.deleteRange(col, findFirstNonWhitespaceColumn(this.getLines()[cursor.line] ?? ""), false);
+      this.deleteRange(
+        col,
+        findFirstNonWhitespaceColumn(this.getLines()[cursor.line] ?? ""),
+        false,
+      );
       return true;
     }
 
@@ -2588,7 +2800,11 @@ export class ModalEditor extends CustomEditor {
         count,
         wordMotion.semanticClass,
       );
-      this.deleteRangeByAbsolute(currentAbs, targetAbs, wordMotion.motion === "e");
+      this.deleteRangeByAbsolute(
+        currentAbs,
+        targetAbs,
+        wordMotion.motion === "e",
+      );
       return true;
     }
 
@@ -2599,7 +2815,14 @@ export class ModalEditor extends CustomEditor {
     const line = this.getLines()[this.getCursor().line] ?? "";
     const col = this.getCursor().col;
     const count = this.takeTotalCount(1);
-    const targetCol = findCharMotionTarget(line, col, motion, targetChar, false, count);
+    const targetCol = findCharMotionTarget(
+      line,
+      col,
+      motion,
+      targetChar,
+      false,
+      count,
+    );
 
     if (targetCol === null) return;
 
@@ -2628,7 +2851,8 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (data === "j" || data === "k") {
-      const hasDualCount = this.prefixCount.length > 0 && this.operatorCount.length > 0;
+      const hasDualCount =
+        this.prefixCount.length > 0 && this.operatorCount.length > 0;
       const count = this.takeTotalCount(1);
       const delta = hasDualCount ? Math.max(0, count - 1) : count;
       this.yankLinewiseByDelta(data === "j" ? delta : -delta);
@@ -2665,7 +2889,6 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (this.hasPendingCount()) {
-      // Counted forms beyond yy, y{count}j/k, and y{count}{f/F/t/T} are out of scope.
       this.cancelPendingOperator(data);
       return;
     }
@@ -2723,7 +2946,11 @@ export class ModalEditor extends CustomEditor {
         1,
         wordMotion.semanticClass,
       );
-      this.yankRangeByAbsolute(currentAbs, targetAbs, wordMotion.motion === "e");
+      this.yankRangeByAbsolute(
+        currentAbs,
+        targetAbs,
+        wordMotion.motion === "e",
+      );
       return true;
     }
 
@@ -2734,7 +2961,14 @@ export class ModalEditor extends CustomEditor {
     const line = this.getLines()[this.getCursor().line] ?? "";
     const col = this.getCursor().col;
     const count = this.takeTotalCount(1);
-    const targetCol = findCharMotionTarget(line, col, motion, targetChar, false, count);
+    const targetCol = findCharMotionTarget(
+      line,
+      col,
+      motion,
+      targetChar,
+      false,
+      count,
+    );
 
     if (targetCol === null) return;
 
@@ -2749,17 +2983,24 @@ export class ModalEditor extends CustomEditor {
     let end = Math.min(rawEnd, line.length);
 
     if (inclusive) {
-      const targetRange = this.getGraphemeRangeAtCol(line, Math.max(col, targetCol), 1);
+      const targetRange = this.getGraphemeRangeAtCol(
+        line,
+        Math.max(col, targetCol),
+        1,
+      );
       end = targetRange?.end ?? end;
     }
 
     if (end <= start) return;
 
-    // Yank only — no cursor movement, no text mutation
     this.writeToRegister(line.slice(start, end), "yank");
   }
 
-  private yankRangeByAbsolute(currentAbs: number, targetAbs: number, inclusive: boolean = false): void {
+  private yankRangeByAbsolute(
+    currentAbs: number,
+    targetAbs: number,
+    inclusive: boolean = false,
+  ): void {
     const text = this.getText();
     const start = Math.min(currentAbs, targetAbs);
     const rawEnd = Math.max(currentAbs, targetAbs) + (inclusive ? 1 : 0);
@@ -2768,7 +3009,10 @@ export class ModalEditor extends CustomEditor {
     this.writeToRegister(text.slice(start, end), "yank");
   }
 
-  private getCursorFromAbsoluteIndex(text: string, abs: number): { line: number; col: number } {
+  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++) {
@@ -2809,7 +3053,11 @@ export class ModalEditor extends CustomEditor {
     editor.tui?.requestRender?.();
   }
 
-  private deleteRangeByAbsolute(currentAbs: number, targetAbs: number, inclusive: boolean = false): void {
+  private deleteRangeByAbsolute(
+    currentAbs: number,
+    targetAbs: number,
+    inclusive: boolean = false,
+  ): void {
     const text = this.getText();
     const start = Math.min(currentAbs, targetAbs);
     const rawEnd = Math.max(currentAbs, targetAbs) + (inclusive ? 1 : 0);
@@ -2845,7 +3093,7 @@ export class ModalEditor extends CustomEditor {
   private static readonly PUT_SIZE_LIMIT = 512 * 1024; // 512 KB safety cap
 
   private getPasteRegisterText(): string {
-    if (this.clipboardMirror.hasPendingWrite()) {
+    if (this.preferRegisterForPut || this.clipboardMirror.hasPendingWrite()) {
       return this.unnamedRegister;
     }
 
@@ -2861,12 +3109,14 @@ export class ModalEditor extends CustomEditor {
     const count = this.takeTotalCount(1);
     const text = this.getPasteRegisterText();
     if (!text) return;
-    const safeCount = Math.min(count, Math.max(1, Math.floor(ModalEditor.PUT_SIZE_LIMIT / text.length)));
+    const safeCount = Math.min(
+      count,
+      Math.max(1, Math.floor(ModalEditor.PUT_SIZE_LIMIT / text.length)),
+    );
 
     if (text.endsWith("\n")) {
       const content = text.slice(0, -1);
       for (let i = 0; i < safeCount; i++) {
-        // Line-wise: insert new line below and fill it
         super.handleInput(CTRL_E);
         super.handleInput(NEWLINE);
         for (const char of content) {
@@ -2876,7 +3126,6 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    // Character-wise: insert after cursor
     if (!this.isCursorAtOrPastEol()) {
       super.handleInput(ESC_RIGHT);
     }
@@ -2891,12 +3140,14 @@ export class ModalEditor extends CustomEditor {
     const count = this.takeTotalCount(1);
     const text = this.getPasteRegisterText();
     if (!text) return;
-    const safeCount = Math.min(count, Math.max(1, Math.floor(ModalEditor.PUT_SIZE_LIMIT / text.length)));
+    const safeCount = Math.min(
+      count,
+      Math.max(1, Math.floor(ModalEditor.PUT_SIZE_LIMIT / text.length)),
+    );
 
     if (text.endsWith("\n")) {
       const content = text.slice(0, -1);
       for (let i = 0; i < safeCount; i++) {
-        // Line-wise: insert new line above and fill it
         super.handleInput(CTRL_A);
         super.handleInput(NEWLINE);
         super.handleInput(ESC_UP);
@@ -2907,7 +3158,6 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    // Character-wise: insert before cursor (just type it)
     for (let i = 0; i < safeCount; i++) {
       for (const char of text) {
         super.handleInput(char === "\n" ? NEWLINE : char);
@@ -2915,7 +3165,11 @@ export class ModalEditor extends CustomEditor {
     }
   }
 
-  private deleteRange(col: number, targetCol: number, inclusive: boolean): void {
+  private deleteRange(
+    col: number,
+    targetCol: number,
+    inclusive: boolean,
+  ): void {
     const cursor = this.getCursor();
     const line = this.getLines()[cursor.line] ?? "";
     const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
@@ -2924,7 +3178,11 @@ export class ModalEditor extends CustomEditor {
     let end = Math.min(rawEnd, line.length);
 
     if (inclusive) {
-      const targetRange = this.getGraphemeRangeAtCol(line, Math.max(col, targetCol), 1);
+      const targetRange = this.getGraphemeRangeAtCol(
+        line,
+        Math.max(col, targetCol),
+        1,
+      );
       end = targetRange?.end ?? end;
     }
 
@@ -2973,7 +3231,7 @@ export class ModalEditor extends CustomEditor {
   }
 
   private getDesiredCursorShapeSequence(): CursorShapeSequence {
-    return this.mode === "insert" && this.pendingExCommand === null
+    return "insert" === this.mode && this.pendingExCommand === null
       ? INSERT_CURSOR_SHAPE
       : BLOCK_CURSOR_SHAPE;
   }
@@ -3021,7 +3279,8 @@ export class ModalEditor extends CustomEditor {
     const last = lines.length - 1;
     const lastLine = lines[last];
     if (lastLine && visibleWidth(lastLine) >= visibleWidth(rawLabel)) {
-      lines[last] = truncateToWidth(lastLine, width - visibleWidth(rawLabel), "") + label;
+      lines[last] =
+        truncateToWidth(lastLine, width - visibleWidth(rawLabel), "") + label;
     } else {
       lines[last] = label;
     }
@@ -3029,13 +3288,11 @@ export class ModalEditor extends CustomEditor {
   }
 
   private getModeLabelColorizer(): ((s: string) => string) | null {
-    if (!this.labelColorizers) return null;
-    if (this.pendingExCommand !== null) return this.labelColorizers.ex;
-    return this.mode === "insert" ? this.labelColorizers.insert : this.labelColorizers.normal;
+    return this.labelColorizers?.[this.getActiveMode()] ?? null;
   }
 
   private getModeLabel(): string {
-    if (this.mode === "insert") return " INSERT ";
+    if ("insert" === this.mode) return " INSERT ";
     if (this.pendingExCommand !== null) return ` EX ${this.pendingExCommand}_ `;
 
     const prefixCount = this.prefixCount;
@@ -3068,21 +3325,29 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_start", (_event, ctx) => {
     const piVimSettings = readPiVimSettings(ctx.cwd);
-    const clipboardMirrorPolicy = resolveClipboardMirrorPolicy(piVimSettings.clipboardMirror);
+    const clipboardMirrorPolicy = resolveClipboardMirrorPolicy(
+      piVimSettings.clipboardMirror,
+    );
     if (clipboardMirrorPolicy.warning && ctx.hasUI) {
       ctx.ui.notify(clipboardMirrorPolicy.warning, "warning");
     }
 
     const t = ctx.ui.theme;
+    const modeColors = resolveModeColors(piVimSettings.modeColors);
     const reverseVideo = (s: string) => `\x1b[7m${s}\x1b[27m`;
-    const colorizers = t ? {
-      insert: (s: string) => t.fg("borderMuted", reverseVideo(s)),
-      normal: (s: string) => t.fg("borderAccent", reverseVideo(s)),
-      ex: (s: string) => t.fg("warning", reverseVideo(s)),
-    } : null;
+    const labelColorizers = t
+      ? buildModeColorizers(t, modeColors, reverseVideo)
+      : null;
+    const borderColorizers =
+      t && piVimSettings.syncBorderColorWithMode === true
+        ? buildModeColorizers(t, modeColors)
+        : null;
     ctx.ui.setEditorComponent((tui, theme, kb) => {
       cursorShapeCleanup = enableCursorShapeSupport(tui);
-      const editor = new ModalEditor(tui, theme, kb, colorizers);
+      const editor = new ModalEditor(tui, theme, kb, {
+        labelColorizers,
+        borderColorizers,
+      });
       editor.setClipboardMirrorPolicy(clipboardMirrorPolicy.policy);
       editor.setQuitFn(() => ctx.shutdown());
       editor.setNotifyFn((message) => ctx.ui.notify(message, "warning"));