@oh-my-pi/pi-tui 18.1.16 → 18.1.18

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [18.1.17] - 2026-09-10
+
+### Added
+
+- Editor history can retain local draft snapshots with their paste expansions and host-owned attachment restoration, without writing them to persistent history ([#11524](https://github.com/can1357/oh-my-pi/pull/11524) by [@camjac251](https://github.com/camjac251)).
+- Added an optional Vim-style modal editing layer to `Editor`, off unless `setVimMode(true)` is called: Insert, Normal, and Visual/Visual-Line with motions, count prefixes, and operators. `j`/`k` keep Vim's desired column, so passing over a shorter line does not collapse it, and `$` sticks to end-of-line. `p`/`P` paste from an internal register; yanks are surfaced to the host through `onYank` so it can route them to the system clipboard.
+- Vim mode now exposes its chrome to hosts: `Editor.vimEnabled`, `Editor.vimPending` (the half-typed command, e.g. `2d`), and `Editor.vimSelectedLines` (Visual selection height). `onVimModeChange` additionally fires when the pending command or selection size changes, not only on mode switches.
+- Vim mode now understands text objects: `iw`/`aw` (and `W`), quotes `i"`/`a'`/`` a` ``, bracket pairs `i(`/`a{`/`i[`/`a<` (nesting-aware and multi-line), and paragraphs `ip`/`ap`. They work under an operator (`diw`, `ca(`) and in Visual mode (`viw`), with counts (`d2aw`). Previously `i` after an operator fell through to Insert mode, so `diw` typed text instead of deleting a word.
+- Vim mode's `c` operator now actually enters Insert mode (`cw`, `cip`, `c` in Visual); it also follows Vim's `cw`-acts-like-`ce` quirk and parks the cursor correctly when the changed range is empty (`ci"` between bare quotes).
+- Added `Terminal.setCursorShape()` (DECSCUSR), restored to the terminal's configured shape on teardown and crash cleanup.
+
+### Changed
+
+- The software cursor now reflects the Vim mode: a reverse-video block in Normal/Visual and an underline in Insert. Both occupy one cell, so layout is unchanged, and non-modal editors keep the reverse-video block they always had.
+
 ## [18.1.15] - 2026-09-08
 
 ### Fixed

package/dist/types/components/editor.d.ts

@@ -1,6 +1,7 @@
 import { type AutocompleteProvider } from "../autocomplete.js";
 import type { SymbolTheme } from "../symbols.js";
 import { type Component, type Focusable } from "../tui.js";
+import { type VimMode } from "../vim.js";
 import { type EditorBorderStyle, type EditorTopBorder } from "./composer/index.js";
 export type { EditorBorderStyle, EditorTopBorder };
 import { type SelectListTheme } from "./select-list.js";
@@ -74,6 +75,11 @@ export declare class Editor implements Component, Focusable {
      *  Width-changing output is allowed on lines without the cursor; it is truncated
      *  to the content width rather than reflowed. Cursor glyphs and inline hints are excluded. */
     decorateText: ((text: string, context: EditorTextDecorationContext) => string) | undefined;
+    /** Called with the selected text when Visual mode yanks, so hosts can reach the system
+     *  clipboard — `packages/tui` deliberately has no clipboard dependency of its own. */
+    onYank?: (text: string) => void;
+    /** Fired when the modal state changes, so hosts can restyle their chrome (border, status). */
+    onVimModeChange?: (mode: VimMode) => void;
     borderColor: (str: string) => string;
     onAutocompleteUpdate?: () => void;
     /** Called after an async text-assist result mutates the document outside an input event, so hosts can schedule a repaint. */
@@ -148,6 +154,24 @@ export declare class Editor implements Component, Focusable {
     setUseTerminalCursor(useTerminalCursor: boolean): void;
     /** Render a dedicated bottom border so terminal-local IME preedit cannot shift editor chrome. */
     setImeSafeCursorLayout(enabled: boolean): void;
+    /** Enable Vim-style modal editing. Toggling always drops back to Insert mode so the editor is
+     *  never left in a state where ordinary typing does nothing. */
+    setVimMode(enabled: boolean): void;
+    /** Current modal state; always `"insert"` when Vim mode is off. */
+    get vimMode(): VimMode;
+    /** True when modal editing is active, regardless of which mode is current. */
+    get vimEnabled(): boolean;
+    /** Half-typed Vim command (`"2d"`, `"g"`), or `""` when nothing is pending. */
+    get vimPending(): string;
+    /** Lines spanned by the active Visual selection; 0 outside Visual modes. */
+    get vimSelectedLines(): number;
+    /**
+     * Whether Escape belongs to the editor right now rather than to the app.
+     *
+     * Hosts bind Escape to interrupt/clear; in Vim mode it first has to mean "leave Insert mode" and
+     * "cancel a half-typed operator". Only a quiet Normal mode gives Escape back to the app.
+     */
+    vimConsumesEscape(): boolean;
     getUseTerminalCursor(): boolean;
     setMaxHeight(maxHeight: number | undefined): void;
     /** Enable/disable the right-border scrollbar. Only shown when content overflows. */
@@ -162,6 +186,12 @@ export declare class Editor implements Component, Focusable {
      * Called after successful submission.
      */
     addToHistory(text: string): void;
+    /** Retain the current draft for local recall only, never persistent history. */
+    rememberDraft(restore?: () => void): void;
+    /** Release the current draft's expansion payloads without touching history. */
+    clearPasteState(): void;
+    /** Restore host-owned draft state before history text triggers onChange. */
+    restoreHistoryState(restore?: () => void): void;
     invalidate(): void;
     render(width: number): readonly string[];
     handleInput(data: string): void;

package/dist/types/mouse.d.ts

@@ -1,11 +1,11 @@
 /**
  * SGR mouse report parsing (`\x1b[<button;col;rowM` / `…m`).
  *
- * Mouse tracking is enabled only while a fullscreen overlay holds the
- * alternate screen (see tui.ts MOUSE_TRACKING_ON), so consumers are
- * fullscreen components hit-testing against their own rendered frame:
- * the frame paints from screen row 0, hence `row`/`col` are exposed
- * 0-based for direct indexing into rendered lines.
+ * Mouse tracking is enabled while a fullscreen overlay holds the alternate
+ * screen (see tui.ts MOUSE_TRACKING_ON), or — opt-in via `tui.mouse` — on the
+ * normal buffer whenever no overlay is visible. Consumers hit-test
+ * against their own rendered frame: the frame paints from screen row 0, hence
+ * `row`/`col` are exposed 0-based for direct indexing into rendered lines.
  */
 /** A decoded SGR mouse report. */
 export interface SgrMouseEvent {

package/dist/types/terminal.d.ts

@@ -106,6 +106,13 @@ export type TerminalAppearanceRequestToken = number;
  * set, 4 permanently reset) when the terminal answered DECRQM.
  */
 export type PrivateModeReportHandler = (mode: number, supported: boolean, confirmed?: boolean, status?: number) => void;
+/**
+ * Cursor shapes addressable via DECSCUSR (`CSI <n> SP q`). `"default"` (0) hands the shape back to
+ * the terminal's own configuration, which is what teardown restores rather than guessing a shape
+ * the user never chose.
+ */
+export type CursorShape = "default" | "block" | "underline" | "bar";
+export declare const CURSOR_SHAPE_CODES: Record<CursorShape, number>;
 export interface Terminal {
     start(onInput: (data: string) => void, onResize: () => void, onDisconnect?: () => void, options?: TerminalStartOptions): void;
     /**
@@ -142,6 +149,7 @@ export interface Terminal {
     moveBy(lines: number): void;
     hideCursor(force?: boolean): void;
     showCursor(force?: boolean): void;
+    setCursorShape?(shape: CursorShape): void;
     clearLine(): void;
     clearFromCursor(): void;
     clearScreen(): void;
@@ -243,6 +251,12 @@ export declare class ProcessTerminal implements Terminal {
     moveBy(lines: number): void;
     hideCursor(force?: boolean): void;
     showCursor(force?: boolean): void;
+    /**
+     * Set the hardware cursor shape (DECSCUSR). Deduped against the last shape written so a
+     * per-keystroke mode indicator does not add a sequence to every frame; {@link stop} restores
+     * `"default"` so the user's own cursor configuration survives exit.
+     */
+    setCursorShape(shape: CursorShape): void;
     clearLine(): void;
     clearFromCursor(): void;
     clearScreen(): void;

package/dist/types/tui.d.ts

@@ -334,6 +334,28 @@ export declare class TUI extends Container {
     hideOverlay(): void;
     /** Check if there are any visible overlays */
     hasOverlay(): boolean;
+    /**
+     * Mutable normal-buffer viewport from the last provider frame: screen row
+     * where it begins plus its row count. Inline click targets are indexed
+     * into this window (`screenRow - top`). Empty while the alt screen owns
+     * the display, while a resize transaction is settling, and while a Ghostty
+     * image paint is deferred — the painted rows predate the latest spans in
+     * all three cases, so hits would map to unrelated old rows.
+     * The origin is in composer rows: a replay paint replaces leading composer
+     * blanks with history rows and prepends blanks for a short viewport, so
+     * the painted top is backed out by that net pad.
+     */
+    getMutableViewport(): {
+        top: number;
+        length: number;
+    };
+    /**
+     * Probe for opt-in normal-buffer click capture. The provider is read every
+     * frame; while it returns true (and no fullscreen overlay owns the
+     * display) the terminal reports button clicks as SGR events for inline
+     * click targets. Native text selection becomes Shift+drag while on.
+     */
+    setInlineMouseTrackingProvider(provider: (() => boolean) | undefined): void;
     invalidate(): void;
     start(options?: TUIStartOptions): void;
     /**

package/dist/types/vim.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Modal editing state machine for {@link Editor}.
+ *
+ * Deliberately a *pure* state machine: it reads a snapshot of the buffer and returns the edits it
+ * wants applied, so motions can be unit-tested without a terminal and the editor keeps sole
+ * ownership of undo, atomic placeholder tokens, the kill ring, and `onChange`.
+ *
+ * This is a usable subset of Vim, not a reimplementation of it (see issue #3299): Normal and Visual
+ * modes, the common motions, and operators built from those motions.
+ */
+export type VimMode = "insert" | "normal" | "visual" | "visual-line";
+export type VimOperator = "d" | "y" | "c";
+export interface VimPosition {
+    line: number;
+    col: number;
+}
+/** Read-only view of the editor buffer that motions resolve against. */
+export interface VimBuffer {
+    readonly lines: readonly string[];
+    readonly cursorLine: number;
+    readonly cursorCol: number;
+}
+/**
+ * An edit the editor should apply. `to` is always an *exclusive* end offset, so ranges compose the
+ * same way regardless of whether the originating motion was inclusive (`e`) or exclusive (`w`).
+ */
+export type VimCommand = {
+    kind: "move";
+    to: VimPosition;
+} | {
+    kind: "mode";
+    mode: VimMode;
+} | {
+    kind: "yank";
+    from: VimPosition;
+    to: VimPosition;
+    linewise: boolean;
+} | {
+    kind: "delete";
+    from: VimPosition;
+    to: VimPosition;
+    linewise: boolean;
+    insert: boolean;
+} | {
+    kind: "openLine";
+    below: boolean;
+} | {
+    kind: "paste";
+    after: boolean;
+    count: number;
+} | {
+    kind: "undo";
+};
+/** Start offset of the grapheme after `col`, clamped to `text.length`. */
+export declare function nextGraphemeStart(text: string, col: number): number;
+/** Start offset of the grapheme before `col`, clamped to 0. */
+export declare function prevGraphemeStart(text: string, col: number): number;
+/** Offset of the final grapheme — where a Normal-mode cursor rests on a non-empty line. */
+export declare function lastGraphemeStart(text: string): number;
+export declare class VimState {
+    #private;
+    mode: VimMode;
+    /** Fixed end of a Visual selection; the cursor is the moving end. */
+    anchor: VimPosition | null;
+    /** True while a count, operator, `g`, or text-object prefix is half-typed — Escape cancels it. */
+    get pending(): boolean;
+    /**
+     * The half-typed command as Vim would echo it (`"2"`, `"d"`, `"2d"`, `"di"`) — empty when
+     * nothing is pending. Hosts render this next to the mode so a partially entered operator is
+     * visible instead of silently swallowing the next keystroke.
+     */
+    get pendingText(): string;
+    get visual(): boolean;
+    reset(): void;
+    /**
+     * Handle one key. `key` is either the literal `"escape"` or a single grapheme; the editor
+     * normalizes arrow/Home/End keys onto their Vim equivalents before calling.
+     *
+     * Returns the commands to apply, or `null` when the key is not ours — the editor then falls
+     * through to its regular handling (and, for Escape in Normal mode, to the app's interrupt).
+     */
+    handleKey(key: string, buf: VimBuffer): VimCommand[] | null;
+}
+/**
+ * Normalized, end-exclusive span covered by a Visual selection.
+ *
+ * Charwise selections include the grapheme under the cursor (Vim semantics); linewise selections
+ * span whole lines, with `to.col` at the end of the last line so the caller can decide whether the
+ * trailing newline goes too.
+ */
+export declare function visualRange(buf: VimBuffer, anchor: VimPosition, linewise: boolean): {
+    from: VimPosition;
+    to: VimPosition;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "18.1.16",
+	"version": "18.1.18",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -37,8 +37,8 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.1.16",
-		"@oh-my-pi/pi-utils": "18.1.16"
+		"@oh-my-pi/pi-natives": "18.1.18",
+		"@oh-my-pi/pi-utils": "18.1.18"
 	},
 	"devDependencies": {
 		"kitty-vt-wasm": "^0.2.0"