pi-vim 0.3.1 → 0.8.0

package/index.ts

@@ -1,60 +1,11 @@
-/**
- * Modal Editor - vim-like modal editing extension
- *
- * Usage: pi --extension ./index.ts
- *
- * - Escape / ctrl+[: insert → normal mode (in normal mode, aborts agent)
- * - i: normal → insert mode (at cursor)
- * - a: insert after cursor
- * - A: insert at end of line
- * - I: insert at start of line
- * - o: open new line below (insert mode)
- * - O: open new line above (insert mode)
- * - hjkl: navigation in normal mode
- * - 0/$: line start/end
- * - ^: first non-whitespace char of line
- * - _: first non-whitespace (with count: down count-1 lines first); linewise with d/c/y
- * - x: delete char under cursor
- * - D: delete to end of line
- * - S: substitute line (delete line content + insert mode)
- * - s: substitute char (delete char + insert mode)
- * - d{motion}: delete with motion (`w/b/e` + `W/B/E`, `$`, `0`, `^`, `dd`/`d_`, `f/t/F/T{char}`)
- * - c{motion}: change with same motion set as `d` (then enter insert mode)
- * - y{motion}: yank with same motion set as `d` (no text mutation)
- * - f{char}: jump to next {char} on line
- * - F{char}: jump to previous {char} on line
- * - t{char}: jump to just before next {char} on line
- * - T{char}: jump to just after previous {char} on line
- * - ;: repeat last f/F/t/T motion (same direction)
- * - ,: repeat last f/F/t/T motion (reverse direction)
- * - w/b/e: `word` motions (keyword/punctuation aware)
- * - W/B/E: `WORD` motions (whitespace-delimited non-space runs)
- * - {/}: paragraph motions to previous/next paragraph start (line start col 0)
- * - `{count}` prefixes supported for navigation, paragraph motions, and `d/c` word/WORD motions
- * - operator forms with braces (`d{`, `d}`, `c{`, `c}`, `y{`, `y}`) are out of scope
- * - counted yank caveat: `y2w`, `2yw`, `y2W`, `2yW` cancel (linewise counts still supported)
- * - Shift+Alt+A: go to end of line (insert mode shortcut)
- * - Shift+Alt+I: go to start of line (insert mode shortcut)
- * - Alt+o: open new line below (insert mode shortcut)
- * - Alt+Shift+o: open new line above (insert mode shortcut)
- * - u: undo (normal mode, sends ctrl+_ to underlying readline editor)
- * - ctrl+c, ctrl+d, etc. work in both modes
- *
- * Inspired by original repo:
- * - https://github.com/badlogic/pi-mono
- *   (packages/coding-agent/examples/extensions/modal-editor.ts)
- *
- * Additional ideas adapted from:
- * - https://github.com/l-lin/dotfiles
- *   (home-manager/modules/share/ai/pi/.pi/agent/extensions/vim-mode)
- */
+import { spawn, spawnSync } from "node:child_process";
 
 import {
-  copyToClipboard,
   CustomEditor,
   type ExtensionAPI,
 } from "@mariozechner/pi-coding-agent";
 import {
+  CURSOR_MARKER,
   Key,
   matchesKey,
   truncateToWidth,
@@ -95,11 +46,37 @@ import {
   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~";
 const BRACKETED_PASTE_END_TAIL = BRACKETED_PASTE_END.slice(1);
 const MAX_COUNT = 9999;
+const PI_NATIVE_CLIPBOARD_TIMEOUT_MS = 5000;
+const SOFTWARE_CURSOR_START = "\x1b[7m";
+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;
 
 type EditorSnapshot = {
   text: string;
@@ -119,16 +96,451 @@ type ModalEditorInternals = {
   setCursorCol?: (col: number) => void;
 };
 
+type CustomEditorConstructorArgs = ConstructorParameters<typeof CustomEditor>;
+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 CursorShapeSequence =
+  | typeof INSERT_CURSOR_SHAPE
+  | typeof BLOCK_CURSOR_SHAPE
+  | typeof RESET_CURSOR_SHAPE;
+
+type CursorShapeRuntime = {
+  writeCursorShape: (sequence: CursorShapeSequence) => void;
+  setShowHardwareCursor: (show: boolean) => void;
+  getShowHardwareCursor?: () => boolean | undefined;
+};
+
+type CursorShapeCleanup = () => void;
+
+type CursorShapeTuiCandidate = {
+  terminal?: { write?: unknown };
+  setShowHardwareCursor?: unknown;
+  getShowHardwareCursor?: unknown;
+};
+
+function getCursorShapeRuntime(tui: unknown): CursorShapeRuntime | null {
+  if (typeof tui !== "object" || tui === null) return null;
+
+  const candidate = tui as CursorShapeTuiCandidate;
+  const terminal = candidate.terminal;
+  if (typeof terminal !== "object" || terminal === null) return null;
+
+  const write = terminal.write;
+  const setShowHardwareCursor = candidate.setShowHardwareCursor;
+  if (typeof write !== "function" || typeof setShowHardwareCursor !== "function") {
+    return null;
+  }
+
+  const runtime: CursorShapeRuntime = {
+    writeCursorShape(sequence: CursorShapeSequence): void {
+      write.call(terminal, sequence);
+    },
+    setShowHardwareCursor(show: boolean): void {
+      setShowHardwareCursor.call(candidate, show);
+    },
+  };
+
+  if (typeof candidate.getShowHardwareCursor === "function") {
+    const getShowHardwareCursor = candidate.getShowHardwareCursor;
+    runtime.getShowHardwareCursor = () => {
+      const value = getShowHardwareCursor.call(candidate);
+      return typeof value === "boolean" ? value : undefined;
+    };
+  }
+
+  return runtime;
+}
+
+function enableCursorShapeSupport(tui: unknown): CursorShapeCleanup | null {
+  const runtime = getCursorShapeRuntime(tui);
+  if (!runtime) return null;
+
+  const previousShowHardwareCursor = runtime.getShowHardwareCursor?.();
+  runtime.setShowHardwareCursor(true);
+
+  return () => {
+    runtime.writeCursorShape(RESET_CURSOR_SHAPE);
+    if (previousShowHardwareCursor !== undefined) {
+      runtime.setShowHardwareCursor(previousShowHardwareCursor);
+    }
+  };
+}
+
+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;
+
+  for (const sequence of SOFTWARE_CURSOR_RESETS) {
+    const index = line.indexOf(sequence, startIndex);
+    if (index === -1) continue;
+    if (!firstReset || index < firstReset.index) {
+      firstReset = { index, sequence };
+    }
+  }
+
+  return firstReset;
+}
+
+function stripSoftwareCursorAfterMarker(line: string): string {
+  const markerIndex = line.indexOf(CURSOR_MARKER);
+  if (markerIndex === -1) return line;
+
+  const searchStart = markerIndex + CURSOR_MARKER.length;
+  const cursorStart = line.indexOf(SOFTWARE_CURSOR_START, searchStart);
+  if (cursorStart === -1) return line;
+
+  const cursorContentStart = cursorStart + SOFTWARE_CURSOR_START.length;
+  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);
+}
+
+type ClipboardCircuitBreaker = {
+  consecutiveEnvironmentFailures: number;
+  disabled: boolean;
+};
+
+const processClipboardCircuitBreaker: ClipboardCircuitBreaker = {
+  consecutiveEnvironmentFailures: 0,
+  disabled: false,
+};
+
+function resetClipboardCircuitBreaker(): void {
+  processClipboardCircuitBreaker.consecutiveEnvironmentFailures = 0;
+  processClipboardCircuitBreaker.disabled = false;
+}
+
+class ClipboardSpawnError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "ClipboardSpawnError";
+  }
+}
+
+type SpawnErrnoLike = Error & { code?: unknown; syscall?: unknown };
+
+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");
+}
+
+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 CLIPBOARD_HELPER_SOURCE = `
+import { copyToClipboard } from ${JSON.stringify(PI_CODING_AGENT_MODULE_URL)};
+
+const chunks = [];
+for await (const chunk of process.stdin) {
+  chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+}
+
+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.
+}
+`;
+
+const CLIPBOARD_READ_HELPER_SOURCE = `
+import { createRequire } from "node:module";
+
+const require = createRequire(${JSON.stringify(PI_CODING_AGENT_MODULE_URL)});
+const clipboard = require("@mariozechner/clipboard");
+if (!await clipboard.hasText()) {
+  process.exit(0);
+}
+const text = await clipboard.getText();
+if (typeof text === "string") {
+  process.stdout.write(text);
+}
+`;
+
+function readClipboardInChildProcess(): string | null {
+  try {
+    const result = spawnSync(
+      process.execPath,
+      ["--input-type=module", "-e", CLIPBOARD_READ_HELPER_SOURCE],
+      {
+        encoding: "utf8",
+        maxBuffer: CLIPBOARD_READ_MAX_BUFFER_BYTES,
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: CLIPBOARD_READ_TIMEOUT_MS,
+        windowsHide: true,
+      },
+    );
+
+    if (result.error || result.status !== 0 || result.signal) return null;
+    return result.stdout ?? "";
+  } catch {
+    return null;
+  }
+}
+
+function createClipboardAbortError(message: string): Error {
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
+}
+
+function getAbortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : createClipboardAbortError("clipboard write aborted");
+}
+
+function killClipboardProcess(child: ClipboardProcess): void {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+
+  try {
+    child.kill("SIGKILL");
+  } catch {
+    // Best effort only; clipboard mirroring must not affect editing.
+  }
+}
+
+function writeClipboardInChildProcess(text: string, signal: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal.aborted) {
+      reject(getAbortError(signal));
+      return;
+    }
+
+    let child: ClipboardProcess | null = null;
+    let settled = false;
+    const stdoutChunks: Buffer[] = [];
+
+    function finish(error?: unknown): void {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    }
+
+    function onAbort(): void {
+      if (child) {
+        killClipboardProcess(child);
+      }
+      finish(getAbortError(signal));
+    }
+
+    try {
+      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 }));
+      return;
+    }
+
+    signal.addEventListener("abort", onAbort, { once: true });
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      stdoutChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    });
+    child.stdout?.on("error", (error) => {
+      finish(error);
+    });
+
+    child.once("error", (error) => {
+      finish(new ClipboardSpawnError("clipboard helper spawn failed", { cause: error }));
+    });
+
+    child.once("close", (code) => {
+      if (settled) return;
+
+      if (signal.aborted) {
+        finish(getAbortError(signal));
+        return;
+      }
+
+      if (code === 0) {
+        try {
+          for (const chunk of stdoutChunks) {
+            process.stdout.write(chunk);
+          }
+        } catch (error) {
+          finish(error);
+          return;
+        }
+        finish();
+        return;
+      }
+
+      finish(new ClipboardSpawnError(`clipboard helper failed with exit code ${code ?? "null"}`));
+    });
+
+    if (!child.stdin) {
+      killClipboardProcess(child);
+      finish(new ClipboardSpawnError("clipboard helper stdin unavailable"));
+      return;
+    }
+
+    child.stdin.on("error", (error: NodeJS.ErrnoException) => {
+      if (signal.aborted) {
+        finish(getAbortError(signal));
+        return;
+      }
+
+      if (error.code === "EPIPE" || error.code === "ERR_STREAM_DESTROYED") {
+        return;
+      }
+
+      finish(error);
+    });
+
+    try {
+      child.stdin.end(text);
+    } catch (error) {
+      finish(error);
+    }
+  });
+}
+
+class ClipboardMirror {
+  private activeController: AbortController | null = null;
+  private activeText: string | null = null;
+  private draining = false;
+  private pendingText: string | null = null;
+
+  constructor(
+    private writeFn: ClipboardWriteFn,
+    private timeoutMs: number = CLIPBOARD_WRITE_TIMEOUT_MS,
+    private readonly circuitBreaker: ClipboardCircuitBreaker = processClipboardCircuitBreaker,
+  ) {}
+
+  setWriteFn(writeFn: ClipboardWriteFn): void {
+    this.activeController?.abort(createClipboardAbortError("clipboard writer replaced"));
+    this.writeFn = writeFn;
+    resetClipboardCircuitBreaker();
+  }
+
+  setTimeoutMs(timeoutMs: number): void {
+    this.timeoutMs = Math.max(0, timeoutMs);
+  }
+
+  hasPendingWrite(): boolean {
+    return this.activeText !== null || this.pendingText !== null || this.draining;
+  }
+
+  mirror(text: string): void {
+    if (this.circuitBreaker.disabled) return;
+
+    this.pendingText = text;
+
+    if (!this.draining) {
+      void this.drain();
+    }
+  }
+
+  private async drain(): Promise<void> {
+    if (this.draining) return;
+    this.draining = true;
+
+    try {
+      while (this.pendingText !== null && !this.circuitBreaker.disabled) {
+        const text = this.pendingText;
+        this.pendingText = null;
+        const controller = new AbortController();
+        this.activeController = controller;
+        this.activeText = text;
+
+        try {
+          await this.writeWithTimeout(text, controller);
+          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;
+          }
+          this.activeText = null;
+        }
+      }
+
+      if (this.circuitBreaker.disabled) {
+        this.pendingText = null;
+      }
+    } finally {
+      this.draining = false;
+      if (this.pendingText !== null && !this.circuitBreaker.disabled) {
+        void this.drain();
+      }
+    }
+  }
+
+  private recordWriteFailure(error: unknown): void {
+    if (!isClipboardEnvironmentFailure(error)) {
+      this.circuitBreaker.consecutiveEnvironmentFailures = 0;
+      return;
+    }
+
+    this.circuitBreaker.consecutiveEnvironmentFailures += 1;
+    if (this.circuitBreaker.consecutiveEnvironmentFailures >= CLIPBOARD_SPAWN_FAILURE_LIMIT) {
+      this.circuitBreaker.disabled = true;
+      this.pendingText = null;
+    }
+  }
+
+  private async writeWithTimeout(text: string, controller: AbortController): Promise<void> {
+    const timeoutError = createClipboardAbortError("clipboard write timed out");
+    const timeoutId = setTimeout(() => {
+      controller.abort(timeoutError);
+    }, this.timeoutMs);
+
+    try {
+      await this.writeFn(text, controller.signal);
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw getAbortError(controller.signal);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
 export class ModalEditor extends CustomEditor {
   private mode: Mode = "insert";
   private pendingMotion: PendingMotion = null;
-  private pendingTextObject: "i" | "a" | null = null;
+  private pendingTextObject: TextObjectKind | null = null;
   private pendingOperator: PendingOperator = null;
   private prefixCount: string = "";
   private operatorCount: string = "";
   private pendingG: boolean = false;
   private pendingGCount: string = "";
   private pendingReplace: boolean = false;
+  private pendingExCommand: string | null = null;
+  private acceptingBracketedPasteInExCommand: boolean = false;
+  private pendingEscWhileAcceptingBracketedPasteInExCommand: boolean = false;
   private lastCharMotion: LastCharMotion | null = null;
   private discardingBracketedPasteInNormalMode: boolean = false;
   private pendingEscWhileDiscardingBracketedPasteInNormalMode: boolean = false;
@@ -136,26 +548,49 @@ export class ModalEditor extends CustomEditor {
   private readonly redoStack: EditorSnapshot[] = [];
   private currentTransition: TransitionState = "none";
   private onChangeHooked: boolean = false;
-  private readonly labelColorizers: { insert: (s: string) => string; normal: (s: string) => string } | null;
+  private readonly labelColorizers: ModeLabelColorizers | null;
+  private readonly cursorShapeRuntime: CursorShapeRuntime | null;
+  private lastCursorShapeSequence: CursorShapeSequence | null = null;
 
   // Unnamed register
   private unnamedRegister: string = "";
-  private clipboardFn: (text: string) => void = (text: string) => {
-    try { copyToClipboard(text); } catch { /* best effort */ }
-  };
+  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 = () => {};
 
   constructor(
-    tui: any,
-    theme: any,
-    kb: any,
-    labelColorizers?: { insert: (s: string) => string; normal: (s: string) => string } | null,
+    tui: CustomEditorConstructorArgs[0],
+    theme: CustomEditorConstructorArgs[1],
+    kb: CustomEditorConstructorArgs[2],
+    labelColorizers?: ModeLabelColorizers | null,
   ) {
     super(tui, theme, kb);
+    this.cursorShapeRuntime = getCursorShapeRuntime(tui);
     this.labelColorizers = labelColorizers ?? null;
   }
 
   // Test seams
-  setClipboardFn(fn: (text: string) => void): void { this.clipboardFn = fn; }
+  setClipboardFn(fn: (text: string, signal?: AbortSignal) => unknown): void {
+    this.clipboardMirror.setWriteFn(async (text: string, signal: AbortSignal) => {
+      await fn(text, signal);
+    });
+  }
+  setClipboardWriteTimeoutMs(timeoutMs: number): void {
+    this.clipboardMirror.setTimeoutMs(timeoutMs);
+  }
+  setClipboardReadFn(fn: ClipboardReadFn): void {
+    this.clipboardReadFn = fn;
+  }
+  setClipboardMirrorPolicy(policy: ClipboardMirrorPolicy): void {
+    this.clipboardMirrorPolicy = policy;
+  }
+  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; }
@@ -181,7 +616,7 @@ export class ModalEditor extends CustomEditor {
     if (!state || !Array.isArray(state.lines)) {
       throw new Error("Redo restore prerequisite: editor state unavailable");
     }
-    return state;
+    return state as { lines: string[]; cursorLine?: number; cursorCol?: number };
   }
 
   private restoreSnapshot(snapshot: EditorSnapshot): void {
@@ -344,6 +779,26 @@ export class ModalEditor extends CustomEditor {
     editor.tui?.requestRender?.();
   }
 
+  private startPendingExCommand(): void {
+    this.pendingExCommand = ":";
+    this.acceptingBracketedPasteInExCommand = false;
+    this.pendingEscWhileAcceptingBracketedPasteInExCommand = false;
+  }
+
+  private clearPendingExCommand(): void {
+    const shouldDiscardBracketedPasteTail = this.acceptingBracketedPasteInExCommand
+      || this.pendingEscWhileAcceptingBracketedPasteInExCommand;
+
+    this.pendingExCommand = null;
+    this.acceptingBracketedPasteInExCommand = false;
+    this.pendingEscWhileAcceptingBracketedPasteInExCommand = false;
+
+    if (shouldDiscardBracketedPasteTail) {
+      this.discardingBracketedPasteInNormalMode = true;
+      this.pendingEscWhileDiscardingBracketedPasteInNormalMode = false;
+    }
+  }
+
   private clearPendingState(): void {
     this.pendingMotion = null;
     this.pendingTextObject = null;
@@ -353,12 +808,69 @@ export class ModalEditor extends CustomEditor {
     this.pendingG = false;
     this.pendingGCount = "";
     this.pendingReplace = false;
+    this.clearPendingExCommand();
   }
 
   private isEscapeLikeInput(data: string): boolean {
     return matchesKey(data, "escape") || matchesKey(data, "ctrl+[");
   }
 
+  private normalizePendingExCommandInput(data: string): string | null {
+    let chunk = data;
+    let normalized = "";
+
+    while (true) {
+      if (this.acceptingBracketedPasteInExCommand) {
+        if (this.pendingEscWhileAcceptingBracketedPasteInExCommand) {
+          if (chunk.startsWith(BRACKETED_PASTE_END_TAIL)) {
+            this.pendingEscWhileAcceptingBracketedPasteInExCommand = false;
+            this.acceptingBracketedPasteInExCommand = false;
+            chunk = chunk.slice(BRACKETED_PASTE_END_TAIL.length);
+            if (chunk.length === 0) {
+              return normalized.length > 0 ? normalized : null;
+            }
+            continue;
+          }
+
+          normalized += "\x1b";
+          this.pendingEscWhileAcceptingBracketedPasteInExCommand = false;
+        }
+
+        const end = chunk.indexOf(BRACKETED_PASTE_END);
+        if (end !== -1) {
+          normalized += chunk.slice(0, end);
+          this.acceptingBracketedPasteInExCommand = false;
+          chunk = chunk.slice(end + BRACKETED_PASTE_END.length);
+          if (chunk.length === 0) {
+            return normalized.length > 0 ? normalized : null;
+          }
+          continue;
+        }
+
+        if (this.isEscapeLikeInput(chunk)) {
+          this.pendingEscWhileAcceptingBracketedPasteInExCommand = true;
+          return normalized.length > 0 ? normalized : null;
+        }
+
+        normalized += chunk;
+        return normalized.length > 0 ? normalized : null;
+      }
+
+      const start = chunk.indexOf(BRACKETED_PASTE_START);
+      if (start === -1) {
+        normalized += chunk;
+        return normalized.length > 0 ? normalized : null;
+      }
+
+      normalized += chunk.slice(0, start);
+      chunk = chunk.slice(start + BRACKETED_PASTE_START.length);
+      this.acceptingBracketedPasteInExCommand = true;
+      if (chunk.length === 0) {
+        return normalized.length > 0 ? normalized : null;
+      }
+    }
+  }
+
   private stripBracketedPasteInNormalMode(data: string): { filtered: string | null; stripped: boolean } {
     let chunk = data;
     let stripped = false;
@@ -397,7 +909,11 @@ export class ModalEditor extends CustomEditor {
   handleInput(data: string): void {
     this.ensureOnChangeHook();
 
-    if (this.mode !== "insert") {
+    if (this.pendingExCommand !== null) {
+      const normalized = this.normalizePendingExCommandInput(data);
+      if (normalized === null) return;
+      data = normalized;
+    } else if (this.mode !== "insert") {
       if (this.discardingBracketedPasteInNormalMode) {
         if (this.isEscapeLikeInput(data)) {
           if (this.pendingEscWhileDiscardingBracketedPasteInNormalMode) {
@@ -434,17 +950,20 @@ export class ModalEditor extends CustomEditor {
     }
 
     if (this.isEscapeLikeInput(data)) {
-      return this.handleEscape();
+      this.handleEscape();
+      return;
     }
 
     if (this.mode === "insert") {
       // Shift+Alt+A: go to end of line (like Esc -> A but stay in insert)
       if (matchesKey(data, Key.shiftAlt("a")) || data === "\x1bA") {
-        return super.handleInput(CTRL_E);
+        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") {
-        return super.handleInput(CTRL_A);
+        super.handleInput(CTRL_A);
+        return;
       }
       // Alt+o: open new line below (stay in insert mode)
       if (matchesKey(data, Key.alt("o")) || data === "\x1bo") {
@@ -487,24 +1006,34 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (this.pendingExCommand !== null) {
+      this.handlePendingExCommand(data);
+      return;
+    }
+
     if (this.pendingTextObject) {
-      return this.handlePendingTextObject(data);
+      this.handlePendingTextObject(data);
+      return;
     }
 
     if (this.pendingMotion) {
-      return this.handlePendingMotion(data);
+      this.handlePendingMotion(data);
+      return;
     }
 
     if (this.pendingOperator === "d") {
-      return this.handlePendingDelete(data);
+      this.handlePendingDelete(data);
+      return;
     }
 
     if (this.pendingOperator === "c") {
-      return this.handlePendingChange(data);
+      this.handlePendingChange(data);
+      return;
     }
 
     if (this.pendingOperator === "y") {
-      return this.handlePendingYank(data);
+      this.handlePendingYank(data);
+      return;
     }
 
     this.handleNormalMode(data);
@@ -529,6 +1058,11 @@ export class ModalEditor extends CustomEditor {
   }
 
   private handleEscape(): void {
+    if (this.pendingExCommand !== null) {
+      this.clearPendingExCommand();
+      return;
+    }
+
     if (
       this.pendingMotion
       || this.pendingTextObject
@@ -550,11 +1084,135 @@ export class ModalEditor extends CustomEditor {
     }
   }
 
+  private isEnterLikeInput(data: string): boolean {
+    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");
+  }
+
+  private deleteLastPendingExCommandGrapheme(): void {
+    const current = this.pendingExCommand ?? "";
+    const graphemes = getLineGraphemes(current);
+
+    if (graphemes.length <= 1) {
+      this.clearPendingExCommand();
+      return;
+    }
+
+    const previousGrapheme = graphemes[graphemes.length - 2];
+    if (!previousGrapheme) {
+      this.clearPendingExCommand();
+      return;
+    }
+
+    this.pendingExCommand = current.slice(0, previousGrapheme.end);
+  }
+
+  private handlePendingExCommandControlChunk(data: string): boolean {
+    if (
+      !data.includes("\r")
+      && !data.includes("\n")
+      && !data.includes("\x7f")
+      && !data.includes("\x08")
+    ) {
+      return false;
+    }
+
+    let printable = "";
+    const flushPrintable = () => {
+      if (!printable) return;
+      this.pendingExCommand += printable;
+      printable = "";
+    };
+
+    for (const char of data) {
+      if (char === "\r" || char === "\n") {
+        flushPrintable();
+        this.submitPendingExCommand();
+        return true;
+      }
+
+      if (char === "\x7f" || char === "\x08") {
+        flushPrintable();
+        this.deleteLastPendingExCommandGrapheme();
+        if (this.pendingExCommand === null) {
+          return true;
+        }
+        continue;
+      }
+
+      const codePoint = char.codePointAt(0);
+      if (codePoint === undefined || codePoint < 32 || codePoint === 127) {
+        this.clearPendingExCommand();
+        return true;
+      }
+
+      printable += char;
+    }
+
+    flushPrintable();
+    return true;
+  }
+
+  private handlePendingExCommand(data: string): void {
+    if (this.isEnterLikeInput(data)) {
+      this.submitPendingExCommand();
+      return;
+    }
+
+    if (this.isBackspaceLikeInput(data)) {
+      this.deleteLastPendingExCommandGrapheme();
+      return;
+    }
+
+    if (this.handlePendingExCommandControlChunk(data)) {
+      return;
+    }
+
+    if (!this.isPrintableChunk(data)) {
+      this.clearPendingExCommand();
+      this.handleInput(data);
+      return;
+    }
+
+    this.pendingExCommand += data;
+  }
+
+  private hasNonEmptyPrompt(): boolean {
+    return this.getText().trim().length > 0;
+  }
+
+  private submitPendingExCommand(): void {
+    const command = this.pendingExCommand?.slice(1).trim() ?? "";
+    this.clearPendingExCommand();
+
+    if (command === "q" || command === "qa") {
+      if (this.hasNonEmptyPrompt()) {
+        this.notifyFn(`Prompt is not empty; use :${command}! to quit anyway`);
+        return;
+      }
+
+      this.quitFn();
+      return;
+    }
+
+    if (command === "q!" || command === "qa!") {
+      this.quitFn();
+      return;
+    }
+
+    if (command) {
+      this.notifyFn(`Unsupported ex command: :${command}`);
+    }
+  }
+
   private isPrintableChunk(data: string): boolean {
     if (data.length === 0) return false;
     for (const char of data) {
-      const codePoint = char.codePointAt(0)!;
-      if (codePoint < 32 || codePoint === 127) return false;
+      const codePoint = char.codePointAt(0);
+      if (codePoint === undefined || codePoint < 32 || codePoint === 127) return false;
     }
     return true;
   }
@@ -599,6 +1257,10 @@ export class ModalEditor extends CustomEditor {
     return Math.min(MAX_COUNT, total);
   }
 
+  private hasPendingCount(): boolean {
+    return this.prefixCount.length > 0 || this.operatorCount.length > 0;
+  }
+
   private cancelPendingOperator(data: string): void {
     this.pendingOperator = null;
     this.prefixCount = "";
@@ -615,59 +1277,101 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    const pendingMotion = this.pendingMotion;
+    if (!pendingMotion) return;
+
     if (this.pendingOperator === "d") {
-      this.deleteWithCharMotion(this.pendingMotion!, data);
+      this.deleteWithCharMotion(pendingMotion, data);
       this.pendingOperator = null;
     } else if (this.pendingOperator === "c") {
-      this.deleteWithCharMotion(this.pendingMotion!, data);
+      this.deleteWithCharMotion(pendingMotion, data);
       this.pendingOperator = null;
       this.mode = "insert";
     } else if (this.pendingOperator === "y") {
-      this.yankWithCharMotion(this.pendingMotion!, data);
+      this.yankWithCharMotion(pendingMotion, data);
       this.pendingOperator = null;
     } else {
-      this.executeCharMotion(this.pendingMotion!, data);
+      this.executeCharMotion(pendingMotion, data);
     }
 
     this.pendingMotion = null;
   }
 
   private handlePendingTextObject(data: string): void {
-    if (data !== "w") {
-      this.pendingTextObject = null;
-      this.cancelPendingOperator(data);
+    const pendingTextObject = this.pendingTextObject;
+    this.pendingTextObject = null;
+    if (!pendingTextObject) {
+      this.pendingOperator = null;
       return;
     }
 
-    const count = this.takeTotalCount(1);
-    const range = this.getWordObjectRange(this.pendingTextObject!, count);
-    this.pendingTextObject = null;
-    if (!range || !this.pendingOperator) {
-      this.pendingOperator = null;
+    const hasCount = this.hasPendingCount();
+
+    if (this.pendingOperator === "y" && hasCount) {
+      this.cancelPendingOperator(data);
       return;
     }
 
-    const { startAbs, endAbs } = range;
-    if (this.pendingOperator === "d") {
-      this.deleteRangeByAbsolute(startAbs, endAbs);
-      this.pendingOperator = null;
+    if (data === "w" || data === "W") {
+      const semanticClass: WordTextObjectClass = data === "W" ? "WORD" : "word";
+      const count = this.takeTotalCount(1);
+      const range = this.getWordObjectRange(pendingTextObject, count, semanticClass);
+      if (!range || !this.pendingOperator) {
+        this.pendingOperator = null;
+        return;
+      }
+
+      this.applyResolvedTextObjectRange(range);
       return;
     }
 
-    if (this.pendingOperator === "c") {
-      this.deleteRangeByAbsolute(startAbs, endAbs);
-      this.pendingOperator = null;
-      this.mode = "insert";
+    if (hasCount) {
+      this.cancelPendingOperator(data);
       return;
     }
 
-    if (this.pendingOperator === "y") {
-      this.yankRangeByAbsolute(startAbs, endAbs);
-      this.pendingOperator = null;
+    const range = resolveDelimitedTextObjectRange(
+      this.getText(),
+      this.getDelimitedTextObjectCursorAbs(),
+      pendingTextObject,
+      data,
+    );
+    if (!range) {
+      this.cancelPendingOperator(data);
       return;
     }
 
+    this.applyResolvedTextObjectRange(range);
+  }
+
+  private applyResolvedTextObjectRange(range: TextObjectRange): void {
+    const pendingOperator = this.pendingOperator;
     this.pendingOperator = null;
+
+    if (!pendingOperator || range.endAbs < range.startAbs) return;
+
+    if (range.endAbs === range.startAbs) {
+      if (pendingOperator === "c") {
+        this.moveCursorToAbsoluteIndex(range.startAbs);
+        this.mode = "insert";
+      }
+      return;
+    }
+
+    if (pendingOperator === "d") {
+      this.deleteRangeByAbsolute(range.startAbs, range.endAbs);
+      return;
+    }
+
+    if (pendingOperator === "c") {
+      this.deleteRangeByAbsolute(range.startAbs, range.endAbs);
+      this.mode = "insert";
+      return;
+    }
+
+    if (pendingOperator === "y") {
+      this.yankRangeByAbsolute(range.startAbs, range.endAbs);
+    }
   }
 
   private handlePendingDelete(data: string): void {
@@ -982,6 +1686,11 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
+    if (data === ":") {
+      this.startPendingExCommand();
+      return;
+    }
+
     if (data === "G") {
       this.moveCursorToBufferEnd();
       return;
@@ -1072,16 +1781,33 @@ export class ModalEditor extends CustomEditor {
 
     if (data === "w") {
       const count = this.takeTotalCount(1);
-      return this.moveWord("forward", "start", count, "word");
+      this.moveWord("forward", "start", count, "word");
+      return;
+    }
+    if (data === "b") {
+      this.moveWord("backward", "start", this.takeTotalCount(1), "word");
+      return;
+    }
+    if (data === "e") {
+      this.moveWord("forward", "end", this.takeTotalCount(1), "word");
+      return;
+    }
+    if (data === "W") {
+      this.moveWord("forward", "start", this.takeTotalCount(1), "WORD");
+      return;
+    }
+    if (data === "B") {
+      this.moveWord("backward", "start", this.takeTotalCount(1), "WORD");
+      return;
+    }
+    if (data === "E") {
+      this.moveWord("forward", "end", this.takeTotalCount(1), "WORD");
+      return;
     }
-    if (data === "b") return this.moveWord("backward", "start", this.takeTotalCount(1), "word");
-    if (data === "e") return this.moveWord("forward", "end", this.takeTotalCount(1), "word");
-    if (data === "W") return this.moveWord("forward", "start", this.takeTotalCount(1), "WORD");
-    if (data === "B") return this.moveWord("backward", "start", this.takeTotalCount(1), "WORD");
-    if (data === "E") return this.moveWord("forward", "end", this.takeTotalCount(1), "WORD");
 
     if (Object.hasOwn(NORMAL_KEYS, data)) {
-      return this.handleMappedKey(data);
+      this.handleMappedKey(data);
+      return;
     }
 
     // Pass control sequences (ctrl+c, etc.) to super, ignore printable chars
@@ -1315,7 +2041,7 @@ export class ModalEditor extends CustomEditor {
   }
 
   private moveCursorToFirstNonWhitespace(): void {
-    const { line, col } = this.getCurrentLineAndCol();
+    const { line } = this.getCurrentLineAndCol();
     const targetCol = findFirstNonWhitespaceColumn(line);
     this.moveCursorToCol(targetCol);
   }
@@ -1341,13 +2067,14 @@ export class ModalEditor extends CustomEditor {
       for (let i = 0; i < steps; i++) {
         if (currentLine >= state.lines.length - 1) break;
 
-        const left = state.lines[currentLine]!;
-        const right = state.lines[currentLine + 1]!;
+        const left = state.lines[currentLine] ?? "";
+        const right = state.lines[currentLine + 1] ?? "";
         let joined: string;
 
         if (normalize) {
           const trimmedRight = right.trimStart();
-          const leftEndsWithSpace = left.length > 0 && /\s/.test(left[left.length - 1]!);
+          const leftLastChar = left[left.length - 1];
+          const leftEndsWithSpace = leftLastChar !== undefined && /\s/.test(leftLastChar);
           const needsSeparator = !leftEndsWithSpace && trimmedRight.length > 0;
           joined = needsSeparator ? `${left} ${trimmedRight}` : left + trimmedRight;
           joinPoint = left.length;
@@ -1408,6 +2135,18 @@ export class ModalEditor extends CustomEditor {
     return this.getAbsoluteIndex(cursor.line, cursor.col);
   }
 
+  private getDelimitedTextObjectCursorAbs(): number {
+    const lines = this.getLines();
+    const cursor = this.getCursor();
+    const line = lines[cursor.line] ?? "";
+
+    if (line.length > 0 && cursor.col >= line.length) {
+      return this.getAbsoluteIndex(cursor.line, line.length - 1);
+    }
+
+    return this.getAbsoluteIndex(cursor.line, cursor.col);
+  }
+
   private findWordTargetInText(
     text: string,
     abs: number,
@@ -1615,10 +2354,18 @@ export class ModalEditor extends CustomEditor {
     }
   }
 
-  private writeToRegister(text: string): void {
+  private shouldMirrorRegisterWrite(source: RegisterWriteSource): boolean {
+    if (this.clipboardMirrorPolicy === "never") return false;
+    if (this.clipboardMirrorPolicy === "yank") return source === "yank";
+    return true;
+  }
+
+  private writeToRegister(text: string, source: RegisterWriteSource = "mutation"): void {
     this.unnamedRegister = text;
     if (!text) return;
-    this.clipboardFn(text);
+    if (!this.shouldMirrorRegisterWrite(source)) return;
+
+    this.clipboardMirror.mirror(text);
   }
 
   private getCurrentLineAndCol(): { line: string; col: number } {
@@ -1648,9 +2395,13 @@ export class ModalEditor extends CustomEditor {
       endIndex = segments.length - 1;
     }
 
+    const startSegment = segments[startIndex];
+    const endSegment = segments[endIndex];
+    if (!startSegment || !endSegment) return null;
+
     return {
-      start: segments[startIndex]!.start,
-      end: segments[endIndex]!.end,
+      start: startSegment.start,
+      end: endSegment.end,
     };
   }
 
@@ -1770,7 +2521,7 @@ export class ModalEditor extends CustomEditor {
 
   private yankLineRange(startLine: number, endLine: number): void {
     if (this.getLines().length === 0) return;
-    this.writeToRegister(this.getLinewisePayload(startLine, endLine));
+    this.writeToRegister(this.getLinewisePayload(startLine, endLine), "yank");
   }
 
   private deleteLinewiseByDelta(delta: number): void {
@@ -1908,14 +2659,14 @@ export class ModalEditor extends CustomEditor {
       return;
     }
 
-    if (this.prefixCount.length > 0 || this.operatorCount.length > 0) {
-      // Counted forms beyond yy, y{count}j/k, and y{count}{f/F/t/T} are out of scope.
-      this.cancelPendingOperator(data);
+    if (data === "i" || data === "a") {
+      this.pendingTextObject = data;
       return;
     }
 
-    if (data === "i" || data === "a") {
-      this.pendingTextObject = data;
+    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;
     }
 
@@ -2005,16 +2756,16 @@ export class ModalEditor extends CustomEditor {
     if (end <= start) return;
 
     // Yank only — no cursor movement, no text mutation
-    this.writeToRegister(line.slice(start, end));
+    this.writeToRegister(line.slice(start, end), "yank");
   }
 
-  private yankRangeByAbsolute(currentAbs: number, targetAbs: number, inclusive: boolean): 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);
     const end = Math.min(rawEnd, text.length);
     if (end <= start) return;
-    this.writeToRegister(text.slice(start, end));
+    this.writeToRegister(text.slice(start, end), "yank");
   }
 
   private getCursorFromAbsoluteIndex(text: string, abs: number): { line: number; col: number } {
@@ -2072,73 +2823,43 @@ export class ModalEditor extends CustomEditor {
   }
 
   private getWordObjectRange(
-    kind: "i" | "a",
+    kind: TextObjectKind,
     count: number = 1,
-  ): { startAbs: number; endAbs: number } | null {
+    semanticClass: WordTextObjectClass = "word",
+  ): TextObjectRange | null {
     const lines = this.getLines();
     const cursor = this.getCursor();
     const line = lines[cursor.line] ?? "";
-    if (!line) return null;
-
-    const steps = Math.max(1, Math.min(MAX_COUNT, count));
-    const hasWordChar = (idx: number) => idx >= 0 && idx < line.length && this.isWordChar(line[idx]!);
-
-    let col = Math.min(cursor.col, Math.max(0, line.length - 1));
-
-    if (!hasWordChar(col)) {
-      let right = col;
-      while (right < line.length && !hasWordChar(right)) right++;
-      if (right < line.length) {
-        col = right;
-      } else {
-        let left = Math.min(col, line.length - 1);
-        while (left >= 0 && !hasWordChar(left)) left--;
-        if (left < 0) return null;
-        col = left;
-      }
-    }
-
-    let start = col;
-    while (start > 0 && hasWordChar(start - 1)) start--;
-
-    let end = col + 1;
-    while (end < line.length && hasWordChar(end)) end++;
+    const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
 
-    let remaining = steps - 1;
-    while (remaining > 0) {
-      let nextWordStart = end;
-      while (nextWordStart < line.length && !hasWordChar(nextWordStart)) nextWordStart++;
-      if (nextWordStart >= line.length) break;
+    return resolveWordTextObjectRange(
+      line,
+      lineStartAbs,
+      cursor.col,
+      kind,
+      count,
+      semanticClass,
+    );
+  }
 
-      let nextWordEnd = nextWordStart + 1;
-      while (nextWordEnd < line.length && hasWordChar(nextWordEnd)) nextWordEnd++;
+  private static readonly PUT_SIZE_LIMIT = 512 * 1024; // 512 KB safety cap
 
-      end = nextWordEnd;
-      remaining--;
+  private getPasteRegisterText(): string {
+    if (this.clipboardMirror.hasPendingWrite()) {
+      return this.unnamedRegister;
     }
 
-    if (kind === "a") {
-      let aroundEnd = end;
-      while (aroundEnd < line.length && /\s/.test(line[aroundEnd]!)) aroundEnd++;
-
-      if (aroundEnd > end) {
-        end = aroundEnd;
-      } else {
-        while (start > 0 && /\s/.test(line[start - 1]!)) start--;
-      }
+    try {
+      const clipboardText = this.clipboardReadFn();
+      return clipboardText ?? this.unnamedRegister;
+    } catch {
+      return this.unnamedRegister;
     }
-
-    return {
-      startAbs: this.getAbsoluteIndex(cursor.line, start),
-      endAbs: this.getAbsoluteIndex(cursor.line, end),
-    };
   }
 
-  private static readonly PUT_SIZE_LIMIT = 512 * 1024; // 512 KB safety cap
-
   private putAfter(): void {
     const count = this.takeTotalCount(1);
-    const text = this.unnamedRegister;
+    const text = this.getPasteRegisterText();
     if (!text) return;
     const safeCount = Math.min(count, Math.max(1, Math.floor(ModalEditor.PUT_SIZE_LIMIT / text.length)));
 
@@ -2168,7 +2889,7 @@ export class ModalEditor extends CustomEditor {
 
   private putBefore(): void {
     const count = this.takeTotalCount(1);
-    const text = this.unnamedRegister;
+    const text = this.getPasteRegisterText();
     if (!text) return;
     const safeCount = Math.min(count, Math.max(1, Math.floor(ModalEditor.PUT_SIZE_LIMIT / text.length)));
 
@@ -2210,24 +2931,112 @@ export class ModalEditor extends CustomEditor {
     this.deleteRangeByAbsolute(lineStartAbs + start, lineStartAbs + end);
   }
 
+  private takeModeLabelSuffix(rawLabel: string, width: number): string {
+    if (width <= 0) return "";
+
+    const graphemes = getLineGraphemes(rawLabel);
+    const suffix: string[] = [];
+    let usedWidth = 0;
+
+    for (let i = graphemes.length - 1; i >= 0; i--) {
+      const grapheme = graphemes[i];
+      if (!grapheme) continue;
+
+      const segment = rawLabel.slice(grapheme.start, grapheme.end);
+      const segmentWidth = visibleWidth(segment);
+      if (usedWidth + segmentWidth > width) break;
+      suffix.push(segment);
+      usedWidth += segmentWidth;
+    }
+
+    return suffix.reverse().join("");
+  }
+
+  private fitModeLabel(rawLabel: string, width: number): string {
+    if (visibleWidth(rawLabel) <= width) return rawLabel;
+
+    const prefix = rawLabel.startsWith(" INSERT ")
+      ? " INSERT "
+      : rawLabel.startsWith(" NORMAL ")
+        ? " NORMAL "
+        : rawLabel.startsWith(" EX ")
+          ? " EX "
+          : "";
+
+    if (!prefix || visibleWidth(prefix) >= width) {
+      return truncateToWidth(rawLabel, width, "");
+    }
+
+    const suffixWidth = width - visibleWidth(prefix) - 1;
+    if (suffixWidth <= 0) return `${prefix}…`;
+    return `${prefix}…${this.takeModeLabelSuffix(rawLabel, suffixWidth)}`;
+  }
+
+  private getDesiredCursorShapeSequence(): CursorShapeSequence {
+    return this.mode === "insert" && this.pendingExCommand === null
+      ? INSERT_CURSOR_SHAPE
+      : BLOCK_CURSOR_SHAPE;
+  }
+
+  private hasPromptCursorMarker(lines: string[]): boolean {
+    return lines.some((line) => line.includes(CURSOR_MARKER));
+  }
+
+  private stripSoftwareCursorWhenHardwareCursorIsUsed(lines: string[]): void {
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i];
+      if (!line?.includes(CURSOR_MARKER)) continue;
+
+      lines[i] = stripSoftwareCursorAfterMarker(line);
+      return;
+    }
+  }
+
+  private syncCursorShapeForRender(lines: string[]): void {
+    if (!this.cursorShapeRuntime) return;
+    if (!this.hasPromptCursorMarker(lines)) return;
+
+    if (this.cursorShapeRuntime.getShowHardwareCursor?.() === false) {
+      this.lastCursorShapeSequence = null;
+      return;
+    }
+
+    this.stripSoftwareCursorWhenHardwareCursorIsUsed(lines);
+
+    const sequence = this.getDesiredCursorShapeSequence();
+    if (sequence === this.lastCursorShapeSequence) return;
+
+    this.cursorShapeRuntime.writeCursorShape(sequence);
+    this.lastCursorShapeSequence = sequence;
+  }
+
   render(width: number): string[] {
     const lines = super.render(width);
+    this.syncCursorShapeForRender(lines);
     if (lines.length === 0) return lines;
 
-    const rawLabel = this.getModeLabel();
-    const colorize = this.labelColorizers
-      ? (this.mode === "insert" ? this.labelColorizers.insert : this.labelColorizers.normal)
-      : null;
+    const rawLabel = this.fitModeLabel(this.getModeLabel(), width);
+    const colorize = this.getModeLabelColorizer();
     const label = colorize ? colorize(rawLabel) : rawLabel;
     const last = lines.length - 1;
-    if (visibleWidth(lines[last]!) >= visibleWidth(rawLabel)) {
-      lines[last] = truncateToWidth(lines[last]!, width - visibleWidth(rawLabel), "") + label;
+    const lastLine = lines[last];
+    if (lastLine && visibleWidth(lastLine) >= visibleWidth(rawLabel)) {
+      lines[last] = truncateToWidth(lastLine, width - visibleWidth(rawLabel), "") + label;
+    } else {
+      lines[last] = label;
     }
     return lines;
   }
 
+  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;
+  }
+
   private getModeLabel(): string {
     if (this.mode === "insert") return " INSERT ";
+    if (this.pendingExCommand !== null) return ` EX ${this.pendingExCommand}_ `;
 
     const prefixCount = this.prefixCount;
     const operatorCount = this.operatorCount;
@@ -2255,12 +3064,37 @@ export class ModalEditor extends CustomEditor {
 }
 
 export default function (pi: ExtensionAPI) {
+  let cursorShapeCleanup: CursorShapeCleanup | null = null;
+
   pi.on("session_start", (_event, ctx) => {
+    const piVimSettings = readPiVimSettings(ctx.cwd);
+    const clipboardMirrorPolicy = resolveClipboardMirrorPolicy(piVimSettings.clipboardMirror);
+    if (clipboardMirrorPolicy.warning && ctx.hasUI) {
+      ctx.ui.notify(clipboardMirrorPolicy.warning, "warning");
+    }
+
     const t = ctx.ui.theme;
+    const reverseVideo = (s: string) => `\x1b[7m${s}\x1b[27m`;
     const colorizers = t ? {
-      insert: (s: string) => t.fg("borderMuted", `\x1b[7m${s}\x1b[27m`),
-      normal: (s: string) => t.fg("borderAccent", `\x1b[7m${s}\x1b[27m`),
+      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;
-    ctx.ui.setEditorComponent((tui, theme, kb) => new ModalEditor(tui, theme, kb, colorizers));
+    ctx.ui.setEditorComponent((tui, theme, kb) => {
+      cursorShapeCleanup = enableCursorShapeSupport(tui);
+      const editor = new ModalEditor(tui, theme, kb, colorizers);
+      editor.setClipboardMirrorPolicy(clipboardMirrorPolicy.policy);
+      editor.setQuitFn(() => ctx.shutdown());
+      editor.setNotifyFn((message) => ctx.ui.notify(message, "warning"));
+      return editor;
+    });
+  });
+
+  pi.on("session_shutdown", () => {
+    try {
+      cursorShapeCleanup?.();
+    } finally {
+      cursorShapeCleanup = null;
+    }
   });
 }