@aemonge-dev/pi-stardeck 0.0.0-stage → 0.6.0

package/packages/pi-vim-top-border/index.ts

@@ -0,0 +1,4195 @@
+import {
+  CustomEditor,
+  getAgentDir,
+  type ExtensionAPI,
+  type Theme,
+} from '@earendil-works/pi-coding-agent';
+import { Key, matchesKey } from '@earendil-works/pi-tui';
+import { ClipboardMirror, writeClipboardInChildProcess } from './clipboard-mirror.js';
+import {
+  type ClipboardMirrorPolicy,
+  DEFAULT_CLIPBOARD_MIRROR_POLICY,
+  type RegisterWriteSource,
+  resolveClipboardMirrorPolicy,
+} from './clipboard-policy.js';
+import {
+  BLOCK_CURSOR_SHAPE,
+  type CursorShapeCleanup,
+  type CursorShapeRuntime,
+  type CursorShapeSequence,
+  enableCursorShapeSupport,
+  getCursorShapeRuntime,
+  hasPromptCursorMarker,
+  INSERT_CURSOR_SHAPE,
+  stripSoftwareCursorWhenHardwareCursorIsUsed,
+} from './cursor-shape.js';
+import {
+  isBackspaceLikeInput,
+  isCountStarter,
+  isDigit,
+  isEnterLikeInput,
+  isEscapeLikeInput,
+  isPrintableChunk,
+  isPrintableInput,
+} from './input-keys.js';
+import {
+  cancelModeChangeCommands,
+  createModeChangeHandler,
+  setModeChangeCommandRunnerForTests,
+} from './mode-change-command.js';
+import {
+  buildModeColorizers,
+  buildOffBorderColor,
+  isNeutralBorder,
+  type ModeColorizers,
+  type ModeColorKey,
+  resolveModeColors,
+} from './mode-colors.js';
+import { MODE_ICONS } from './mode-label.js';
+import {
+  findCharMotionTarget,
+  findFirstNonWhitespaceColumn,
+  findParagraphMotionTarget,
+  getLineGraphemes,
+  reverseCharMotion,
+  type WordMotionClass,
+} from './motions.js';
+import {
+  PromptExternalEditor,
+  type PromptExternalEditorResult,
+} from './prompt-external-editor.js';
+import {
+  collectSessionCost,
+  FANCY_FOOTER_WIDGET_CHANNEL,
+  type PromptRailColorize,
+  type PromptRailSnapshot,
+  PromptRailStore,
+  renderPromptRails,
+} from './prompt-rail.js';
+import {
+  DEFAULT_EX_COMMAND_SETTINGS,
+  type ExCommandSettings,
+  readPiVimSettings,
+  resolveExCommandSettings,
+  resolveSurfaceSyncMaps,
+  type SurfaceSyncMap,
+} from './settings.js';
+import {
+  resolveDelimitedTextObjectRange,
+  resolveMatchingPairMotionTarget,
+  resolveWordTextObjectRange,
+  type TextObjectKind,
+  type TextObjectRange,
+  type WordTextObjectClass,
+} from './text-objects.js';
+import type {
+  CharMotion,
+  LastCharMotion,
+  Mode,
+  PendingMotion,
+  PendingOperator,
+} from './types.js';
+import {
+  CHAR_MOTION_KEYS,
+  CTRL_A,
+  CTRL_E,
+  CTRL_K,
+  CTRL_R,
+  CTRL_UNDERSCORE,
+  CTRL_V,
+  ESC_DOWN,
+  ESC_LEFT,
+  ESC_RIGHT,
+  ESC_UP,
+  NEWLINE,
+  NORMAL_KEYS,
+} from './types.js';
+import {
+  clampVisualPosition,
+  getInclusiveEndColumn,
+  getVisualLineRange,
+  isVisualMode,
+  orderVisualEndpoints,
+  type VisualMode,
+  type VisualPosition,
+} from './visual.js';
+import {
+  WordBoundaryCache,
+  type WordMotionDirection,
+  type WordMotionTarget,
+} from './word-boundary-cache.js';
+
+export { setModeChangeCommandRunnerForTests };
+
+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 TEXT_INSERT_REPEAT_KEYS = new Set(['i', 'a', 'A', 'I']);
+const OPEN_LINE_REPEAT_KEYS = new Set(['o', 'O']);
+const REPEATABLE_COMMAND_START_KEYS = new Set([
+  'd',
+  'c',
+  'r',
+  'p',
+  'P',
+  'J',
+  'g',
+  ...TEXT_INSERT_REPEAT_KEYS,
+  ...OPEN_LINE_REPEAT_KEYS,
+  'D',
+  'C',
+  'S',
+  's',
+  'x',
+  'X',
+]);
+// Normal-mode commands that must never run while a visual selection is live.
+// They are swallowed instead of falling through to the normal-mode dispatch.
+const VISUAL_IGNORED_KEYS = new Set([
+  'p',
+  'P',
+  'r',
+  'J',
+  'u',
+  'U',
+  '~',
+  '>',
+  '<',
+  '.',
+  ':',
+  'i',
+  'a',
+  'A',
+  'I',
+  'R',
+  CTRL_R,
+  CTRL_UNDERSCORE,
+]);
+
+// Pi's builtin slash commands. `pi.getCommands()` reports only extension,
+// prompt and skill commands; the builtin list is not re-exported from the
+// package's public entry point, so it is mirrored here. A name missing from
+// this mirror simply falls through to "Unsupported ex command".
+const EX_BUILTIN_COMMAND_NAMES: ReadonlySet<string> = new Set([
+  'settings',
+  'model',
+  'scoped-models',
+  'export',
+  'import',
+  'share',
+  'copy',
+  'name',
+  'session',
+  'changelog',
+  'hotkeys',
+  'fork',
+  'clone',
+  'tree',
+  'login',
+  'logout',
+  'new',
+  'compact',
+  'resume',
+  'reload',
+  'quit',
+  'trust',
+]);
+
+type EditorSnapshot = {
+  text: string;
+  cursor: { line: number; col: number };
+};
+
+type CommandDispatchResult = void | PromiseLike<void>;
+
+type DispatchState = {
+  snapshot: EditorSnapshot;
+  restore: () => void;
+};
+
+type RepeatRecording = {
+  /** Raw key inputs that reconstruct one repeatable normal-mode change. */
+  keys: string[];
+  /** Replay keys without command counts, used when `{count}.` overrides them. */
+  countOverrideKeys: string[];
+  /** Buffer mutation version before the command started. */
+  startChangeVersion: number;
+  /** True while the command is collecting insert-mode input until Escape. */
+  captureInsert: boolean;
+  /** True when a command completed even if it emitted no mutation event. */
+  forceCommit: boolean;
+};
+
+type RepeatableCommand = Pick<RepeatRecording, 'keys' | 'countOverrideKeys'>;
+
+type TransitionState = 'none' | 'undo' | 'redo' | 'restore';
+
+type ModalEditorInternals = {
+  state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+  preferredVisualCol?: number | null;
+  lastAction?: string | null;
+  historyIndex?: number;
+  onChange?: (text: string) => void;
+  tui?: { requestRender?: () => void };
+  pushUndoSnapshot?: () => void;
+  setCursorCol?: (col: number) => void;
+  undoStack?: { readonly length: number; pop(): unknown; stack: unknown[] };
+};
+
+type CustomEditorConstructorArgs = ConstructorParameters<typeof CustomEditor>;
+
+export type PiVimModeRail = { plain: string; styled: string };
+
+type ModalEditorOptions = {
+  labelColorizers?: ModeColorizers | null;
+  borderColorizers?: ModeColorizers | null;
+  // Per-mode paint policy for each surface. "mode" paints the mode color;
+  // "host" shows the host's current border color; "thinking" shows the host
+  // color only while the host border is away from its neutral resting default.
+  // Absent → every mode "mode" (paint the colorizers this editor was given).
+  borderSync?: SurfaceSyncMap | null;
+  labelSync?: SurfaceSyncMap | null;
+  // Renders Pi's neutral "thinking off" border color. Lets "thinking" tell the
+  // resting border apart from an active thinking level or another extension's
+  // highlight. When omitted, "thinking" treats every host border as neutral and
+  // always paints the mode color.
+  offBorderColor?: ((s: string) => string) | null;
+  // Optional text transform applied to the label after its foreground color.
+  labelTransform?: ((s: string) => string) | null;
+  getPromptRail?: () => PromptRailSnapshot;
+  promptRailColorize?: PromptRailColorize;
+  promptRailsEnabled?: boolean;
+  editorFrameEnabled?: boolean;
+  externalEditorOnly?: boolean;
+  deckRenderer?: ((width: number, modeRail: PiVimModeRail) => string[]) | null;
+};
+
+export class ModalEditor extends CustomEditor {
+  private readonly appKeybindings: CustomEditorConstructorArgs[2];
+  private mode: Mode = 'insert';
+  private pendingMotion: PendingMotion = 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 visualAnchor: VisualPosition | null = null;
+  private pendingExCommand: string | null = null;
+  private acceptingBracketedPasteInExCommand: boolean = false;
+  private pendingEscWhileAcceptingBracketedPasteInExCommand: boolean = false;
+  private discardingPasteAfterNewlineInExCommand: boolean = false;
+  private lastCharMotion: LastCharMotion | null = null;
+  private discardingBracketedPasteInNormalMode: boolean = false;
+  private pendingEscWhileDiscardingBracketedPasteInNormalMode: boolean = false;
+  private wordBoundaryCache = new WordBoundaryCache();
+  private readonly redoStack: EditorSnapshot[] = [];
+  private lastRepeatableCommand: RepeatableCommand | null = null;
+  private repeatRecording: RepeatRecording | null = null;
+  private implicitInsertSuppressed: boolean = false;
+  private replayingRepeat: boolean = false;
+  private repeatReplayFailed: boolean = false;
+  private bufferChangeVersion: number = 0;
+  /**
+   * One undo window per vim change, opened on the recorder's change boundaries
+   * (or a visual mutating operator). `floor` is the host `undoStack.length` at
+   * open; `openVersion` the `bufferChangeVersion`. On close the host stack is
+   * collapsed to `floor + 1`, so one host snapshot equals one vim change.
+   */
+  private undoWindow: { floor: number; openVersion: number } | null = null;
+  private currentTransition: TransitionState = 'none';
+  private onChangeHooked: boolean = false;
+  private readonly labelColorizers: ModeColorizers | null;
+  private readonly borderColorizers: ModeColorizers | null;
+  private borderOverride: ((text: string) => string) | null = null;
+  private readonly offBorderColor: ((s: string) => string) | null;
+  // Latest host-assigned border color and whether it is the neutral resting
+  // default. Kept as mutable instance fields (not closure locals) so the label
+  // resolver can read the same thinking state the border uses.
+  private borderBase: ((s: string) => string) | null = null;
+  private borderBaseIsNeutral = true;
+  // Per-mode paint policy for each surface (border and label). Null → every
+  // mode defaults to "mode" (paint the mode color).
+  private readonly borderSync: SurfaceSyncMap | null;
+  private readonly labelSync: SurfaceSyncMap | null;
+  // Optional label transform; null keeps foreground-only mode styling.
+  private labelTransform: ((s: string) => string) | null = null;
+  private readonly cursorShapeRuntime: CursorShapeRuntime | null;
+  private lastCursorShapeSequence: CursorShapeSequence | null = null;
+  private readonly getPromptRail: () => PromptRailSnapshot;
+  private readonly promptRailColorize: PromptRailColorize;
+  private readonly promptRailsEnabled: boolean;
+  private readonly editorFrameEnabled: boolean;
+  private readonly externalEditorOnly: boolean;
+  private readonly deckRenderer:
+    | ((width: number, modeRail: PiVimModeRail) => string[])
+    | null;
+  private pendingExternalEditorOpen = false;
+  private externalEditorActive = false;
+
+  private unnamedRegister: string = '';
+  private clipboardMirrorPolicy: ClipboardMirrorPolicy =
+    DEFAULT_CLIPBOARD_MIRROR_POLICY;
+  private readonly clipboardMirror = new ClipboardMirror(writeClipboardInChildProcess);
+  private expectingNativePaste: 'editor' | 'send' | null = null;
+  private nativePasteStarted = false;
+  private quitFn: () => void = () => {};
+  private notifyFn: (message: string) => void = () => {};
+  private modeChangeFn: (mode: Mode, prevMode: Mode) => void = () => {};
+  private exCommandSettings: ExCommandSettings = DEFAULT_EX_COMMAND_SETTINGS;
+  private commandNamesFn: () => ReadonlySet<string> = () => EX_BUILTIN_COMMAND_NAMES;
+  private externalEditorFn:
+    | (() => Promise<PromptExternalEditorResult> | undefined)
+    | null = null;
+  // Pi has no public command-dispatch API. The editor's own submit path is the
+  // one mechanism that reaches every command kind (builtin, extension, skill,
+  // prompt), so dispatching `:name` is literally the user typing `/name` and
+  // pressing Enter. Injectable so tests need no live pi runtime.
+  private runCommandFn: (commandLine: string) => CommandDispatchResult = (
+    commandLine,
+  ) => {
+    const submit = this.onSubmit as
+      | ((text: string) => CommandDispatchResult)
+      | undefined;
+    if (!submit) return;
+    this.setText(commandLine);
+    return submit(commandLine);
+  };
+  private pendingAsyncDispatches: number = 0;
+  private restoreLatestDispatchStateFn: (() => void) | null = null;
+
+  constructor(
+    tui: CustomEditorConstructorArgs[0],
+    theme: CustomEditorConstructorArgs[1],
+    kb: CustomEditorConstructorArgs[2],
+    opts?: ModalEditorOptions,
+  ) {
+    super(tui, theme, kb);
+    this.appKeybindings = kb;
+    this.cursorShapeRuntime = getCursorShapeRuntime(tui);
+    this.labelColorizers = opts?.labelColorizers ?? null;
+    this.borderColorizers = opts?.borderColorizers ?? null;
+    this.offBorderColor = opts?.offBorderColor ?? null;
+    this.borderSync = opts?.borderSync ?? null;
+    this.labelSync = opts?.labelSync ?? null;
+    this.labelTransform = opts?.labelTransform ?? null;
+    this.getPromptRail =
+      opts?.getPromptRail ?? (() => ({ widgets: new Map(), totalCost: 0 }));
+    this.promptRailColorize = opts?.promptRailColorize ?? ((_color, text) => text);
+    this.promptRailsEnabled = opts?.promptRailsEnabled ?? true;
+    this.editorFrameEnabled = opts?.editorFrameEnabled ?? true;
+    this.externalEditorOnly = opts?.externalEditorOnly ?? false;
+    this.deckRenderer = opts?.deckRenderer ?? null;
+    if (this.externalEditorOnly) this.mode = 'normal';
+    this.installModeBorderColorizer();
+  }
+
+  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);
+  }
+  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;
+  }
+  setExternalEditorFn(
+    fn: (() => Promise<PromptExternalEditorResult> | undefined) | null,
+  ): void {
+    this.externalEditorFn = fn;
+  }
+  setBorderOverride(colorizer: ((text: string) => string) | null): void {
+    this.borderOverride = colorizer;
+    const editor = this as unknown as ModalEditorInternals;
+    editor.tui?.requestRender?.();
+  }
+  setModeChangeFn(fn: (mode: Mode, prevMode: Mode) => void): void {
+    this.modeChangeFn = fn;
+  }
+  setRunCommandFn(fn: (commandLine: string) => CommandDispatchResult): void {
+    this.runCommandFn = fn;
+  }
+  setCommandNamesFn(fn: () => ReadonlySet<string>): void {
+    this.commandNamesFn = fn;
+  }
+  setExCommandSettings(settings: ExCommandSettings): void {
+    this.exCommandSettings = settings;
+  }
+  getRegister(): string {
+    return this.unnamedRegister;
+  }
+  setRegister(text: string): void {
+    this.unnamedRegister = text;
+  }
+  getMode(): Mode {
+    return this.mode;
+  }
+  getText(): string {
+    return this.getLines().join('\n');
+  }
+
+  private getActiveMode(): ModeColorKey {
+    if (this.externalEditorActive) return 'insert';
+    if (this.pendingExCommand !== null) return 'ex';
+    if (this.mode === 'insert') return 'insert';
+    if (isVisualMode(this.mode)) return 'visual';
+    return 'normal';
+  }
+
+  /**
+   * Resolve a surface (border or label) color for the active mode under its
+   * per-mode paint policy:
+   *   - "mode"     always paints the mode color;
+   *   - "host"     always shows the host's current border color;
+   *   - "thinking" shows the host color while the host border is away from its
+   *                neutral resting default, otherwise paints the mode color.
+   * A missing policy map defaults every mode to "mode". `deferWrap` is identity
+   * for the border and reverse-video for the label, so a deferred host color
+   * inherits the surface's normal styling.
+   */
+  private resolveSurfaceColor(
+    colorizers: ModeColorizers,
+    syncMap: SurfaceSyncMap | null,
+    text: string,
+    deferWrap: (s: string) => string,
+  ): string {
+    const mode = this.getActiveMode();
+    const modeColorFn = colorizers[mode] ?? ((s: string) => s);
+    const policy = syncMap ? syncMap[mode] : 'mode';
+    if (policy === 'mode' || (policy === 'thinking' && this.borderBaseIsNeutral)) {
+      return modeColorFn(text);
+    }
+    // Defer to the host border color ("host" always; "thinking" only while the
+    // host border is non-neutral), wrapped the way this surface styles its text.
+    const host = this.borderBase ?? modeColorFn;
+    return deferWrap(host(text));
+  }
+
+  // The border trap recolors the border getter, tracks host assignments, and
+  // provides the temporary inactive override used during Neovim handoff. It is
+  // installed for every configured editor surface; host-synced modes still
+  // resolve to the byte-identical host color when no override is active.
+  private installModeBorderColorizer(): void {
+    if (!this.borderColorizers) return;
+    // Capture the values the getter/setter close over so the traps never
+    // depend on late `this` rebinding. The accessors themselves are arrow
+    // functions, so their `this` is this editor instance.
+    const borderColorizers = this.borderColorizers;
+    const offBorderColor = this.offBorderColor;
+    // Seed the instance fields from whatever the host assigned before the trap
+    // was installed (usually the inherited default border).
+    this.borderBase = this.borderColor;
+    this.borderBaseIsNeutral = isNeutralBorder(this.borderBase, offBorderColor);
+    const resolvedBorderColor = (text: string) =>
+      this.borderOverride?.(text) ??
+      this.resolveSurfaceColor(borderColorizers, this.borderSync, text, (s) => s);
+    // Pi assigns its default border color after extension editor construction.
+    // Keep a mode-aware getter installed and treat later assignments as the
+    // host base color, otherwise the border sync is overwritten in real
+    // sessions even though direct editor tests pass. Reclassify on every host
+    // assignment so a thinking-level cycle off -> on -> off is honored.
+    Object.defineProperty(this, 'borderColor', {
+      get: () => resolvedBorderColor,
+      set: (next: unknown) => {
+        if (typeof next === 'function') {
+          this.borderBase = next as (s: string) => string;
+          this.borderBaseIsNeutral = isNeutralBorder(this.borderBase, offBorderColor);
+        }
+      },
+    });
+  }
+
+  private setMode(mode: Mode = 'insert'): void {
+    const prev = this.mode;
+    const next = this.externalEditorOnly && mode === 'insert' ? 'normal' : mode;
+    this.mode = next;
+    if (next !== 'normal') this.cancelNativePasteExpectation();
+    if (this.externalEditorOnly && mode === 'insert') {
+      this.pendingExternalEditorOpen = true;
+    }
+    // Leaving insert ends any host-tainted session, so the next implicit
+    // insert (post-submit or a re-entry) records normally again.
+    if (prev === 'insert' && next !== 'insert') {
+      this.implicitInsertSuppressed = false;
+    }
+    if (prev !== next) {
+      try {
+        this.modeChangeFn(next, prev);
+      } catch {
+        // mode-change side effects must never break editing
+      }
+    }
+  }
+
+  private flushPendingExternalEditorOpen(): void {
+    if (!this.pendingExternalEditorOpen) return;
+    this.pendingExternalEditorOpen = false;
+    this.openExternalEditor();
+  }
+
+  private requestEditorRender(): void {
+    const editor = this as unknown as ModalEditorInternals;
+    editor.tui?.requestRender?.();
+  }
+
+  private finishExternalEditor(result?: PromptExternalEditorResult): void {
+    this.externalEditorActive = false;
+    this.requestEditorRender();
+    if (this.externalEditorOnly && result === 'saved') {
+      super.handleInput('\r');
+    }
+  }
+
+  private openExternalEditor(): void {
+    if (this.externalEditorActive || !this.externalEditorFn) return;
+    this.externalEditorActive = true;
+    this.requestEditorRender();
+
+    let result: Promise<PromptExternalEditorResult> | undefined;
+    try {
+      result = this.externalEditorFn();
+    } catch {
+      this.finishExternalEditor('failed');
+      return;
+    }
+
+    void Promise.resolve(result).then(
+      (outcome) => this.finishExternalEditor(outcome),
+      () => this.finishExternalEditor('failed'),
+    );
+  }
+
+  override setText(text: string): void {
+    this.discardUndoWindow();
+    this.clearRedoStack();
+    this.clearRepeatState();
+    // A full host buffer reset starts a fresh session: later typing is a new
+    // implicit insert, not a continuation of a host-tainted one.
+    this.implicitInsertSuppressed = false;
+    super.setText(text);
+    this.refreshPendingDispatchRestore(true);
+  }
+
+  override insertTextAtCursor(text: string): void {
+    this.discardUndoWindow();
+    this.cancelRepeatableCommand();
+    // A host injection mid-insert taints the session: the injected text is not
+    // ours to replay, and neither is any typing that continues around it.
+    this.implicitInsertSuppressed = true;
+    super.insertTextAtCursor(text);
+    this.refreshPendingDispatchRestore(true);
+
+    // Pi's native clipboard paste (`handleClipboardPaste`) delivers its text
+    // (or the image's temp-file path) through this seam, asynchronously after
+    // p/P synthesized ctrl+v. Fire the pending follow-up once it has landed.
+    if (this.expectingNativePaste !== null) {
+      const action = this.expectingNativePaste;
+      this.cancelNativePasteExpectation();
+      this.finishNativePaste(action);
+    }
+  }
+
+  /**
+   * While an async EX dispatch is pending, the prompt the settle handler will
+   * reapply must track the *latest* buffer, not only what `handleInput`
+   * produced. A wrapper mutating the prompt out of band through the public
+   * setters refreshes the snapshot here, so a late-settling dispatch that
+   * clears the prompt restores the wrapper's newer text instead of the stale
+   * pre-dispatch state.
+   *
+   * A public setter that empties the buffer is skipped: that is the async
+   * clear the restore exists to compensate for (or a wrapper clearing), so
+   * capturing it would defeat the reapply. `handleInput` still refreshes on any
+   * result, including an intentional emptying edit like `dd`.
+   */
+  private refreshPendingDispatchRestore(fromPublicSetter = false): void {
+    if (this.pendingAsyncDispatches === 0) return;
+    if (fromPublicSetter && this.getText() === '') return;
+    this.restoreLatestDispatchStateFn = this.captureDispatchState().restore;
+  }
+
+  private captureSnapshot(): EditorSnapshot {
+    const cursor = this.getCursor();
+    return {
+      text: this.getText(),
+      cursor: { line: cursor.line, col: cursor.col },
+    };
+  }
+
+  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;
+    };
+  }
+
+  private restoreSnapshot(snapshot: EditorSnapshot): void {
+    const editor = this as unknown as ModalEditorInternals;
+    const state = this.requireRedoRestoreState(editor);
+
+    const lines = snapshot.text.split('\n');
+    state.lines = lines.length > 0 ? lines : [''];
+
+    const maxLine = Math.max(0, state.lines.length - 1);
+    const cursorLine = Math.max(0, Math.min(snapshot.cursor.line, maxLine));
+    const line = state.lines[cursorLine] ?? '';
+    const cursorCol = Math.max(0, Math.min(snapshot.cursor.col, line.length));
+
+    state.cursorLine = cursorLine;
+    if (typeof editor.setCursorCol === 'function') {
+      editor.setCursorCol(cursorCol);
+    } else {
+      state.cursorCol = cursorCol;
+      editor.preferredVisualCol = null;
+    }
+
+    this.invalidateWordBoundaryCache();
+
+    editor.historyIndex = -1;
+    editor.lastAction = null;
+    editor.onChange?.(this.getText());
+    editor.tui?.requestRender?.();
+  }
+
+  private snapshotChanged(a: EditorSnapshot, b: EditorSnapshot): boolean {
+    return (
+      a.text !== b.text ||
+      a.cursor.line !== b.cursor.line ||
+      a.cursor.col !== b.cursor.col
+    );
+  }
+
+  private withTransition<T>(
+    transition: Exclude<TransitionState, 'none'>,
+    action: () => T,
+  ): T {
+    const previousTransition = this.currentTransition;
+    this.currentTransition = transition;
+    try {
+      return action();
+    } finally {
+      this.currentTransition = previousTransition;
+    }
+  }
+
+  private performUndo(count: number = this.takeTotalCount(1)): void {
+    this.discardUndoWindow();
+    const maxSteps = Math.max(1, Math.min(MAX_COUNT, count));
+    for (let i = 0; i < maxSteps; i++) {
+      let changed = false;
+      this.withTransition('undo', () => {
+        const beforeUndo = this.captureSnapshot();
+        super.handleInput(CTRL_UNDERSCORE);
+        const afterUndo = this.captureSnapshot();
+
+        if (this.snapshotChanged(beforeUndo, afterUndo)) {
+          this.redoStack.push(beforeUndo);
+          changed = true;
+        }
+      });
+      if (!changed) break;
+    }
+  }
+
+  private performRedo(count: number = this.takeTotalCount(1)): void {
+    this.discardUndoWindow();
+    const maxSteps = Math.max(1, Math.min(MAX_COUNT, count));
+    const editor = this as unknown as ModalEditorInternals;
+
+    for (let i = 0; i < maxSteps; i++) {
+      const snapshot = this.redoStack[this.redoStack.length - 1];
+      if (!snapshot) break;
+
+      this.withTransition('redo', () => {
+        this.requireRedoRestoreState(editor);
+        if (typeof editor.pushUndoSnapshot !== 'function') {
+          throw new Error('Redo restore prerequisite: pushUndoSnapshot unavailable');
+        }
+        editor.pushUndoSnapshot();
+        this.restoreSnapshot(snapshot);
+        this.redoStack.pop();
+      });
+    }
+  }
+
+  private clearRedoStack(): void {
+    this.redoStack.length = 0;
+  }
+
+  private invalidateWordBoundaryCache(): void {
+    this.wordBoundaryCache = new WordBoundaryCache();
+  }
+
+  private ensureOnChangeHook(): void {
+    if (this.onChangeHooked) return;
+
+    const editor = this as unknown as ModalEditorInternals;
+    const originalOnChange = editor.onChange;
+
+    editor.onChange = (text: string) => {
+      originalOnChange?.(text);
+      this.bufferChangeVersion++;
+      this.centralInvalidationCheck();
+    };
+
+    this.onChangeHooked = true;
+  }
+
+  private centralInvalidationCheck(): void {
+    if (this.redoStack.length === 0) return;
+    if (this.currentTransition !== 'none') return;
+    this.clearRedoStack();
+  }
+
+  private isRepeatRecordingInProgress(): boolean {
+    return (
+      this.pendingMotion !== null ||
+      this.pendingTextObject !== null ||
+      this.pendingOperator !== null ||
+      this.pendingG ||
+      this.pendingReplace
+    );
+  }
+
+  private isRepeatableCommandStart(key: string): boolean {
+    return REPEATABLE_COMMAND_START_KEYS.has(key);
+  }
+
+  private isOperatorCountDigit(key: string): boolean {
+    return isDigit(key) && (key !== '0' || this.operatorCount.length > 0);
+  }
+
+  private shouldStripKeyFromCountOverride(key: string): boolean {
+    if (this.mode === 'insert') return false;
+    if (this.pendingMotion || this.pendingTextObject || this.pendingReplace) {
+      return false;
+    }
+    if (!this.pendingOperator) return false;
+    return this.isOperatorCountDigit(key);
+  }
+
+  /**
+   * Every Enter encoding Pi submits on: legacy `\r` plus the Kitty keyboard
+   * protocol's CSI-u forms (`\x1b[13u`, numpad Enter, the modifier-0 variants).
+   * `\n` is deliberately excluded: pi-vim treats it as the shift+enter newline
+   * (see the implicit-insert newline dot-repeat test), so it stays captured as
+   * typed text rather than cancelling the recording.
+   */
+  private isSubmitEnterInput(key: string): boolean {
+    return key !== '\n' && matchesKey(key, 'enter');
+  }
+
+  private shouldCancelInsertRepeatInput(key: string): boolean {
+    // A submit must cancel the recording, not be captured into it. A bare `\r`
+    // check missed the Kitty CSI-u Enter (`\x1b[13u`), letting it be recorded
+    // and then re-submitted on replay.
+    if (this.isSubmitEnterInput(key)) return true;
+    return key === '\t' && this.isShowingAutocomplete();
+  }
+
+  /**
+   * Dot-repeat is recorded by watching the key stream for one normal-mode
+   * change. The raw key stream is kept for plain `.`, while a second stream
+   * strips normal-mode command counts so `{count}.` can replace the stored
+   * count like Vim instead of multiplying it by repeated replay.
+   */
+  private prepareRepeatRecordingForInput(key: string): void {
+    if (this.replayingRepeat || this.pendingExCommand !== null) return;
+
+    // Visual-mode operators are not dot-repeatable; they clear the stored
+    // command instead of recording a normal-mode key stream that would replay
+    // as something else entirely.
+    if (isVisualMode(this.mode)) return;
+
+    if (this.mode === 'insert') {
+      if (this.shouldCancelInsertRepeatInput(key)) {
+        this.clearRepeatState();
+        // A submit clears the host undo stack and an autocomplete accept injects
+        // host text; either way `floor` no longer indexes a valid snapshot, so
+        // discard the window. There is no cross-submit undo.
+        this.discardUndoWindow();
+        // Enter submits and opens a fresh prompt, so the next implicit insert
+        // is repeatable again. Tab-completion is a host edit inside the
+        // current session, so it taints the rest of that session — continued
+        // typing must not resurrect a recording.
+        this.implicitInsertSuppressed = !this.isSubmitEnterInput(key);
+        return;
+      }
+      // Implicit insert (startup / post-submit): the editor is already in
+      // insert mode with no recording open, so a vim `i`/`a`/… entry never
+      // ran to seed one. Synthesize an `i` entry on the first real keystroke
+      // so the typed run becomes dot-repeatable, exactly as if the user had
+      // pressed `i` in normal mode. Escape finalizes it as the last change;
+      // Enter and Tab-completion stay excluded via the cancel check above, so
+      // a later replay can never submit. A session tainted by a mid-insert
+      // host edit stays suppressed until Escape leaves insert mode.
+      if (
+        !this.repeatRecording &&
+        !this.implicitInsertSuppressed &&
+        !isEscapeLikeInput(key)
+      ) {
+        this.beginImplicitInsertRecording();
+      }
+      if (this.repeatRecording?.captureInsert) {
+        this.repeatRecording.keys.push(key);
+        this.repeatRecording.countOverrideKeys.push(key);
+      }
+      return;
+    }
+
+    if (this.repeatRecording && !this.isRepeatRecordingInProgress()) {
+      this.cancelRepeatableCommand();
+    }
+
+    if (this.repeatRecording) {
+      this.repeatRecording.keys.push(key);
+      if (!this.shouldStripKeyFromCountOverride(key)) {
+        this.repeatRecording.countOverrideKeys.push(key);
+      }
+      return;
+    }
+
+    if (this.isRepeatRecordingInProgress()) return;
+    if (!this.isRepeatableCommandStart(key)) return;
+
+    this.repeatRecording = {
+      keys: [...this.prefixCount, key],
+      countOverrideKeys: [key],
+      startChangeVersion: this.bufferChangeVersion,
+      captureInsert: false,
+      forceCommit: false,
+    };
+    // A repeatable command starts a vim change; bracket it so every host push
+    // it produces (the delete of `cw`, the per-character pushes of `p`)
+    // collapses to one unit. This runs before the command body, so `floor`
+    // precedes the mutation.
+    this.openUndoWindow();
+  }
+
+  /**
+   * Open a recording for an implicit insert session as if `i` had been pressed.
+   * `captureInsert` starts true so the triggering keystroke and everything up
+   * to Escape is captured; replaying the stored `["i", …, Esc]` re-enters
+   * insert mode and re-types the run without ever submitting.
+   */
+  private beginImplicitInsertRecording(): void {
+    this.repeatRecording = {
+      keys: ['i'],
+      countOverrideKeys: ['i'],
+      startChangeVersion: this.bufferChangeVersion,
+      captureInsert: true,
+      forceCommit: false,
+    };
+    this.openUndoWindow();
+  }
+
+  private clearRepeatState(): void {
+    if (this.replayingRepeat) return;
+    this.repeatRecording = null;
+    this.lastRepeatableCommand = null;
+  }
+
+  private cancelRepeatableCommand(): void {
+    if (this.replayingRepeat) {
+      this.repeatReplayFailed = true;
+      return;
+    }
+    this.repeatRecording = null;
+  }
+
+  private forceCommitRepeatRecording(): void {
+    if (this.replayingRepeat || !this.repeatRecording) return;
+    this.repeatRecording.forceCommit = true;
+  }
+
+  /**
+   * Commit only after the watched command has completed and changed the buffer.
+   * This naturally ignores motions, yanks, failed edits, and aborted pending
+   * commands while keeping insert-mode changes open until Escape returns to
+   * normal mode.
+   */
+  private finishRepeatRecordingAfterInput(): void {
+    if (this.replayingRepeat) return;
+
+    const recording = this.repeatRecording;
+    if (!recording) return;
+
+    if (this.mode === 'insert') {
+      recording.captureInsert = true;
+      return;
+    }
+
+    if (this.isRepeatRecordingInProgress()) return;
+
+    this.repeatRecording = null;
+    if (recording.keys.length === 0) return;
+
+    if (
+      recording.forceCommit ||
+      this.bufferChangeVersion !== recording.startChangeVersion
+    ) {
+      this.lastRepeatableCommand = {
+        keys: [...recording.keys],
+        countOverrideKeys: [...recording.countOverrideKeys],
+      };
+    }
+  }
+
+  /**
+   * Open a window for the starting change, unless one is already open (a
+   * multi-key change reuses its first key's window) or a replay is in flight
+   * (the outer replay window owns the span). `floor` is captured before this
+   * turn's mutation, so `undoStack[floor]` becomes the change's first (pre-
+   * change) host push. Resetting `lastAction` forces a pure insert's first
+   * character to push that anchor despite leftover fish-style coalescing.
+   */
+  private openUndoWindow(): void {
+    if (this.replayingRepeat) return;
+    if (this.undoWindow !== null) return;
+    const editor = this as unknown as ModalEditorInternals;
+    const stack = editor.undoStack?.stack;
+    if (!stack) return;
+    this.undoWindow = {
+      floor: stack.length,
+      openVersion: this.bufferChangeVersion,
+    };
+    editor.lastAction = null;
+  }
+
+  /**
+   * Close the window at a change boundary. If the buffer mutated, collapse to
+   * `floor + 1` (keep only the pre-change snapshot); a no-op change trims any
+   * stray anchor back to `floor`, leaving prior history untouched.
+   */
+  private closeUndoWindow(): void {
+    const window = this.undoWindow;
+    this.undoWindow = null;
+    if (!window) return;
+    if (this.bufferChangeVersion === window.openVersion) {
+      this.collapseUndoStackTo(window.floor);
+      return;
+    }
+    this.collapseUndoStackTo(window.floor + 1);
+  }
+
+  /** Drop the open window without collapsing (undo/redo/reset/dispatch/submit). */
+  private discardUndoWindow(): void {
+    this.undoWindow = null;
+  }
+
+  /**
+   * Trim the host undo stack to `target` entries. A direct length trim (no
+   * `setText`/`onChange`) so `centralInvalidationCheck` is not tripped.
+   */
+  private collapseUndoStackTo(target: number): void {
+    const stack = (this as unknown as ModalEditorInternals).undoStack?.stack;
+    if (!stack) return;
+    if (stack.length > target) stack.length = target;
+  }
+
+  /**
+   * Settle the window in the input `finally`, mirroring the recorder: hold
+   * while in insert mode or while an operator/motion/text-object is pending;
+   * otherwise close. Suppressed during a replay (the outer window collapses).
+   */
+  private settleUndoWindowAfterInput(): void {
+    if (this.replayingRepeat) return;
+    if (this.undoWindow === null) return;
+    if (this.mode === 'insert') return;
+    if (this.isRepeatRecordingInProgress()) return;
+    this.closeUndoWindow();
+  }
+
+  private isTextInsertRepeatCommand(command: RepeatableCommand): boolean {
+    return TEXT_INSERT_REPEAT_KEYS.has(command.countOverrideKeys[0] ?? '');
+  }
+
+  private isOpenLineRepeatCommand(command: RepeatableCommand): boolean {
+    return OPEN_LINE_REPEAT_KEYS.has(command.countOverrideKeys[0] ?? '');
+  }
+
+  private getOpenLineRepeatReplayKeys(
+    command: RepeatableCommand,
+    overrideCount: number,
+  ): string[] {
+    if (command.countOverrideKeys[0] !== 'O' || overrideCount <= 1) {
+      return Array.from(
+        { length: overrideCount },
+        () => command.countOverrideKeys,
+      ).flat();
+    }
+
+    return Array.from({ length: overrideCount }, (_, index) =>
+      index === 0 ? command.countOverrideKeys : ['j', ...command.countOverrideKeys],
+    ).flat();
+  }
+
+  private getRepeatReplayKeys(
+    command: RepeatableCommand,
+    hasOverrideCount: boolean,
+    overrideCount: number,
+  ): string[] {
+    if (!hasOverrideCount) return command.keys;
+
+    if (this.isOpenLineRepeatCommand(command)) {
+      return this.getOpenLineRepeatReplayKeys(command, overrideCount);
+    }
+
+    if (this.isTextInsertRepeatCommand(command)) {
+      const [startKey, ...continuation] = command.countOverrideKeys;
+      const finalKey = continuation[continuation.length - 1];
+      const hasFinalEscape = finalKey !== undefined && isEscapeLikeInput(finalKey);
+      const insertKeys = hasFinalEscape ? continuation.slice(0, -1) : continuation;
+      return [
+        startKey,
+        ...Array.from({ length: overrideCount }, () => insertKeys).flat(),
+        ...(hasFinalEscape ? [finalKey] : []),
+      ];
+    }
+
+    return [...String(overrideCount), ...command.countOverrideKeys];
+  }
+
+  /**
+   * Replay the last committed change. Plain `.` replays the original command,
+   * including its count. A count before `.` replaces the original command count.
+   * Replay runs with recording disabled so `.` itself never changes what is
+   * stored as the last repeatable command.
+   */
+  private repeatLastCommand(): void {
+    const command = this.lastRepeatableCommand;
+    const hasOverrideCount = this.hasPendingCount();
+    const overrideCount = this.takeTotalCount(1);
+    if (!command || command.keys.length === 0) return;
+
+    const replayKeys = this.getRepeatReplayKeys(
+      command,
+      hasOverrideCount,
+      overrideCount,
+    );
+    const beforeReplay = this.captureSnapshot();
+    const beforeRegister = this.unnamedRegister;
+
+    this.repeatRecording = null;
+    this.repeatReplayFailed = false;
+    // A `.` replay is one undo unit, separate from the change it repeats. Wrap
+    // it in one outer window opened before `replayingRepeat` goes high;
+    // per-keystroke windows are suppressed during replay, so only this one
+    // collapses.
+    this.openUndoWindow();
+    this.replayingRepeat = true;
+    try {
+      for (const key of replayKeys) {
+        this.handleInput(key);
+        if (this.repeatReplayFailed) break;
+      }
+    } finally {
+      this.replayingRepeat = false;
+    }
+
+    if (this.repeatReplayFailed) {
+      this.clearPendingState();
+      this.withTransition('restore', () => {
+        this.restoreSnapshot(beforeReplay);
+      });
+      this.unnamedRegister = beforeRegister;
+      this.repeatReplayFailed = false;
+      this.discardUndoWindow();
+      return;
+    }
+
+    this.closeUndoWindow();
+
+    if (hasOverrideCount) {
+      this.lastRepeatableCommand = {
+        keys: [...replayKeys],
+        countOverrideKeys: [...command.countOverrideKeys],
+      };
+    }
+  }
+
+  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');
+    }
+
+    if (typeof editor.pushUndoSnapshot !== 'function') {
+      throw new Error('Synthetic edit prerequisite: pushUndoSnapshot unavailable');
+    }
+
+    const textBefore = this.getText();
+    const preCursorLine = editor.state.cursorLine;
+    const preCursorCol = editor.state.cursorCol;
+
+    mutation();
+
+    if (this.getText() === textBefore) return;
+
+    const postLines = editor.state.lines.slice();
+    const postCursorLine = editor.state.cursorLine;
+    const postCursorCol = editor.state.cursorCol;
+    const postPreferredCol = editor.preferredVisualCol;
+
+    const preLines = textBefore.split('\n');
+    editor.state.lines = preLines.length > 0 ? preLines : [''];
+    editor.state.cursorLine = preCursorLine;
+    editor.state.cursorCol = preCursorCol;
+    editor.pushUndoSnapshot();
+
+    editor.state.lines = postLines;
+    editor.state.cursorLine = postCursorLine;
+    editor.state.cursorCol = postCursorCol;
+    editor.preferredVisualCol = postPreferredCol;
+
+    editor.onChange?.(this.getText());
+    editor.tui?.requestRender?.();
+  }
+
+  private startPendingExCommand(): void {
+    this.pendingExCommand = ':';
+    this.endBracketedPasteInExCommand();
+  }
+
+  private clearPendingExCommand(): void {
+    const shouldDiscardBracketedPasteTail =
+      this.acceptingBracketedPasteInExCommand ||
+      this.pendingEscWhileAcceptingBracketedPasteInExCommand;
+
+    this.pendingExCommand = null;
+    this.endBracketedPasteInExCommand();
+
+    if (shouldDiscardBracketedPasteTail) {
+      this.discardingBracketedPasteInNormalMode = true;
+      this.pendingEscWhileDiscardingBracketedPasteInNormalMode = false;
+    }
+  }
+
+  private clearPendingState(): void {
+    this.pendingMotion = null;
+    this.pendingTextObject = null;
+    this.pendingOperator = null;
+    this.prefixCount = '';
+    this.operatorCount = '';
+    this.pendingG = false;
+    this.pendingGCount = '';
+    this.pendingReplace = false;
+    this.clearPendingExCommand();
+    this.cancelNativePasteExpectation();
+  }
+
+  private endBracketedPasteInExCommand(): void {
+    this.acceptingBracketedPasteInExCommand = false;
+    this.pendingEscWhileAcceptingBracketedPasteInExCommand = false;
+    this.discardingPasteAfterNewlineInExCommand = false;
+  }
+
+  private cancelNativePasteExpectation(): void {
+    this.expectingNativePaste = null;
+    this.nativePasteStarted = false;
+  }
+
+  /**
+   * Accept the bracketed-paste payload delivered by Pi's native clipboard
+   * paste (`app.clipboard.pasteImage`, triggered through a synthesized
+   * ctrl+v). Chunks are forwarded verbatim to the built-in editor so paste
+   * insertion and large-content collapse behave exactly as in insert mode;
+   * only the start/end markers are tracked so the pending p/P follow-up
+   * fires once the payload has fully landed. Returns null when the chunk
+   * was consumed, or the chunk itself when no paste arrived, canceling the
+   * expectation and letting normal-mode handling continue.
+   */
+  private acceptNativePasteChunk(data: string): string | null {
+    if (!this.nativePasteStarted) {
+      if (!data.includes(BRACKETED_PASTE_START)) return data;
+      this.nativePasteStarted = true;
+    }
+
+    super.handleInput(data);
+
+    if (data.includes(BRACKETED_PASTE_END)) {
+      const action = this.expectingNativePaste;
+      this.cancelNativePasteExpectation();
+      if (action !== null) this.finishNativePaste(action);
+    }
+    return null;
+  }
+
+  private finishNativePaste(action: 'editor' | 'send'): void {
+    if (action === 'send') {
+      // An empty clipboard delivers nothing through insertTextAtCursor, so an
+      // empty prompt is never submitted; an image pastes as a file path.
+      if (this.getText() !== '') super.handleInput('\r');
+      return;
+    }
+    // The paste lands from an async clipboard continuation with no
+    // handleInput on the stack, so the deferred-open flush would never run;
+    // open directly. Guarded against double-open and a missing editor fn.
+    this.openExternalEditor();
+  }
+
+  private retainDiscardedExPasteTailState(tail: string): void {
+    const lastStart = tail.lastIndexOf(BRACKETED_PASTE_START);
+    const lastEnd = tail.lastIndexOf(BRACKETED_PASTE_END);
+    let endsWithStartPrefix = false;
+    for (let length = 1; length < BRACKETED_PASTE_START.length; length++) {
+      if (tail.endsWith(BRACKETED_PASTE_START.slice(0, length))) {
+        endsWithStartPrefix = true;
+        break;
+      }
+    }
+    if (lastStart <= lastEnd && !endsWithStartPrefix) return;
+
+    this.acceptingBracketedPasteInExCommand = true;
+    this.pendingEscWhileAcceptingBracketedPasteInExCommand = false;
+    this.discardingPasteAfterNewlineInExCommand = true;
+  }
+
+  /**
+   * First-line-wait: a pasted newline never submits. The payload up to the
+   * first newline becomes the pending command; the rest of that paste is
+   * dropped. Only a typed Enter reaches `submitPendingExCommand`.
+   */
+  private takePastedExCommandText(payload: string): string {
+    if (this.discardingPasteAfterNewlineInExCommand) return '';
+
+    const newline = payload.search(/[\r\n]/);
+    if (newline === -1) return payload;
+
+    this.discardingPasteAfterNewlineInExCommand = true;
+    return payload.slice(0, newline);
+  }
+
+  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)) {
+            const tail = chunk.slice(BRACKETED_PASTE_END_TAIL.length);
+            this.endBracketedPasteInExCommand();
+            this.retainDiscardedExPasteTailState(tail);
+            return null;
+          }
+
+          normalized += this.takePastedExCommandText('\x1b');
+          this.pendingEscWhileAcceptingBracketedPasteInExCommand = false;
+        }
+
+        const end = chunk.indexOf(BRACKETED_PASTE_END);
+        if (end !== -1) {
+          normalized += this.takePastedExCommandText(chunk.slice(0, end));
+          const tail = chunk.slice(end + BRACKETED_PASTE_END.length);
+          this.endBracketedPasteInExCommand();
+          this.retainDiscardedExPasteTailState(tail);
+          return normalized.length > 0 ? normalized : null;
+        }
+
+        if (isEscapeLikeInput(chunk)) {
+          this.pendingEscWhileAcceptingBracketedPasteInExCommand = true;
+          return normalized.length > 0 ? normalized : null;
+        }
+
+        normalized += this.takePastedExCommandText(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;
+
+    while (true) {
+      if (this.discardingBracketedPasteInNormalMode) {
+        stripped = true;
+        const end = chunk.indexOf(BRACKETED_PASTE_END);
+        if (end === -1) {
+          return { filtered: null, stripped };
+        }
+        this.discardingBracketedPasteInNormalMode = false;
+        this.pendingEscWhileDiscardingBracketedPasteInNormalMode = false;
+        chunk = chunk.slice(end + BRACKETED_PASTE_END.length);
+        if (!chunk) return { filtered: null, stripped };
+      }
+
+      const start = chunk.indexOf(BRACKETED_PASTE_START);
+      if (start === -1) {
+        return { filtered: chunk, stripped };
+      }
+
+      stripped = true;
+      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);
+      if (!chunk) return { filtered: null, stripped };
+    }
+  }
+
+  handleInput(data: string): void {
+    try {
+      this.handleInputCore(data);
+    } finally {
+      this.refreshPendingDispatchRestore();
+      this.flushPendingExternalEditorOpen();
+    }
+  }
+
+  private handleInputCore(data: string): void {
+    if (
+      this.externalEditorFn &&
+      this.appKeybindings.matches(data, 'app.editor.external')
+    ) {
+      this.openExternalEditor();
+      return;
+    }
+
+    this.ensureOnChangeHook();
+
+    if (this.pendingExCommand !== null) {
+      const normalized = this.normalizePendingExCommandInput(data);
+      if (normalized === null) return;
+      data = normalized;
+    } else if (this.mode !== 'insert') {
+      if (this.expectingNativePaste !== null) {
+        const remaining = this.acceptNativePasteChunk(data);
+        if (remaining === null) return;
+        data = remaining;
+        this.cancelNativePasteExpectation();
+      }
+
+      if (this.discardingBracketedPasteInNormalMode) {
+        if (isEscapeLikeInput(data)) {
+          if (this.pendingEscWhileDiscardingBracketedPasteInNormalMode) {
+            this.pendingEscWhileDiscardingBracketedPasteInNormalMode = false;
+            this.discardingBracketedPasteInNormalMode = false;
+            this.clearPendingState();
+            this.cancelRepeatableCommand();
+            return;
+          } else {
+            this.pendingEscWhileDiscardingBracketedPasteInNormalMode = true;
+            this.clearPendingState();
+            this.cancelRepeatableCommand();
+            return;
+          }
+        } else if (this.pendingEscWhileDiscardingBracketedPasteInNormalMode) {
+          if (data.startsWith(BRACKETED_PASTE_END_TAIL)) {
+            this.pendingEscWhileDiscardingBracketedPasteInNormalMode = false;
+            this.discardingBracketedPasteInNormalMode = false;
+            data = data.slice(BRACKETED_PASTE_END_TAIL.length);
+            if (data.length === 0) {
+              this.clearPendingState();
+              this.cancelRepeatableCommand();
+              return;
+            }
+          } else {
+            this.pendingEscWhileDiscardingBracketedPasteInNormalMode = false;
+          }
+        }
+      }
+
+      const { filtered, stripped } = this.stripBracketedPasteInNormalMode(data);
+      if (stripped) {
+        this.clearPendingState();
+        this.cancelRepeatableCommand();
+      }
+      if (filtered === null) return;
+      data = filtered;
+    }
+
+    this.prepareRepeatRecordingForInput(data);
+    try {
+      if (isEscapeLikeInput(data)) {
+        this.handleEscape();
+        return;
+      }
+
+      if ('insert' === this.mode) {
+        if (matchesKey(data, Key.shiftAlt('a')) || data === '\x1bA') {
+          super.handleInput(CTRL_E);
+          return;
+        }
+        if (matchesKey(data, Key.shiftAlt('i')) || data === '\x1bI') {
+          super.handleInput(CTRL_A);
+          return;
+        }
+        if (matchesKey(data, Key.alt('o')) || data === '\x1bo') {
+          this.openLineBelow();
+          return;
+        }
+        if (matchesKey(data, Key.shiftAlt('o')) || data === '\x1bO') {
+          this.openLineAbove();
+          return;
+        }
+        super.handleInput(data);
+        return;
+      }
+
+      if (this.pendingReplace) {
+        this.pendingReplace = false;
+        if (!isPrintableInput(data)) {
+          this.prefixCount = '';
+          this.operatorCount = '';
+          this.cancelRepeatableCommand();
+          return;
+        }
+
+        const count = this.takeTotalCount(1);
+        const cursor = this.getCursor();
+        const line = this.getLines()[cursor.line] ?? '';
+        const range = this.getGraphemeRangeAtCol(line, cursor.col, count);
+        if (!range) {
+          this.cancelRepeatableCommand();
+          return;
+        }
+
+        const before = line.slice(0, range.start);
+        const after = line.slice(range.end);
+        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);
+        this.forceCommitRepeatRecording();
+        this.replaceTextInBuffer(newText, newCursorAbs);
+        return;
+      }
+
+      if (this.pendingExCommand !== null) {
+        this.handlePendingExCommand(data);
+        return;
+      }
+
+      if (this.pendingTextObject) {
+        this.handlePendingTextObject(data);
+        return;
+      }
+
+      if (this.pendingMotion) {
+        this.handlePendingMotion(data);
+        return;
+      }
+
+      if (this.pendingOperator === 'd') {
+        this.handlePendingDelete(data);
+        return;
+      }
+
+      if (this.pendingOperator === 'c') {
+        this.handlePendingChange(data);
+        return;
+      }
+
+      if (this.pendingOperator === 'y') {
+        this.handlePendingYank(data);
+        return;
+      }
+
+      if (isVisualMode(this.mode) && this.handleVisualMode(data)) return;
+
+      this.handleNormalMode(data);
+    } finally {
+      this.finishRepeatRecordingAfterInput();
+      this.settleUndoWindowAfterInput();
+    }
+  }
+
+  private clearUnderlyingPasteStateIfActive(): void {
+    const editor = this as unknown as {
+      isInPaste?: boolean;
+      pasteBuffer?: string;
+      pasteCounter?: number;
+    };
+
+    if (!editor.isInPaste) return;
+
+    editor.isInPaste = false;
+    if (typeof editor.pasteBuffer === 'string') {
+      editor.pasteBuffer = '';
+    }
+    if (typeof editor.pasteCounter === 'number') {
+      editor.pasteCounter = 0;
+    }
+  }
+
+  private handleEscape(): void {
+    if (this.pendingExCommand !== null) {
+      this.clearPendingExCommand();
+      return;
+    }
+
+    if (
+      this.pendingMotion ||
+      this.pendingTextObject ||
+      this.pendingOperator ||
+      this.prefixCount ||
+      this.operatorCount ||
+      this.pendingG ||
+      this.pendingGCount ||
+      this.pendingReplace
+    ) {
+      this.clearPendingState();
+      this.cancelRepeatableCommand();
+      return;
+    }
+    if (isVisualMode(this.mode)) {
+      this.exitVisualMode();
+      return;
+    }
+    if ('insert' === this.mode) {
+      this.clearUnderlyingPasteStateIfActive();
+      this.setMode('normal');
+      if (this.getCursor().col > 0) this.moveCursorBy(-1);
+    } else {
+      super.handleInput('\x1b'); // pass escape to abort agent
+    }
+  }
+
+  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 (isEnterLikeInput(data)) {
+      this.submitPendingExCommand();
+      return;
+    }
+
+    if (isBackspaceLikeInput(data)) {
+      this.deleteLastPendingExCommandGrapheme();
+      return;
+    }
+
+    if (this.handlePendingExCommandControlChunk(data)) {
+      return;
+    }
+
+    if (!isPrintableChunk(data)) {
+      this.clearPendingExCommand();
+      this.handleInput(data);
+      return;
+    }
+
+    this.pendingExCommand += data;
+  }
+
+  private hasNonEmptyPrompt(): boolean {
+    return this.getText().trim().length > 0;
+  }
+
+  private static readonly EX_QUIT_NAMES = new Set([
+    'q',
+    'qa',
+    'quit',
+    'qall',
+    'quitall',
+  ]);
+
+  // Names pi-vim claims for real vim ex semantics later. They are never
+  // dispatched to Pi, so a `/s` or `/w` extension installed today cannot
+  // shadow a future `:s` substitute or `:w` write.
+  private static readonly EX_RESERVED_NAMES = new Set([
+    's',
+    'g',
+    'v',
+    'd',
+    'm',
+    't',
+    'co',
+    'j',
+    'w',
+    'r',
+    'normal',
+    'sort',
+    '&',
+    '>',
+    '<',
+  ]);
+
+  private submitPendingExCommand(): void {
+    const command = this.pendingExCommand?.slice(1).trim() ?? '';
+    this.clearPendingExCommand();
+    if (!command) return;
+
+    const force = command.endsWith('!');
+    const quitName = force ? command.slice(0, -1) : command;
+
+    if (ModalEditor.EX_QUIT_NAMES.has(quitName)) {
+      if (!force && this.hasNonEmptyPrompt()) {
+        this.notifyFn(`Prompt is not empty; use :${command}! to quit anyway`);
+        return;
+      }
+
+      this.quitFn();
+      return;
+    }
+
+    // `:!cmd` submits `!cmd` through the same seam the slash bridge uses, so it
+    // reaches Pi's bash mode: `onSubmit` runs a leading `!` as a shell command
+    // (`!!` excludes it from context). The quit check above already claimed the
+    // `:q!` family, so only a bare leading `!` lands here. `:!` with no command
+    // is unsupported, and piDispatch gates it like every other bridge dispatch.
+    if (command.startsWith('!')) {
+      const shellCommand = command.replace(/^!+/, '').trim();
+      if (shellCommand && this.exCommandSettings.piDispatch) {
+        this.dispatchThroughSubmit(command);
+      } else {
+        this.notifyFn(`Unsupported ex command: :${command}`);
+      }
+      return;
+    }
+
+    const separator = command.search(/\s/);
+    const name = separator === -1 ? command : command.slice(0, separator);
+    const args = separator === -1 ? '' : command.slice(separator + 1).trim();
+    const bareName = name.endsWith('!') ? name.slice(0, -1) : name;
+
+    if (ModalEditor.EX_RESERVED_NAMES.has(bareName)) {
+      this.notifyFn(`Reserved ex command: :${name}`);
+      return;
+    }
+
+    if (this.exCommandSettings.piDispatch && this.commandNamesFn().has(name)) {
+      this.dispatchSlashCommand(name, args);
+      return;
+    }
+
+    this.notifyFn(`Unsupported ex command: :${command}`);
+  }
+
+  private captureDispatchState(): DispatchState {
+    const snapshot = this.captureSnapshot();
+    const savedRedo = [...this.redoStack];
+    const savedRepeat = this.lastRepeatableCommand;
+    const undoStack = (this as unknown as ModalEditorInternals).undoStack;
+    const savedUndoDepth = undoStack?.length ?? 0;
+
+    return {
+      snapshot,
+      restore: () => {
+        this.restoreSnapshot(snapshot);
+        while (undoStack && undoStack.length > savedUndoDepth) undoStack.pop();
+        this.redoStack.length = 0;
+        this.redoStack.push(...savedRedo);
+        this.lastRepeatableCommand = savedRepeat;
+      },
+    };
+  }
+
+  private dispatchSlashCommand(name: string, args: string): void {
+    this.dispatchThroughSubmit(args ? `/${name} ${args}` : `/${name}`);
+  }
+
+  /**
+   * Run a command line (`/name args` or `!cmd`) through the editor's own submit
+   * path, then put the composed prompt back. Reapply the latest prompt state
+   * when an asynchronous submit settles too, because some builtin routes clear
+   * the prompt only after awaiting work. No command reads that buffer as an
+   * argument, so restoring the composed state is always semantically correct.
+   *
+   * The dispatch is a side effect the user never typed, so it must leave no
+   * trace: besides the text and cursor, the undo depth, the redo stack and the
+   * repeatable command all go back to what they were. Without that, the
+   * dispatch's own `setText("")` would sit on the undo stack and swallow the
+   * next `u`.
+   */
+  private dispatchThroughSubmit(commandLine: string): void {
+    // A dispatch is not a user change: discard any window so no collapse runs
+    // mid-dispatch and no floor is stranded. The bridge's `savedUndoDepth`
+    // restore then erases the phantom `setText("")` checkpoint.
+    this.discardUndoWindow();
+    const dispatchState = this.captureDispatchState();
+
+    if (this.exCommandSettings.copyInputToClipboard && dispatchState.snapshot.text) {
+      this.clipboardMirror.mirror(dispatchState.snapshot.text);
+    }
+
+    let result: CommandDispatchResult;
+    try {
+      result = this.runCommandFn(commandLine);
+    } finally {
+      dispatchState.restore();
+    }
+
+    if (!result || typeof result.then !== 'function') return;
+
+    this.pendingAsyncDispatches++;
+    this.restoreLatestDispatchStateFn = dispatchState.restore;
+    const settleDispatch = (): void => {
+      try {
+        if (this.getText() === '') this.restoreLatestDispatchStateFn?.();
+      } finally {
+        this.pendingAsyncDispatches--;
+        if (this.pendingAsyncDispatches === 0) {
+          this.restoreLatestDispatchStateFn = null;
+        }
+      }
+    };
+    void Promise.resolve(result).then(settleDispatch, settleDispatch);
+  }
+
+  private takeTotalCount(defaultValue: number = 1): number {
+    const prefixRaw = this.prefixCount;
+    const operatorRaw = this.operatorCount;
+    this.prefixCount = '';
+    this.operatorCount = '';
+
+    if (!prefixRaw && !operatorRaw) return defaultValue;
+
+    const parse = (raw: string): number | null => {
+      if (!raw) return null;
+      const parsed = Number.parseInt(raw, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) return null;
+      return parsed;
+    };
+
+    const prefix = parse(prefixRaw);
+    const operator = parse(operatorRaw);
+
+    if (prefix === null && operator === null) return 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);
+  }
+
+  private hasPendingCount(): boolean {
+    return this.prefixCount.length > 0 || this.operatorCount.length > 0;
+  }
+
+  private opDigit(data: string): boolean {
+    if (!this.isOperatorCountDigit(data)) return false;
+    this.operatorCount += data;
+    return true;
+  }
+
+  private cancelPendingOperator(data: string): void {
+    this.pendingOperator = null;
+    this.prefixCount = '';
+    this.operatorCount = '';
+    this.cancelRepeatableCommand();
+    if (!isPrintableChunk(data)) {
+      super.handleInput(data);
+    }
+  }
+
+  private handlePendingMotion(data: string): void {
+    if (!isPrintableInput(data)) {
+      this.pendingMotion = null;
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    const pendingMotion = this.pendingMotion;
+    if (!pendingMotion) return;
+
+    if (this.pendingOperator === 'd') {
+      if (!this.deleteWithCharMotion(pendingMotion, data)) {
+        this.cancelRepeatableCommand();
+      }
+      this.pendingOperator = null;
+    } else if (this.pendingOperator === 'c') {
+      const changed = this.deleteWithCharMotion(pendingMotion, data);
+      this.pendingOperator = null;
+      if (changed) {
+        this.setMode();
+      } else {
+        this.cancelRepeatableCommand();
+      }
+    } else if (this.pendingOperator === 'y') {
+      this.yankWithCharMotion(pendingMotion, data);
+      this.pendingOperator = null;
+    } else {
+      this.executeCharMotion(pendingMotion, data);
+    }
+
+    this.pendingMotion = null;
+  }
+
+  private handlePendingTextObject(data: string): void {
+    const pendingTextObject = this.pendingTextObject;
+    this.pendingTextObject = null;
+    if (!pendingTextObject) {
+      this.pendingOperator = null;
+      this.cancelRepeatableCommand();
+      return;
+    }
+
+    const hasCount = this.hasPendingCount();
+
+    if (this.pendingOperator === 'y' && hasCount) {
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    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) {
+        // A word text object that cannot be satisfied (e.g. `2diw` on a lone
+        // word, `daw` on trailing whitespace) leaves the buffer and register
+        // untouched in nvim, but still drops the cursor on the last char of the
+        // line where the object motion ran out. Match that cursor move so the
+        // no-op stays in parity.
+        if (range === null && this.pendingOperator !== null) {
+          this.moveCursorToLastGraphemeOnLine();
+        }
+        this.pendingOperator = null;
+        this.cancelRepeatableCommand();
+        return;
+      }
+
+      this.applyResolvedTextObjectRange(range);
+      return;
+    }
+
+    if (hasCount) {
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    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) {
+      this.cancelRepeatableCommand();
+      return;
+    }
+
+    if (range.endAbs === range.startAbs) {
+      if (pendingOperator === 'c') {
+        this.moveCursorToAbsoluteIndex(range.startAbs);
+        this.setMode();
+      } else {
+        this.cancelRepeatableCommand();
+      }
+      return;
+    }
+
+    if (pendingOperator === 'd') {
+      this.deleteRangeByAbsolute(range.startAbs, range.endAbs);
+      this.clampCursorAfterTextObjectDeletion();
+      return;
+    }
+
+    if (pendingOperator === 'c') {
+      this.deleteRangeByAbsolute(range.startAbs, range.endAbs);
+      this.setMode();
+      return;
+    }
+
+    if (pendingOperator === 'y') {
+      this.yankRangeByAbsolute(range.startAbs, range.endAbs);
+    }
+  }
+
+  // After a normal-mode text-object delete whose range ended at EOL, the cursor
+  // is left at the deletion start, which now equals the line length — one past
+  // the last grapheme. nvim clamps back onto the last grapheme; without this a
+  // following `x` no-ops on the phantom column. Mirrors cutCharUnderCursor's
+  // `col >= line.length` clamp, but grapheme-aware.
+  private clampCursorAfterTextObjectDeletion(): void {
+    const { line, col } = this.getCurrentLineAndCol();
+    if (line.length > 0 && col >= line.length) {
+      this.moveCursorToPreviousGraphemeStart();
+    }
+  }
+
+  private handlePendingDelete(data: string): void {
+    if (this.opDigit(data)) return;
+
+    if (data === '%') {
+      this.applyPercentOp();
+      return;
+    }
+
+    if (data === 'd') {
+      const count = this.takeTotalCount(1);
+      this.deleteLinewiseByDelta(count - 1);
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (data === 'j' || data === 'k') {
+      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);
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (data === 'G') {
+      if (this.prefixCount.length > 0 || this.operatorCount.length > 0) {
+        this.cancelPendingOperator(data);
+        return;
+      }
+
+      this.deleteToBufferEndLinewise();
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (data === '_') {
+      const count = this.takeTotalCount(1);
+      this.deleteLinewiseByDelta(count - 1);
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (CHAR_MOTION_KEYS.has(data)) {
+      this.pendingMotion = data as PendingMotion;
+      return;
+    }
+
+    const hasCount = this.hasPendingCount();
+    const supportsCountedWordMotion =
+      data === 'w' ||
+      data === 'e' ||
+      data === 'b' ||
+      data === 'W' ||
+      data === 'E' ||
+      data === 'B';
+    const supportsCountedTextObject = data === 'i' || data === 'a';
+    const supportsCountedLineEnd = data === '$';
+    const supportsIgnoredCountMotion = data === '0' || data === '^';
+
+    if (
+      hasCount &&
+      !supportsCountedWordMotion &&
+      !supportsCountedTextObject &&
+      !supportsCountedLineEnd &&
+      !supportsIgnoredCountMotion
+    ) {
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    if (supportsCountedTextObject) {
+      this.pendingTextObject = data;
+      return;
+    }
+
+    if (supportsCountedLineEnd) {
+      const count = this.takeTotalCount(1);
+      if (this.applyLineEndOperator(count, 'delete')) {
+        this.pendingOperator = null;
+        return;
+      }
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    const motionCount = supportsCountedWordMotion ? this.takeTotalCount(1) : 1;
+    if (supportsIgnoredCountMotion) this.takeTotalCount(1);
+    if (this.deleteWithMotion(data, motionCount)) {
+      this.pendingOperator = null;
+      return;
+    }
+
+    this.cancelPendingOperator(data);
+  }
+
+  private handlePendingChange(data: string): void {
+    if (this.opDigit(data)) return;
+
+    if (data === '%') {
+      this.applyPercentOp();
+      return;
+    }
+
+    if (data === 'c') {
+      if (this.prefixCount.length > 0 || this.operatorCount.length > 0) {
+        this.cancelPendingOperator(data);
+        return;
+      }
+
+      this.cutLine();
+      this.pendingOperator = null;
+      this.setMode();
+      return;
+    }
+
+    if (data === '_') {
+      const count = this.takeTotalCount(1);
+      if (count <= 1) {
+        this.cutLine();
+      } else {
+        const currentLine = this.getCursor().line;
+        const lines = this.getLines();
+        const clampedEnd = Math.min(currentLine + count - 1, lines.length - 1);
+        this.writeToRegister(this.getLinewisePayload(currentLine, clampedEnd));
+        const before = lines.slice(0, currentLine);
+        const after = lines.slice(clampedEnd + 1);
+        const newLines = [...before, '', ...after];
+        const newText = newLines.join('\n');
+        const cursorAbs = before.reduce((acc, l) => acc + l.length + 1, 0);
+        this.replaceTextInBuffer(newText, cursorAbs);
+      }
+      this.pendingOperator = null;
+      this.setMode();
+      return;
+    }
+
+    if (CHAR_MOTION_KEYS.has(data)) {
+      this.pendingMotion = data as PendingMotion;
+      return;
+    }
+
+    const hasCount = this.hasPendingCount();
+    const supportsCountedWordMotion =
+      data === 'w' ||
+      data === 'e' ||
+      data === 'b' ||
+      data === 'W' ||
+      data === 'E' ||
+      data === 'B';
+    const supportsCountedTextObject = data === 'i' || data === 'a';
+    const supportsCountedLineEnd = data === '$';
+    const supportsIgnoredCountMotion = data === '0' || data === '^';
+
+    if (
+      hasCount &&
+      !supportsCountedWordMotion &&
+      !supportsCountedTextObject &&
+      !supportsCountedLineEnd &&
+      !supportsIgnoredCountMotion
+    ) {
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    if (supportsCountedTextObject) {
+      this.pendingTextObject = data;
+      return;
+    }
+
+    if (supportsCountedLineEnd) {
+      const count = this.takeTotalCount(1);
+      if (this.applyLineEndOperator(count, 'change')) {
+        this.pendingOperator = null;
+        this.setMode();
+        return;
+      }
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    const motionCount = supportsCountedWordMotion ? this.takeTotalCount(1) : 1;
+    if (supportsIgnoredCountMotion) this.takeTotalCount(1);
+    const effectiveMotion = data === 'W' && this.isCursorOnNonWhitespace() ? 'E' : data;
+    if (this.deleteWithMotion(effectiveMotion, motionCount)) {
+      this.pendingOperator = null;
+      this.setMode();
+      return;
+    }
+
+    this.cancelPendingOperator(data);
+  }
+
+  private enterVisualMode(mode: VisualMode): void {
+    if (!isVisualMode(this.mode)) {
+      const cursor = this.getCursor();
+      this.visualAnchor = { line: cursor.line, col: cursor.col };
+    }
+    this.takeTotalCount(1);
+    this.setMode(mode);
+  }
+
+  private exitVisualMode(): void {
+    this.visualAnchor = null;
+    this.setMode('normal');
+  }
+
+  private getVisualAnchor(): VisualPosition {
+    const cursor = this.getCursor();
+    return clampVisualPosition(this.visualAnchor ?? cursor, this.getLines());
+  }
+
+  /** Absolute `[startAbs, endAbs)` span of the inclusive char-wise selection. */
+  private getVisualCharwiseRange(): { startAbs: number; endAbs: number } {
+    const { start, end } = orderVisualEndpoints(
+      this.getVisualAnchor(),
+      this.getCursor(),
+    );
+    const lines = this.getLines();
+    const endLine = lines[end.line] ?? '';
+    const includesNewline = end.col >= endLine.length && end.line < lines.length - 1;
+    return {
+      startAbs: this.getAbsoluteIndex(start.line, start.col),
+      endAbs:
+        this.getAbsoluteIndex(end.line, 0) +
+        getInclusiveEndColumn(endLine, end.col) +
+        (includesNewline ? 1 : 0),
+    };
+  }
+
+  private clampCursorToLastGrapheme(): void {
+    const { line, col } = this.getCurrentLineAndCol();
+    if (col < line.length) return;
+    const graphemes = getLineGraphemes(line);
+    this.moveCursorToCol(graphemes[graphemes.length - 1]?.start ?? 0);
+  }
+
+  /** Replace the selected lines with one empty line, then open insert there. */
+  private changeVisualLines(startLine: number, endLine: number): void {
+    const lines = this.getLines();
+    this.writeToRegister(this.getLinewisePayload(startLine, endLine));
+
+    const before = lines.slice(0, startLine);
+    const after = lines.slice(endLine + 1);
+    const cursorAbs = before.reduce((abs, line) => abs + line.length + 1, 0);
+    this.replaceTextInBuffer([...before, '', ...after].join('\n'), cursorAbs);
+  }
+
+  private applyVisualOperator(operator: 'd' | 'y' | 'c', linewise: boolean): void {
+    this.takeTotalCount(1);
+    // Mutating visual edits are excluded from dot-repeat and supersede the
+    // older change. A visual yank is not a change, so it preserves that repeat.
+    if (operator !== 'y') {
+      this.clearRepeatState();
+      // Visual `c`/`d` bypass the recorder but still mutate and are single undo
+      // units. Open the window before the delete; the input `finally` closes it
+      // — at once for visual `d`, or on the `<Esc>` ending the visual-`c` insert.
+      this.openUndoWindow();
+    }
+
+    // Both branches resolve the selection before dropping the anchor.
+    const anchor = this.getVisualAnchor();
+    const cursor = this.getCursor();
+
+    if (linewise) {
+      const { startLine, endLine } = getVisualLineRange(anchor, cursor);
+      this.visualAnchor = null;
+      if (operator === 'c') {
+        this.setMode('insert');
+        this.changeVisualLines(startLine, endLine);
+        return;
+      }
+      this.setMode('normal');
+      if (operator === 'd') {
+        this.deleteLineRange(startLine, endLine);
+        return;
+      }
+      this.yankLineRange(startLine, endLine);
+      // Vim only pulls the cursor to the start of the yanked lines when it is
+      // not already sitting on that end of the selection.
+      if (cursor.line >= anchor.line) this.moveCursorToLineStart(startLine);
+      return;
+    }
+
+    const { startAbs, endAbs } = this.getVisualCharwiseRange();
+    this.visualAnchor = null;
+    if (operator === 'c') {
+      this.setMode('insert');
+      this.deleteRangeByAbsolute(startAbs, endAbs);
+      return;
+    }
+    this.setMode('normal');
+    if (operator === 'd') {
+      this.deleteRangeByAbsolute(startAbs, endAbs);
+      this.clampCursorToLastGrapheme();
+      return;
+    }
+    this.yankRangeByAbsolute(startAbs, endAbs);
+    this.moveCursorToAbsoluteIndex(startAbs);
+  }
+
+  /** Swap the anchor and the cursor so the other end of the selection moves. */
+  private swapVisualEnds(): void {
+    const anchor = this.getVisualAnchor();
+    const cursor = this.getCursor();
+    this.visualAnchor = { line: cursor.line, col: cursor.col };
+    this.moveCursorToAbsoluteIndex(this.getAbsoluteIndex(anchor.line, anchor.col));
+  }
+
+  /**
+   * Visual-mode keys that are not motions. Returns true when the key was
+   * consumed; motions and counts fall through to the normal-mode dispatch,
+   * which moves the cursor and thereby resizes the selection.
+   */
+  private handleVisualMode(data: string): boolean {
+    if (this.pendingG || this.pendingMotion) return false;
+
+    const linewise = this.mode === 'visual-line';
+
+    switch (data) {
+      case 'v':
+        if (linewise) this.setMode('visual');
+        else this.exitVisualMode();
+        return true;
+      case 'V':
+        if (linewise) this.exitVisualMode();
+        else this.setMode('visual-line');
+        return true;
+      case 'o':
+      case 'O':
+        this.swapVisualEnds();
+        return true;
+      case 'd':
+      case 'x':
+        this.applyVisualOperator('d', linewise);
+        return true;
+      case 'y':
+        this.applyVisualOperator('y', linewise);
+        return true;
+      case 'c':
+      case 's':
+        this.applyVisualOperator('c', linewise);
+        return true;
+      case 'D':
+      case 'X':
+        this.applyVisualOperator('d', true);
+        return true;
+      case 'Y':
+        this.applyVisualOperator('y', true);
+        return true;
+      case 'C':
+      case 'S':
+        this.applyVisualOperator('c', true);
+        return true;
+      default:
+        if (
+          VISUAL_IGNORED_KEYS.has(data) ||
+          matchesKey(data, 'ctrl+r') ||
+          matchesKey(data, 'ctrl+_')
+        ) {
+          // Swallowed keys are inert in visual mode. Drop any pending count so
+          // it cannot leak into the next motion: `v2pld` must extend by one and
+          // delete one char, not swallow `p` yet still carry the 2 into `l`.
+          this.prefixCount = '';
+          this.operatorCount = '';
+          return true;
+        }
+        return false;
+    }
+  }
+
+  private handleNormalMode(data: string): void {
+    if (this.pendingG) {
+      if (isDigit(data)) {
+        this.pendingGCount += data;
+        return;
+      }
+
+      this.pendingG = false;
+      const hadGCount = this.pendingGCount.length > 0;
+      this.pendingGCount = '';
+
+      if (!hadGCount) {
+        if (data === 'g') {
+          const count = this.takeTotalCount(1);
+          this.moveCursorToLineStart(count - 1);
+          return;
+        }
+
+        if (data === 'J' && !isVisualMode(this.mode)) {
+          this.joinLines(false);
+          return;
+        }
+
+        if (data === 'M') {
+          // :h gM — halfway the text of the line; with a count of 1..100,
+          // to that percentage of the line's text. nvim ignores counts
+          // above 100 (falls back to halfway) and clamps 100gM to the
+          // last character. nvim measures screen cells (linetabsize);
+          // pi-vim measures graphemes — an intentional divergence for
+          // tabs and double-width characters.
+          const count = this.takeTotalCount(0);
+          const { line } = this.getCurrentLineAndCol();
+          const graphemes = getLineGraphemes(line);
+          const target =
+            count >= 1 && count <= 100
+              ? Math.floor((graphemes.length * count) / 100)
+              : Math.floor(graphemes.length / 2);
+          const clamped = Math.min(target, graphemes.length - 1);
+          this.moveCursorToCol(graphemes[clamped]?.start ?? 0);
+          return;
+        }
+      }
+
+      this.clearPendingState();
+      return;
+    }
+
+    if (this.prefixCount.length > 0) {
+      if (isDigit(data)) {
+        this.prefixCount += data;
+        return;
+      }
+
+      if (data === '%') {
+        this.prefixCount = '';
+        this.operatorCount = '';
+        return;
+      }
+
+      if (data === 'd' || data === 'y') {
+        this.pendingOperator = data;
+        return;
+      }
+
+      if (data === 'c') {
+        this.pendingOperator = 'c';
+        return;
+      }
+
+      if (data === 'g') {
+        this.pendingGCount = '';
+        this.pendingG = true;
+        return;
+      }
+
+      if (data === 'G') {
+        const count = this.takeTotalCount(1);
+        this.moveCursorToLineStart(count - 1);
+        return;
+      }
+
+      const supportsCountedStandaloneEdit =
+        data === 'x' ||
+        data === 'X' ||
+        data === 'r' ||
+        data === 's' ||
+        data === 'S' ||
+        data === 'D' ||
+        data === 'C' ||
+        data === 'p' ||
+        data === 'P' ||
+        data === 'Y' ||
+        data === 'J' ||
+        data === '.' ||
+        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 supportsCountedUnderscore = data === '_';
+
+      if (supportsCountedNav) {
+        const count = this.takeTotalCount(1);
+        const clamped = Math.min(count, MAX_COUNT);
+        if ((data === 'h' || data === 'l') && isVisualMode(this.mode)) {
+          const { line, col } = this.getCurrentLineAndCol();
+          const graphemes = getLineGraphemes(line);
+          const currentIndex = graphemes.findIndex(({ end }) => col < end);
+          const graphemeIndex = currentIndex === -1 ? graphemes.length : currentIndex;
+          const availableSteps =
+            data === 'h' ? graphemeIndex : graphemes.length - graphemeIndex;
+          const steps = Math.min(clamped, availableSteps);
+          this.moveCursorBy(data === 'h' ? -steps : steps);
+        } else if (data === 'h') {
+          this.moveCursorBy(-clamped);
+        } else if (data === 'l') {
+          this.moveCursorBy(clamped);
+        } else {
+          const delta = data === 'j' ? clamped : -clamped;
+          this.moveCursorVertically(delta);
+        }
+        return;
+      }
+
+      if (supportsCountedParagraphMotion) {
+        this.executeParagraphMotion(data === '}' ? 'forward' : 'backward');
+        return;
+      }
+
+      if (
+        !supportsCountedStandaloneEdit &&
+        !supportsCountedCharMotion &&
+        !supportsCountedWordMotion &&
+        !supportsCountedParagraphMotion &&
+        !supportsCountedUnderscore
+      ) {
+        this.prefixCount = '';
+        this.operatorCount = '';
+      }
+    } else if (isCountStarter(data)) {
+      this.prefixCount = data;
+      return;
+    }
+
+    if (data === 'J') {
+      this.joinLines(true);
+      return;
+    }
+
+    if (data === 'g') {
+      this.pendingGCount = '';
+      this.pendingG = true;
+      return;
+    }
+
+    if (data === ':') {
+      this.startPendingExCommand();
+      return;
+    }
+
+    if (data === 'G') {
+      this.moveCursorToBufferEnd();
+      return;
+    }
+
+    if (data === 'r') {
+      this.pendingReplace = true;
+      return;
+    }
+
+    if (data === 'v' || data === 'V') {
+      this.enterVisualMode(data === 'v' ? 'visual' : 'visual-line');
+      return;
+    }
+
+    if (data === 'd') {
+      this.pendingOperator = 'd';
+      return;
+    }
+
+    if (data === 'c') {
+      this.pendingOperator = 'c';
+      return;
+    }
+
+    if (data === 'y') {
+      this.pendingOperator = 'y';
+      return;
+    }
+
+    if (data === 'p' || data === 'P') {
+      // Native clipboard paste: counts are consumed and discarded so `3p`
+      // pastes once without leaking the count into later motions.
+      this.takeTotalCount(1);
+      this.expectingNativePaste = data === 'p' ? 'editor' : 'send';
+      this.nativePasteStarted = false;
+      super.handleInput(CTRL_V);
+      return;
+    }
+
+    if (data === 'Y') {
+      const count = this.takeTotalCount(1);
+      this.yankLinewiseByDelta(count - 1);
+      return;
+    }
+
+    if (CHAR_MOTION_KEYS.has(data)) {
+      this.pendingMotion = data as PendingMotion;
+      return;
+    }
+
+    if (data === ';' && this.lastCharMotion) {
+      this.executeCharMotion(
+        this.lastCharMotion.motion,
+        this.lastCharMotion.char,
+        false,
+      );
+      return;
+    }
+    if (data === ',' && this.lastCharMotion) {
+      this.executeCharMotion(
+        reverseCharMotion(this.lastCharMotion.motion),
+        this.lastCharMotion.char,
+        false,
+      );
+      return;
+    }
+
+    if (data === 'u' || data === CTRL_UNDERSCORE || matchesKey(data, 'ctrl+_')) {
+      this.performUndo();
+      return;
+    }
+
+    if (data === CTRL_R || matchesKey(data, 'ctrl+r')) {
+      this.performRedo();
+      return;
+    }
+
+    if (data === '.') {
+      this.repeatLastCommand();
+      return;
+    }
+
+    if (data === '}' || data === '{') {
+      this.executeParagraphMotion(data === '}' ? 'forward' : 'backward');
+      return;
+    }
+
+    if (data === '^') {
+      this.moveCursorToFirstNonWhitespace();
+      return;
+    }
+
+    if (data === '_') {
+      const count = this.takeTotalCount(1);
+      if (count > 1) {
+        this.moveCursorVertically(count - 1);
+      }
+      this.moveCursorToFirstNonWhitespace();
+      return;
+    }
+
+    if (data === 'w') {
+      const count = this.takeTotalCount(1);
+      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 === '%') {
+      this.moveToMatchingPairTarget();
+      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 (Object.hasOwn(NORMAL_KEYS, data)) {
+      this.handleMappedKey(data);
+      return;
+    }
+
+    if (isPrintableChunk(data)) return;
+    super.handleInput(data);
+  }
+
+  private openLineBelow(): void {
+    super.handleInput(CTRL_E);
+    super.handleInput(NEWLINE);
+  }
+
+  private openLineAbove(): void {
+    super.handleInput(CTRL_A);
+    super.handleInput(NEWLINE);
+    super.handleInput(ESC_UP);
+  }
+
+  private handleMappedKey(key: string): void {
+    const seq = NORMAL_KEYS[key];
+    switch (key) {
+      case 'i':
+        this.setMode();
+        break;
+      case 'a':
+        this.setMode();
+        if (!this.isCursorAtOrPastEol()) {
+          super.handleInput(ESC_RIGHT);
+        }
+        break;
+      case 'A':
+        this.setMode();
+        super.handleInput(CTRL_E);
+        break;
+      case 'I':
+        this.setMode();
+        this.moveCursorToFirstNonWhitespace();
+        break;
+      case '$': {
+        const { line } = this.getCurrentLineAndCol();
+        if (isVisualMode(this.mode)) {
+          this.moveCursorToCol(line.length);
+          break;
+        }
+        const graphemes = getLineGraphemes(line);
+        this.moveCursorToCol(graphemes[graphemes.length - 1]?.start ?? 0);
+        break;
+      }
+      case 'o':
+        this.openLineBelow();
+        this.setMode();
+        break;
+      case 'O':
+        this.openLineAbove();
+        this.setMode();
+        break;
+      case 'D':
+        this.takeTotalCount(1);
+        this.cutToEndOfLine();
+        break;
+      case 'C':
+        this.takeTotalCount(1);
+        this.cutToEndOfLine();
+        this.setMode();
+        break;
+      case 'S':
+        this.takeTotalCount(1);
+        this.cutCurrentLineContent();
+        this.setMode();
+        break;
+      case 's':
+        this.cutCharUnderCursor();
+        this.setMode();
+        break;
+      case 'x':
+        this.cutCharUnderCursor(true);
+        break;
+      case 'X':
+        this.cutCharsBeforeCursor();
+        break;
+      case 'j':
+        this.moveCursorVertically(1);
+        break;
+      case 'k':
+        this.moveCursorVertically(-1);
+        break;
+      default:
+        if (seq) super.handleInput(seq);
+    }
+  }
+
+  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,
+    );
+
+    if (targetCol !== null && saveMotion) {
+      this.lastCharMotion = { motion, char: targetChar };
+    }
+
+    if (targetCol !== null && targetCol !== col) {
+      this.moveCursorToCol(targetCol);
+    }
+  }
+
+  private executeParagraphMotion(direction: 'forward' | 'backward'): void {
+    const lines = this.getLines();
+    const fromLine = this.getCursor().line;
+    const count = this.takeTotalCount(1);
+    const targetLine = findParagraphMotionTarget(lines, fromLine, direction, count);
+    this.moveCursorToLineStart(targetLine);
+  }
+
+  private tryMoveCursorByState(delta: number): boolean {
+    if (delta === 0) return true;
+
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines)) 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;
+    const line = state.lines[cursorLine] ?? '';
+    if (this.hasMultiCodeUnitGraphemes(line)) return false;
+
+    const target = cursorCol + delta;
+
+    if (target < 0 || target > line.length) return false;
+
+    state.cursorCol = target;
+    editor.preferredVisualCol = target;
+    editor.tui?.requestRender?.();
+    return true;
+  }
+
+  private moveCursorBy(delta: number): void {
+    if (delta === 0) return;
+
+    if (this.tryMoveCursorByState(delta)) return;
+
+    const seq = delta > 0 ? ESC_RIGHT : ESC_LEFT;
+    for (let i = 0; i < Math.abs(delta); i++) {
+      super.handleInput(seq);
+    }
+  }
+
+  private moveCursorVertically(delta: number): void {
+    if (delta === 0) return;
+
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines) || state.lines.length === 0) {
+      const seq = delta > 0 ? ESC_DOWN : ESC_UP;
+      for (let i = 0; i < Math.abs(delta); i++) {
+        super.handleInput(seq);
+      }
+      return;
+    }
+
+    const currentLine = state.cursorLine ?? 0;
+    const targetLine = Math.max(
+      0,
+      Math.min(currentLine + delta, state.lines.length - 1),
+    );
+    if (targetLine === currentLine) return;
+
+    const preferredCol = editor.preferredVisualCol ?? state.cursorCol ?? 0;
+    const targetLineText = state.lines[targetLine] ?? '';
+    editor.lastAction = null;
+    state.cursorLine = targetLine;
+    state.cursorCol = Math.min(preferredCol, targetLineText.length);
+    editor.preferredVisualCol = preferredCol;
+    editor.tui?.requestRender?.();
+  }
+
+  private moveCursorToCol(col: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines)) return;
+
+    editor.lastAction = null;
+    state.cursorCol = col;
+    editor.preferredVisualCol = col;
+    editor.tui?.requestRender?.();
+  }
+
+  private moveCursorToAbsoluteIndex(abs: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines)) return;
+
+    const { line, col } = this.getCursorFromAbsoluteIndex(this.getText(), abs);
+    editor.lastAction = null;
+    state.cursorLine = line;
+    state.cursorCol = col;
+    editor.preferredVisualCol = col;
+    editor.tui?.requestRender?.();
+  }
+
+  private moveCursorToLineStart(lineIndex: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      lastAction?: string | null;
+      tui?: { requestRender?: () => void };
+    };
+
+    const state = editor.state;
+    if (!state || !Array.isArray(state.lines) || state.lines.length === 0) {
+      super.handleInput(CTRL_A);
+      return;
+    }
+
+    const targetLine = Math.max(0, Math.min(lineIndex, state.lines.length - 1));
+    editor.lastAction = null;
+    state.cursorLine = targetLine;
+    state.cursorCol = 0;
+    editor.preferredVisualCol = null;
+    editor.tui?.requestRender?.();
+  }
+
+  private moveCursorToFirstNonWhitespace(): void {
+    const { line } = this.getCurrentLineAndCol();
+    const targetCol = findFirstNonWhitespaceColumn(line);
+    this.moveCursorToCol(targetCol);
+  }
+
+  private moveCursorToBufferEnd(): void {
+    const lines = this.getLines();
+    this.moveCursorToLineStart(Math.max(0, lines.length - 1));
+  }
+
+  private joinLines(normalize: boolean): void {
+    const count = this.takeTotalCount(2);
+    const steps = Math.max(0, count - 1);
+    if (steps === 0) return;
+
+    this.applySyntheticEdit(() => {
+      const editor = this as unknown as ModalEditorInternals;
+      const state = editor.state;
+      if (!state || !Array.isArray(state.lines)) return;
+
+      const currentLine = state.cursorLine ?? 0;
+      let joinPoint = state.cursorCol ?? 0;
+
+      if (this.replayingRepeat && currentLine >= state.lines.length - 1) {
+        state.cursorCol = 0;
+        editor.preferredVisualCol = 0;
+        return;
+      }
+
+      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] ?? '';
+        let joined: string;
+
+        if (normalize) {
+          const trimmedRight = right.trimStart();
+          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;
+        } else {
+          joined = left + right;
+          joinPoint = left.length;
+        }
+
+        state.lines.splice(currentLine, 2, joined);
+      }
+
+      state.cursorLine = currentLine;
+      state.cursorCol = joinPoint;
+      editor.preferredVisualCol = joinPoint;
+    });
+  }
+
+  private isWordChar(ch: string): boolean {
+    return /\w/.test(ch);
+  }
+
+  private charType(
+    ch: string | undefined,
+    semanticClass: WordMotionClass = 'word',
+  ): 'space' | 'word' | 'other' {
+    if (!ch || /\s/.test(ch)) return 'space';
+    if (semanticClass === 'WORD') return 'word';
+    if (this.isWordChar(ch)) return 'word';
+    return 'other';
+  }
+
+  private resolveWordMotion(
+    motion: string,
+  ): { motion: 'w' | 'e' | 'b'; semanticClass: WordMotionClass } | null {
+    if (motion === 'w' || motion === 'e' || motion === 'b') {
+      return { motion, semanticClass: 'word' };
+    }
+
+    if (motion === 'W' || motion === 'E' || motion === 'B') {
+      const normalizedMotion = motion.toLowerCase() as 'w' | 'e' | 'b';
+      return { motion: normalizedMotion, semanticClass: 'WORD' };
+    }
+
+    return null;
+  }
+
+  private getAbsoluteIndex(line: number, col: number): number {
+    const lines = this.getLines();
+    let idx = 0;
+    for (let i = 0; i < line; i++) {
+      idx += (lines[i] ?? '').length + 1;
+    }
+    return idx + col;
+  }
+
+  private getAbsoluteIndexFromCursor(): number {
+    const cursor = this.getCursor();
+    return this.getAbsoluteIndex(cursor.line, cursor.col);
+  }
+
+  private getMatchingPairMotionTarget() {
+    const cursor = this.getCursor();
+    const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
+    return resolveMatchingPairMotionTarget(
+      this.getText(),
+      this.getAbsoluteIndexFromCursor(),
+      lineStartAbs,
+      lineStartAbs + (this.getLines()[cursor.line] ?? '').length,
+    );
+  }
+
+  private moveToMatchingPairTarget(): void {
+    const target = this.getMatchingPairMotionTarget();
+    if (target) this.moveCursorToAbsoluteIndex(target.targetAbs);
+  }
+
+  private applyPercentOp(): void {
+    const op = this.pendingOperator;
+    const counted = this.hasPendingCount();
+    this.clearPendingState();
+    if (!op || counted) {
+      this.cancelRepeatableCommand();
+      return;
+    }
+
+    const t = this.getMatchingPairMotionTarget();
+    if (!t) {
+      this.cancelRepeatableCommand();
+      return;
+    }
+
+    if (op === 'y') {
+      this.yankRangeByAbsolute(t.rangeAnchorAbs, t.targetAbs, true);
+      return;
+    }
+
+    this.deleteRangeByAbsolute(t.rangeAnchorAbs, t.targetAbs, true);
+    if (op === 'c') {
+      this.setMode('insert');
+      return;
+    }
+  }
+
+  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,
+    direction: 'forward' | 'backward',
+    target: 'start' | 'end',
+    count: number = 1,
+    semanticClass: WordMotionClass = 'word',
+  ): number {
+    const len = text.length;
+    if (len === 0) return 0;
+
+    const steps = Math.max(1, Math.min(MAX_COUNT, count));
+    let i = Math.max(0, Math.min(abs, len));
+
+    for (let step = 0; step < steps; step++) {
+      let next = i;
+
+      if (direction === 'forward') {
+        if (next >= len) {
+          next = len;
+        } 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) === 'space')
+            next++;
+        } else {
+          if (next < len - 1) 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++;
+          }
+        }
+      } else {
+        if (next >= len) next = len - 1;
+        if (next > 0) 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--;
+      }
+
+      if (next === i) break;
+      i = next;
+    }
+
+    return i;
+  }
+
+  private tryFindWordTargetInLine(
+    line: string,
+    col: number,
+    direction: WordMotionDirection,
+    target: WordMotionTarget,
+    allowSameColumn: boolean = false,
+    semanticClass: WordMotionClass = 'word',
+  ): number | null {
+    if (line.length === 0) return null;
+    if (col < 0 || col > line.length) return null;
+
+    if (direction === 'forward') {
+      if (col >= line.length) return null;
+    } else {
+      if (col <= 0) return null;
+      if (!/\S/.test(line.slice(0, col))) return null;
+    }
+
+    const targetCol = this.wordBoundaryCache.tryFindTarget(
+      line,
+      col,
+      direction,
+      target,
+      semanticClass,
+    );
+    if (targetCol === null) return null;
+
+    if (direction === 'forward') {
+      if (targetCol >= line.length) return null;
+      if (allowSameColumn) {
+        if (targetCol < col) return null;
+      } else if (targetCol <= col) {
+        return null;
+      }
+      return targetCol;
+    }
+
+    if (allowSameColumn) {
+      if (targetCol > col) return null;
+    } else if (targetCol >= col) {
+      return null;
+    }
+
+    return targetCol;
+  }
+
+  private tryFindWordTargetLineLocal(
+    direction: WordMotionDirection,
+    target: WordMotionTarget,
+    semanticClass: WordMotionClass = 'word',
+  ): number | null {
+    const cursor = this.getCursor();
+    const lineIndex = cursor.line;
+    const col = cursor.col;
+    const lineSnapshot = this.getLines()[lineIndex] ?? '';
+
+    const targetCol = this.tryFindWordTargetInLine(
+      lineSnapshot,
+      col,
+      direction,
+      target,
+      false,
+      semanticClass,
+    );
+    if (targetCol === null) return null;
+
+    const liveLine = this.getLines()[lineIndex] ?? '';
+    const liveCol = this.getCursor().col;
+    if (liveLine !== lineSnapshot || liveCol !== col) return null;
+
+    return targetCol;
+  }
+
+  private tryMoveWordLineLocal(
+    direction: 'forward' | 'backward',
+    target: 'start' | 'end',
+    semanticClass: WordMotionClass = 'word',
+  ): boolean {
+    const col = this.getCursor().col;
+    const targetCol = this.tryFindWordTargetLineLocal(direction, target, semanticClass);
+    if (targetCol === null || targetCol === col) return false;
+
+    this.moveCursorToCol(targetCol);
+    return true;
+  }
+
+  private tryWordMotionLineLocalRange(
+    motion: 'w' | 'e' | 'b',
+    count: number = 1,
+    semanticClass: WordMotionClass = 'word',
+  ): { col: number; targetCol: number; inclusive: boolean } | null {
+    const cursor = this.getCursor();
+    const lineIndex = cursor.line;
+    const col = cursor.col;
+    const lineSnapshot = this.getLines()[lineIndex] ?? '';
+    const direction: WordMotionDirection = motion === 'b' ? 'backward' : 'forward';
+    const target: WordMotionTarget = motion === 'e' ? 'end' : 'start';
+    const steps = Math.max(1, Math.min(MAX_COUNT, count));
+
+    let currentCol = col;
+    for (let step = 0; step < steps; step++) {
+      const nextCol = this.tryFindWordTargetInLine(
+        lineSnapshot,
+        currentCol,
+        direction,
+        target,
+        motion === 'e',
+        semanticClass,
+      );
+      if (nextCol === null) return null;
+      if (nextCol === currentCol && step < steps - 1) return null;
+      currentCol = nextCol;
+    }
+
+    const liveLine = this.getLines()[lineIndex] ?? '';
+    const liveCol = this.getCursor().col;
+    if (liveLine !== lineSnapshot || liveCol !== col) return null;
+
+    return {
+      col,
+      targetCol: currentCol,
+      inclusive: motion === 'e',
+    };
+  }
+
+  private moveWord(
+    direction: 'forward' | 'backward',
+    target: 'start' | 'end',
+    count: number = 1,
+    semanticClass: WordMotionClass = 'word',
+  ): void {
+    let remaining = Math.max(1, Math.min(MAX_COUNT, count));
+
+    while (remaining > 0) {
+      if (this.tryMoveWordLineLocal(direction, target, semanticClass)) {
+        remaining--;
+        continue;
+      }
+
+      const text = this.getText();
+      const currentAbs = this.getAbsoluteIndexFromCursor();
+      const targetAbs = this.findWordTargetInText(
+        text,
+        currentAbs,
+        direction,
+        target,
+        remaining,
+        semanticClass,
+      );
+      if (targetAbs !== currentAbs) {
+        this.moveCursorToAbsoluteIndex(targetAbs);
+      }
+      return;
+    }
+  }
+
+  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;
+    const shouldMirror = text !== '' && this.shouldMirrorRegisterWrite(source);
+    if (!shouldMirror) return;
+
+    this.clipboardMirror.mirror(text);
+  }
+
+  private getCurrentLineAndCol(): { line: string; col: number } {
+    const line = this.getLines()[this.getCursor().line] ?? '';
+    const col = this.getCursor().col;
+    return { line, col };
+  }
+
+  private hasMultiCodeUnitGraphemes(line: string): boolean {
+    return getLineGraphemes(line).some((segment) => segment.end - segment.start > 1);
+  }
+
+  private getGraphemeRangeAtCol(
+    line: string,
+    col: number,
+    count: number,
+    clampToLine: boolean = false,
+  ): { 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);
+    if (startIndex === -1) return null;
+
+    let endIndex = startIndex + Math.max(1, count) - 1;
+    if (endIndex >= segments.length) {
+      if (!clampToLine) return null;
+      endIndex = segments.length - 1;
+    }
+
+    const startSegment = segments[startIndex];
+    const endSegment = segments[endIndex];
+    if (!startSegment || !endSegment) return null;
+
+    return {
+      start: startSegment.start,
+      end: endSegment.end,
+    };
+  }
+
+  private isCursorOnNonWhitespace(): boolean {
+    const { line, col } = this.getCurrentLineAndCol();
+    const ch = line[col];
+    return ch !== undefined && !/\s/.test(ch);
+  }
+
+  private isCursorAtOrPastEol(): boolean {
+    const { line, col } = this.getCurrentLineAndCol();
+    return col >= line.length;
+  }
+
+  private cutCharUnderCursor(normal: boolean = false): void {
+    const count = Math.max(1, Math.min(MAX_COUNT, this.takeTotalCount(1)));
+    const cursor = this.getCursor();
+    const line = this.getLines()[cursor.line] ?? '';
+    const range = this.getGraphemeRangeAtCol(line, cursor.col, count, true);
+    if (!range) return;
+
+    const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
+    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),
+      lineStartAbs + range.start,
+    );
+    if (normal) {
+      const { line, col } = this.getCurrentLineAndCol();
+      if (line && col >= line.length) this.moveCursorBy(-1);
+    }
+  }
+
+  // Vim `X`: delete up to {count} graphemes before the cursor on the current
+  // line, clamping at column 0; a cursor already at column 0 is a no-op.
+  private cutCharsBeforeCursor(): void {
+    const count = Math.max(1, Math.min(MAX_COUNT, this.takeTotalCount(1)));
+    const cursor = this.getCursor();
+    if (cursor.col <= 0) return;
+    const line = this.getLines()[cursor.line] ?? '';
+    const segments = getLineGraphemes(line);
+    const before = segments.filter((segment) => segment.end <= cursor.col);
+    if (before.length === 0) return;
+    const take = Math.min(count, before.length);
+    const start = before[before.length - take].start;
+    const end = before[before.length - 1].end;
+    const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
+    const text = this.getText();
+    this.writeToRegister(line.slice(start, end));
+    this.replaceTextInBuffer(
+      text.slice(0, lineStartAbs + start) + text.slice(lineStartAbs + end),
+      lineStartAbs + start,
+    );
+  }
+
+  private cutToEndOfLine(): void {
+    const lines = this.getLines();
+    const cursorLine = this.getCursor().line;
+    const { line, col } = this.getCurrentLineAndCol();
+
+    const hasNextLine = cursorLine < lines.length - 1;
+    const deleted = col < line.length ? line.slice(col) : hasNextLine ? '\n' : '';
+
+    if (deleted !== '') this.writeToRegister(deleted);
+    super.handleInput(CTRL_K);
+  }
+
+  private cutCurrentLineContent(): void {
+    const lines = this.getLines();
+    const cursorLine = this.getCursor().line;
+    const { line } = this.getCurrentLineAndCol();
+
+    const hasNextLine = cursorLine < lines.length - 1;
+    const deleted = line.length > 0 ? line : hasNextLine ? '\n' : '';
+
+    this.writeToRegister(deleted);
+    super.handleInput(CTRL_A);
+    super.handleInput(CTRL_K);
+  }
+
+  private cutLine(): void {
+    this.cutCurrentLineContent();
+  }
+
+  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));
+    const clampedEnd = Math.max(0, Math.min(endLine, last));
+    return {
+      start: Math.min(clampedStart, clampedEnd),
+      end: Math.max(clampedStart, clampedEnd),
+    };
+  }
+
+  private getLinewisePayload(startLine: number, endLine: number): string {
+    const lines = this.getLines();
+    const { start, end } = this.getNormalizedLineRange(startLine, endLine);
+    return `${lines.slice(start, end + 1).join('\n')}\n`;
+  }
+
+  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);
+    const lastLine = Math.max(0, lines.length - 1);
+
+    let startAbs = this.getAbsoluteIndex(start, 0);
+    let endAbs: number;
+
+    if (end < lastLine) {
+      const endLineText = lines[end] ?? '';
+      endAbs = this.getAbsoluteIndex(end, endLineText.length) + 1;
+    } else {
+      endAbs = text.length;
+      if (start > 0) {
+        startAbs = Math.max(0, startAbs - 1);
+      }
+    }
+
+    return { startAbs, endAbs };
+  }
+
+  private deleteLineRange(startLine: number, endLine: number): void {
+    const lines = this.getLines();
+    if (lines.length === 0) return;
+
+    const payload = this.getLinewisePayload(startLine, endLine);
+    const { startAbs, endAbs } = this.getLineDeleteAbsoluteRange(startLine, endLine);
+
+    this.writeToRegister(payload);
+
+    if (endAbs > startAbs) {
+      const text = this.getText();
+      const newText = text.slice(0, startAbs) + text.slice(endAbs);
+      this.replaceTextInBuffer(newText, startAbs);
+
+      super.handleInput(CTRL_A);
+    }
+  }
+
+  private yankLineRange(startLine: number, endLine: number): void {
+    if (this.getLines().length === 0) return;
+    this.writeToRegister(this.getLinewisePayload(startLine, endLine), 'yank');
+  }
+
+  private deleteLinewiseByDelta(delta: number): void {
+    const currentLine = this.getCursor().line;
+    this.deleteLineRange(currentLine, currentLine + delta);
+  }
+
+  private yankLinewiseByDelta(delta: number): void {
+    const currentLine = this.getCursor().line;
+    this.yankLineRange(currentLine, currentLine + delta);
+  }
+
+  private deleteToBufferEndLinewise(): void {
+    this.deleteLineRange(this.getCursor().line, this.getLines().length - 1);
+  }
+
+  private yankToBufferEndLinewise(): void {
+    this.yankLineRange(this.getCursor().line, this.getLines().length - 1);
+  }
+
+  private deleteWithMotion(motion: string, count: number = 1): boolean {
+    const cursor = this.getCursor();
+    const col = cursor.col;
+
+    if (motion === '$') {
+      this.cutToEndOfLine();
+      return true;
+    }
+
+    if (motion === '0') {
+      this.deleteRange(col, 0, false);
+      return true;
+    }
+
+    if (motion === '^') {
+      this.deleteRange(
+        col,
+        findFirstNonWhitespaceColumn(this.getLines()[cursor.line] ?? ''),
+        false,
+      );
+      return true;
+    }
+
+    const wordMotion = this.resolveWordMotion(motion);
+    if (wordMotion) {
+      const lineLocalRange = this.tryWordMotionLineLocalRange(
+        wordMotion.motion,
+        count,
+        wordMotion.semanticClass,
+      );
+      if (lineLocalRange) {
+        this.deleteRange(
+          lineLocalRange.col,
+          lineLocalRange.targetCol,
+          lineLocalRange.inclusive,
+        );
+        return true;
+      }
+
+      const text = this.getText();
+      const currentAbs = this.getAbsoluteIndexFromCursor();
+      const targetAbs = this.findWordTargetInText(
+        text,
+        currentAbs,
+        wordMotion.motion === 'b' ? 'backward' : 'forward',
+        wordMotion.motion === 'e' ? 'end' : 'start',
+        count,
+        wordMotion.semanticClass,
+      );
+      this.deleteRangeByAbsolute(currentAbs, targetAbs, wordMotion.motion === 'e');
+      return true;
+    }
+
+    return false;
+  }
+
+  // Handles counted `d$`/`c$`. `$` with a count N descends N-1 lines before
+  // going to end of line, so the operator spans multiple lines. Semantics
+  // match nvim (verified against the real editor): count 1 delegates to the
+  // existing single-line path; on the last line a count >= 2 aborts as a
+  // no-op; `d$` (but not `c$`) becomes linewise when the cursor is at or
+  // before the first non-blank column.
+  private applyLineEndOperator(count: number, mode: 'change' | 'delete'): boolean {
+    const clampedCount = Math.max(1, Math.min(MAX_COUNT, count));
+    if (clampedCount <= 1) {
+      this.cutToEndOfLine();
+      return true;
+    }
+
+    const lines = this.getLines();
+    if (lines.length === 0) return false;
+
+    const cursor = this.getCursor();
+    const lastLine = lines.length - 1;
+    if (cursor.line >= lastLine) return false;
+
+    const targetLine = Math.min(cursor.line + clampedCount - 1, lastLine);
+    const text = this.getText();
+    const startAbs = this.getAbsoluteIndex(cursor.line, cursor.col);
+    const targetLineText = lines[targetLine] ?? '';
+    const targetEndAbs = this.getAbsoluteIndex(targetLine, targetLineText.length);
+
+    const firstNonBlank = findFirstNonWhitespaceColumn(lines[cursor.line] ?? '');
+    const linewise = mode === 'delete' && cursor.col <= firstNonBlank;
+
+    if (linewise) {
+      const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
+      this.writeToRegister(`${text.slice(lineStartAbs, targetEndAbs)}\n`);
+
+      let removeStart = lineStartAbs;
+      let removeEnd = targetEndAbs;
+      if (targetLine < lastLine) {
+        removeEnd = targetEndAbs + 1;
+      } else if (cursor.line > 0) {
+        removeStart = Math.max(0, lineStartAbs - 1);
+      }
+
+      const newText = text.slice(0, removeStart) + text.slice(removeEnd);
+      this.replaceTextInBuffer(newText, Math.min(startAbs, newText.length));
+      this.moveCursorAfterDeleteToLineEnd(cursor.line, cursor.col);
+      return true;
+    }
+
+    this.writeToRegister(text.slice(startAbs, targetEndAbs));
+    const newText = text.slice(0, startAbs) + text.slice(targetEndAbs);
+    this.replaceTextInBuffer(newText, Math.min(startAbs, newText.length));
+    if (mode === 'delete') {
+      this.moveCursorAfterDeleteToLineEnd(cursor.line, cursor.col);
+    }
+    return true;
+  }
+
+  private moveCursorAfterDeleteToLineEnd(startLine: number, startCol: number): void {
+    const lines = this.getLines();
+    const lineIndex = Math.min(startLine, Math.max(0, lines.length - 1));
+    if (lineIndex < startLine) {
+      this.moveCursorToLineStart(lineIndex);
+      return;
+    }
+
+    const line = lines[lineIndex] ?? '';
+    if (line.length > 0 && startCol >= line.length) {
+      const graphemes = getLineGraphemes(line);
+      this.moveCursorToCol(graphemes[graphemes.length - 1]?.start ?? 0);
+      return;
+    }
+
+    this.moveCursorToCol(Math.min(startCol, line.length));
+  }
+
+  private deleteWithCharMotion(motion: CharMotion, targetChar: string): boolean {
+    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);
+
+    if (targetCol === null) return false;
+
+    this.lastCharMotion = { motion, char: targetChar };
+    this.deleteRange(col, targetCol, true);
+    return true;
+  }
+
+  private handlePendingYank(data: string): void {
+    if (this.opDigit(data)) return;
+
+    if (data === '%') {
+      this.applyPercentOp();
+      return;
+    }
+
+    if (data === 'y') {
+      const count = this.takeTotalCount(1);
+      this.yankLinewiseByDelta(count - 1);
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (data === 'j' || data === 'k') {
+      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);
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (data === 'G') {
+      if (this.prefixCount.length > 0 || this.operatorCount.length > 0) {
+        this.cancelPendingOperator(data);
+        return;
+      }
+
+      this.yankToBufferEndLinewise();
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (data === '_') {
+      const count = this.takeTotalCount(1);
+      this.yankLinewiseByDelta(count - 1);
+      this.pendingOperator = null;
+      return;
+    }
+
+    if (CHAR_MOTION_KEYS.has(data)) {
+      this.pendingMotion = data as PendingMotion;
+      return;
+    }
+
+    if (data === 'i' || data === 'a') {
+      this.pendingTextObject = data;
+      return;
+    }
+
+    if (this.hasPendingCount()) {
+      this.cancelPendingOperator(data);
+      return;
+    }
+
+    if (this.yankWithMotion(data)) {
+      this.pendingOperator = null;
+    } else {
+      this.cancelPendingOperator(data); // cancel on unrecognised motion
+    }
+  }
+
+  private yankWithMotion(motion: string): boolean {
+    const cursor = this.getCursor();
+    const line = this.getLines()[cursor.line] ?? '';
+    const col = cursor.col;
+
+    if (motion === '$') {
+      this.yankRange(col, line.length, false);
+      return true;
+    }
+
+    if (motion === '0') {
+      this.yankRange(col, 0, false);
+      return true;
+    }
+
+    if (motion === '^') {
+      this.yankRange(col, findFirstNonWhitespaceColumn(line), false);
+      return true;
+    }
+
+    const wordMotion = this.resolveWordMotion(motion);
+    if (wordMotion) {
+      const lineLocalRange = this.tryWordMotionLineLocalRange(
+        wordMotion.motion,
+        1,
+        wordMotion.semanticClass,
+      );
+      if (lineLocalRange) {
+        this.yankRange(
+          lineLocalRange.col,
+          lineLocalRange.targetCol,
+          lineLocalRange.inclusive,
+        );
+        return true;
+      }
+
+      const text = this.getText();
+      const currentAbs = this.getAbsoluteIndexFromCursor();
+      const targetAbs = this.findWordTargetInText(
+        text,
+        currentAbs,
+        wordMotion.motion === 'b' ? 'backward' : 'forward',
+        wordMotion.motion === 'e' ? 'end' : 'start',
+        1,
+        wordMotion.semanticClass,
+      );
+      this.yankRangeByAbsolute(currentAbs, targetAbs, wordMotion.motion === 'e');
+      return true;
+    }
+
+    return false;
+  }
+
+  private yankWithCharMotion(motion: CharMotion, targetChar: string): 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, false, count);
+
+    if (targetCol === null) return;
+
+    this.lastCharMotion = { motion, char: targetChar };
+    this.yankRange(col, targetCol, true);
+  }
+
+  private yankRange(col: number, targetCol: number, inclusive: boolean): void {
+    const line = this.getLines()[this.getCursor().line] ?? '';
+    const start = Math.min(col, targetCol);
+    const rawEnd = Math.max(col, targetCol) + (inclusive ? 1 : 0);
+    let end = Math.min(rawEnd, line.length);
+
+    if (inclusive) {
+      const targetRange = this.getGraphemeRangeAtCol(line, Math.max(col, targetCol), 1);
+      end = targetRange?.end ?? end;
+    }
+
+    if (end <= start) return;
+
+    this.writeToRegister(line.slice(start, end), 'yank');
+  }
+
+  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), 'yank');
+  }
+
+  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++) {
+      const line = lines[lineIndex] ?? '';
+      if (remaining <= line.length) return { line: lineIndex, col: remaining };
+      remaining -= line.length + 1;
+    }
+    const lastLine = Math.max(0, lines.length - 1);
+    return { line: lastLine, col: (lines[lastLine] ?? '').length };
+  }
+
+  private replaceTextInBuffer(text: string, cursorAbs: number): void {
+    const editor = this as unknown as {
+      state?: { lines?: string[]; cursorLine?: number; cursorCol?: number };
+      preferredVisualCol?: number | null;
+      historyIndex?: number;
+      lastAction?: string | null;
+      onChange?: (text: string) => void;
+      tui?: { requestRender?: () => void };
+      pushUndoSnapshot?: () => void;
+      autocompleteState?: unknown;
+      updateAutocomplete?: () => void;
+    };
+    const state = editor.state;
+    if (!state) return;
+    const currentText = this.getText();
+    if (currentText !== text) editor.pushUndoSnapshot?.();
+    const nextLines = text.length === 0 ? [''] : text.split('\n');
+    const { line, col } = this.getCursorFromAbsoluteIndex(text, cursorAbs);
+    editor.historyIndex = -1;
+    editor.lastAction = null;
+    state.lines = nextLines;
+    state.cursorLine = line;
+    state.cursorCol = col;
+    editor.preferredVisualCol = null;
+    editor.onChange?.(text);
+    if (editor.autocompleteState) editor.updateAutocomplete?.();
+    editor.tui?.requestRender?.();
+  }
+
+  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);
+    const end = Math.min(rawEnd, text.length);
+
+    if (end <= start) return;
+
+    this.writeToRegister(text.slice(start, end));
+
+    this.replaceTextInBuffer(text.slice(0, start) + text.slice(end), start);
+  }
+
+  private getWordObjectRange(
+    kind: TextObjectKind,
+    count: number = 1,
+    semanticClass: WordTextObjectClass = 'word',
+  ): TextObjectRange | null {
+    const lines = this.getLines();
+    const cursor = this.getCursor();
+    const line = lines[cursor.line] ?? '';
+    const lineStartAbs = this.getAbsoluteIndex(cursor.line, 0);
+
+    return resolveWordTextObjectRange(
+      line,
+      lineStartAbs,
+      cursor.col,
+      kind,
+      count,
+      semanticClass,
+    );
+  }
+
+  private moveCursorToPreviousGraphemeStart(): void {
+    const cursor = this.getCursor();
+    const line = this.getLines()[cursor.line] ?? '';
+    const col = Math.max(0, Math.min(cursor.col, line.length));
+    if (col <= 0) return;
+
+    const range = this.getGraphemeRangeAtCol(line, col - 1, 1);
+    if (range) this.moveCursorToCol(range.start);
+  }
+
+  private moveCursorToLastGraphemeOnLine(): void {
+    const { line } = this.getCurrentLineAndCol();
+    const graphemes = getLineGraphemes(line);
+    this.moveCursorToCol(graphemes[graphemes.length - 1]?.start ?? 0);
+  }
+
+  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);
+    const start = Math.min(col, targetCol);
+    const rawEnd = Math.max(col, targetCol) + (inclusive ? 1 : 0);
+    let end = Math.min(rawEnd, line.length);
+
+    if (inclusive) {
+      const targetRange = this.getGraphemeRangeAtCol(line, Math.max(col, targetCol), 1);
+      end = targetRange?.end ?? end;
+    }
+
+    this.deleteRangeByAbsolute(lineStartAbs + start, lineStartAbs + end);
+  }
+
+  private getDesiredCursorShapeSequence(): CursorShapeSequence {
+    return 'insert' === this.mode && this.pendingExCommand === null
+      ? INSERT_CURSOR_SHAPE
+      : BLOCK_CURSOR_SHAPE;
+  }
+
+  private syncCursorShapeForRender(lines: string[]): void {
+    if (!this.cursorShapeRuntime) return;
+    if (!hasPromptCursorMarker(lines)) return;
+
+    if (this.cursorShapeRuntime.getShowHardwareCursor?.() === false) {
+      this.lastCursorShapeSequence = null;
+      return;
+    }
+
+    stripSoftwareCursorWhenHardwareCursorIsUsed(lines);
+
+    const sequence = this.getDesiredCursorShapeSequence();
+    if (sequence === this.lastCursorShapeSequence) return;
+
+    this.cursorShapeRuntime.writeCursorShape(sequence);
+    this.lastCursorShapeSequence = sequence;
+  }
+
+  private getModeRailItem(): { plain: string; styled: string } {
+    const plain = this.getModeIcon();
+    const modeColorize = this.getModeLabelColorizer();
+    return { plain, styled: modeColorize ? modeColorize(plain) : plain };
+  }
+
+  private withoutInheritedEditorFrame(lines: string[], width: number): string[] {
+    const editor = this as unknown as {
+      autocompleteState?: unknown;
+      autocompleteList?: { render: (contentWidth: number) => string[] };
+      getPaddingX?: () => number;
+    };
+    let autocompleteRows = 0;
+    if (editor.autocompleteState && editor.autocompleteList) {
+      const maxPadding = Math.max(0, Math.floor((width - 1) / 2));
+      const padding = Math.min(editor.getPaddingX?.() ?? 0, maxPadding);
+      const contentWidth = Math.max(1, width - padding * 2);
+      try {
+        autocompleteRows = editor.autocompleteList.render(contentWidth).length;
+      } catch {
+        // Fail soft: never drop an unknown trailing row as presumed frame chrome.
+        return lines.slice(1);
+      }
+    }
+    const bottomFrameIndex = lines.length - autocompleteRows - 1;
+    if (bottomFrameIndex <= 0) return lines.slice(1);
+    return lines.filter((_, index) => index !== 0 && index !== bottomFrameIndex);
+  }
+
+  render(width: number): string[] {
+    if (this.externalEditorOnly) {
+      try {
+        return this.deckRenderer?.(width, this.getModeRailItem()) ?? [];
+      } catch {
+        return [];
+      }
+    }
+
+    const lines = super.render(width);
+    this.syncCursorShapeForRender(lines);
+    const editorLines = !this.editorFrameEnabled
+      ? this.withoutInheritedEditorFrame(lines, width)
+      : !this.promptRailsEnabled
+        ? lines
+        : renderPromptRails({
+            lines,
+            width,
+            snapshot: this.getPromptRail(),
+            mode: this.getModeRailItem(),
+            colorize: this.promptRailColorize,
+          });
+    if (!this.deckRenderer) return editorLines;
+    try {
+      return [...this.deckRenderer(width, this.getModeRailItem()), ...editorLines];
+    } catch {
+      return editorLines;
+    }
+  }
+
+  private getModeLabelColorizer(): ((s: string) => string) | null {
+    if (!this.labelColorizers) return null;
+    const labelColorizers = this.labelColorizers;
+    const wrap = this.labelTransform ?? ((s: string) => s);
+    return (s: string) =>
+      this.resolveSurfaceColor(labelColorizers, this.labelSync, s, wrap);
+  }
+
+  private getModeIcon(): string {
+    return MODE_ICONS[this.getActiveMode()];
+  }
+}
+
+export interface PiVimDeckSurface {
+  render(width: number, theme: Theme, modeRail?: PiVimModeRail): string[];
+  setRequestRender(requestRender: (() => void) | null): void;
+}
+
+export interface PiVimOptions {
+  surface?: 'rails' | 'editor-only' | 'external-editor-only';
+  deckSurface?: PiVimDeckSurface;
+}
+
+export default function (pi: ExtensionAPI, options: PiVimOptions = {}) {
+  const editorOnly = options.surface === 'editor-only';
+  const externalEditorOnly = options.surface === 'external-editor-only';
+  const deckIntegrated = editorOnly || externalEditorOnly;
+  let cursorShapeCleanup: CursorShapeCleanup | null = null;
+  let promptExternalEditor: PromptExternalEditor | null = null;
+  let requestPromptRender: (() => void) | null = null;
+  let getSessionEntries: (() => readonly unknown[]) | null = null;
+  const promptRail = new PromptRailStore();
+
+  const stopPromptRail = pi.events.on(FANCY_FOOTER_WIDGET_CHANNEL, (raw) => {
+    if (promptRail.apply(raw)) requestPromptRender?.();
+  });
+  const refreshSessionCost = () => {
+    if (!getSessionEntries) return;
+    if (promptRail.setTotalCost(collectSessionCost(getSessionEntries()))) {
+      requestPromptRender?.();
+    }
+  };
+
+  pi.on('session_start', (_event, ctx) => {
+    getSessionEntries = () => ctx.sessionManager.getBranch();
+    refreshSessionCost();
+    const piVimSettings = readPiVimSettings(ctx.cwd);
+    const clipboardMirrorPolicy = resolveClipboardMirrorPolicy(
+      piVimSettings.clipboardMirror,
+    );
+    if (clipboardMirrorPolicy.warning && ctx.hasUI) {
+      ctx.ui.notify(clipboardMirrorPolicy.warning, 'warning');
+    }
+    const exCommand = resolveExCommandSettings(
+      piVimSettings.exCommand,
+      piVimSettings.globalExCommand,
+    );
+    if (exCommand.warning && ctx.hasUI) {
+      ctx.ui.notify(exCommand.warning, 'warning');
+    }
+
+    const t = ctx.ui.theme;
+    const modeColors = resolveModeColors(piVimSettings.modeColors);
+    const { borderSync, labelSync } = resolveSurfaceSyncMaps(piVimSettings);
+    const labelColorizers = t ? buildModeColorizers(t, modeColors) : null;
+    // Both surfaces get their colorizers unconditionally. Host-synced modes
+    // remain visually identical while still supporting the handoff override.
+    const borderColorizers = t ? buildModeColorizers(t, modeColors) : null;
+    // Enables the "thinking" neutral-default detection; unused by "mode"/"host".
+    const offBorderColor = t ? buildOffBorderColor(t) : null;
+    const modeChangeHandler = createModeChangeHandler(
+      piVimSettings.modeChange,
+      (event) => pi.events.emit('pi-vim:mode-change', event),
+    );
+    ctx.ui.setEditorComponent((tui, theme, kb) => {
+      cursorShapeCleanup = enableCursorShapeSupport(tui);
+      requestPromptRender = () => tui.requestRender();
+      options.deckSurface?.setRequestRender(requestPromptRender);
+      const editor = new ModalEditor(tui, theme, kb, {
+        labelColorizers,
+        borderColorizers,
+        borderSync,
+        labelSync,
+        offBorderColor,
+        getPromptRail: () => promptRail.snapshot(),
+        promptRailColorize: (color, text) => (t ? t.fg(color, text) : text),
+        promptRailsEnabled: !deckIntegrated,
+        editorFrameEnabled: !deckIntegrated,
+        externalEditorOnly,
+        deckRenderer:
+          deckIntegrated && options.deckSurface
+            ? (width, modeRail) =>
+                options.deckSurface?.render(width, ctx.ui.theme, modeRail) ?? []
+            : null,
+      });
+      editor.setClipboardMirrorPolicy(clipboardMirrorPolicy.policy);
+      editor.setQuitFn(() => ctx.shutdown());
+      editor.setNotifyFn((message) => ctx.ui.notify(message, 'warning'));
+      promptExternalEditor = new PromptExternalEditor({
+        agentDir: getAgentDir(),
+        cwd: ctx.cwd,
+        editor,
+        mutedBorder: (text) => ctx.ui.theme.fg('dim', text),
+        notifyError: (message) => ctx.ui.notify(message, 'error'),
+      });
+      editor.setExternalEditorFn(() => promptExternalEditor?.open());
+      editor.setModeChangeFn(modeChangeHandler);
+      if (deckIntegrated) {
+        const mode = editor.getMode();
+        pi.events.emit('pi-vim:mode-change', { mode, previousMode: mode });
+      }
+      editor.setExCommandSettings(exCommand.settings);
+      // Resolved at submit time so commands registered or reloaded mid-session
+      // are dispatchable without restarting.
+      editor.setCommandNamesFn(
+        () =>
+          new Set([
+            ...EX_BUILTIN_COMMAND_NAMES,
+            ...pi.getCommands().map((command) => command.name),
+          ]),
+      );
+      return editor;
+    });
+  });
+
+  pi.on('message_end', refreshSessionCost);
+  pi.on('session_compact', refreshSessionCost);
+
+  pi.on('session_shutdown', (event) => {
+    try {
+      promptExternalEditor?.dispose();
+      cursorShapeCleanup?.(event);
+    } finally {
+      stopPromptRail();
+      promptRail.clear();
+      getSessionEntries = null;
+      requestPromptRender = null;
+      options.deckSurface?.setRequestRender(null);
+      cancelModeChangeCommands();
+      promptExternalEditor = null;
+      cursorShapeCleanup = null;
+    }
+  });
+}