@visual-z/xeno 0.1.0

package/src/tui/editor.ts

@@ -0,0 +1,893 @@
+/**
+ * Legacy pure editor contracts plus the live Pi-owned Editor adapter below.
+ * The pure reducer is retained for compatibility tests, not live dispatch.
+ * Its state is a pure applyKey(state, key) -- no terminal,
+ * no clock -- so "left twice then backspace across a CJK boundary" is a
+ * unit test rather than a hope.
+ *
+ * Cursor is a UTF-16 offset into `text` so slice() can address it, but
+ * every motion step is one display cluster (a width>0 base plus trailing
+ * combining marks, or a newline). Counting `.length` as columns would
+ * stop the cursor on the right half of 中, and the terminal would draw it
+ * there.
+ *
+ * applyKey does not take a width. Soft wrap is a render of the same
+ * buffer; up/down walk hard lines (Shift+Enter). Visual-row motion needs
+ * the terminal width, which the next card can store on the caller.
+ */
+
+import { Editor as PiEditor, type TUI } from "../vendor/pi-tui/index.ts";
+import { getKeybindings, setKeybindings, type KeybindingsManager } from "../vendor/pi-tui/keybindings.ts";
+import type { AutocompleteProvider } from "../vendor/pi-tui/autocomplete.ts";
+import { encodeKey } from "./input.ts";
+import { IDENTITY, PLAIN_ATTRS, paint, type Style } from "./style.ts";
+import { completePath, pathTokenAtCursor, type PathToken } from "./complete.ts";
+import { assertNever } from "./exhaustive.ts";
+import { identityEditorTheme, stubTui } from "./host.ts";
+import type { Key, KeyMods } from "./keys.ts";
+import {
+  applySelectKey,
+  createSelect,
+  renderSelect,
+  type SelectState,
+} from "./select.ts";
+import type { Component } from "./text.ts";
+import { displayWidth } from "./width.ts";
+
+/**
+ * Cap on prompt history. Assumed, not measured: matches pi-tui's cap.
+ * Too small and a long session cannot recall an earlier prompt; the
+ * caller can pass a different limit.
+ */
+export const DEFAULT_HISTORY_LIMIT = 100;
+
+/**
+ * Cap on undo snapshots. Assumed, not measured: matches the history cap.
+ * Too small and a long edit cannot be walked back as groups.
+ */
+const UNDO_LIMIT = 100;
+
+/**
+ * Cap on kill-ring entries. Assumed, not measured: Emacs default is 30;
+ * 16 keeps a JSON-roundtrip of EditorState cheap. Too small and an
+ * earlier kill cannot be yanked.
+ */
+const KILL_RING_LIMIT = 16;
+
+export type EditGroup = "insert" | "delete" | "move" | "yank" | null;
+
+export interface EditorSnapshot {
+  readonly text: string;
+  readonly cursor: number;
+}
+
+export interface CreateEditorOptions {
+  readonly text?: string;
+  /** Oldest-to-newest submitted prompts. Stored newest-first internally. */
+  readonly history?: readonly string[];
+  readonly historyLimit?: number;
+  /**
+   * Display-only. applyKey still stores plaintext so submit can return the
+   * real value; renderEditor paints a mask so a pasted secret never reaches
+   * the live region (and therefore never scrollback).
+   */
+  readonly secret?: boolean;
+  /** Injected directory listing. applyKey never reads the disk. */
+  readonly pathEntries?: readonly string[];
+  /**
+   * Vendor Editor reads tui.terminal.rows for the 30%-of-height cap.
+   * Unit tests omit this and get a silent stub so render() does not write.
+   */
+  readonly tui?: TUI;
+}
+
+export interface EditorState {
+  readonly text: string;
+  /**
+   * UTF-16 offset into `text`, always on a cluster boundary. Not a column
+   * count -- 中 is one unit here and two columns in displayWidth.
+   */
+  readonly cursor: number;
+  /** Sticky display column for vertical motion, like a terminal's curswant. */
+  readonly preferredColumn: number;
+  readonly history: readonly string[];
+  readonly historyLimit: number;
+  /** -1 = live buffer; 0 = newest history entry. */
+  readonly historyIndex: number;
+  readonly draft: string | null;
+  readonly submitted: string | null;
+  readonly secret: boolean;
+  readonly pathEntries: readonly string[];
+  readonly completion: SelectState | null;
+  readonly undoStack: readonly EditorSnapshot[];
+  readonly redoStack: readonly EditorSnapshot[];
+  readonly killRing: readonly string[];
+  readonly lastGroup: EditGroup;
+}
+
+export interface CursorView {
+  readonly row: number;
+  readonly col: number;
+}
+
+export function createEditor(opts: CreateEditorOptions = {}): EditorState {
+  const text = opts.text ?? "";
+  const cursor = text.length;
+  return {
+    text,
+    cursor,
+    preferredColumn: columnOf(text, cursor),
+    history: [...(opts.history ?? [])].reverse(),
+    historyLimit: opts.historyLimit ?? DEFAULT_HISTORY_LIMIT,
+    historyIndex: -1,
+    draft: null,
+    submitted: null,
+    secret: opts.secret ?? false,
+    pathEntries: opts.pathEntries ?? [],
+    completion: null,
+    undoStack: [],
+    redoStack: [],
+    killRing: [],
+    lastGroup: null,
+  };
+}
+
+export function cursorDisplayColumn(state: EditorState): number {
+  const { lines, line, offset } = locate(state.text, state.cursor);
+  return columnAt(lines[line]!, offset);
+}
+
+/**
+ * Map the UTF-16 cursor onto wrapped rows. Width is a render concern --
+ * applyKey never sees it -- so this is the thing that has to stay in
+ * lockstep with renderEditor or a wrapped CJK line puts the hardware
+ * cursor on the wrong glyph.
+ */
+export function cursorView(state: EditorState, width: number): CursorView {
+  const { lines, line, offset } = locate(state.text, state.cursor);
+  let row = 0;
+  for (let i = 0; i < line; i++) {
+    row += wrapLogicalLine(lines[i]!, width).length;
+  }
+  const vis = wrapLogicalLine(lines[line]!, width);
+  for (let i = 0; i < vis.length; i++) {
+    const chunk = vis[i]!;
+    const last = i === vis.length - 1;
+    if (offset < chunk.end || last) {
+      return { row: row + i, col: columnAt(chunk.text, offset - chunk.start) };
+    }
+  }
+  const last = vis[vis.length - 1]!;
+  return { row: row + vis.length - 1, col: columnAt(last.text, last.text.length) };
+}
+
+/**
+ * Dispatch a namespaced editor action. Key lookup lives above tui (core
+ * keymap); this only applies the motion so a rebound chord reaches the
+ * same function the default binding did.
+ */
+export function applyEditorAction(state: EditorState, action: string): EditorState {
+  switch (action) {
+    case "editor.cursorLeft":
+      return moveHorizontal(state, -1);
+    case "editor.cursorRight":
+      return moveHorizontal(state, 1);
+    case "editor.cursorWordLeft":
+      return moveWord(state, -1);
+    case "editor.cursorWordRight":
+      return moveWord(state, 1);
+    case "editor.cursorLineStart":
+      return moveLineStart(state);
+    case "editor.cursorLineEnd":
+      return moveLineEnd(state);
+    case "editor.cursorUp":
+      return moveVertical(state, -1);
+    case "editor.cursorDown":
+      return moveVertical(state, 1);
+    case "editor.deleteCharBackward":
+      return deleteBackward(state);
+    case "editor.deleteCharForward":
+      return deleteForward(state);
+    case "editor.deleteWordBackward":
+      return deleteWordBackward(state);
+    case "editor.deleteWordForward":
+      return deleteWordForward(state);
+    case "editor.deleteToLineStart":
+      return deleteToLineStart(state);
+    case "editor.deleteToLineEnd":
+      return deleteToLineEnd(state);
+    case "editor.submit":
+      return submit(state);
+    case "editor.newLine":
+      return insert(state, "\n");
+    case "editor.undo":
+      return undo(state);
+    case "editor.redo":
+      return redo(state);
+    case "editor.yank":
+      return yank(state);
+    case "editor.complete":
+      return applyTab(state);
+    default:
+      return state;
+  }
+}
+
+export function applyKey(state: EditorState, key: Key): EditorState {
+  if (state.completion !== null) {
+    const handled = applyCompletionKey(state, key);
+    if (handled !== null) return handled;
+    state = { ...state, completion: null };
+  }
+  switch (key.type) {
+    case "char":
+      return insert(state, key.grapheme);
+    case "enter":
+      return key.shift ? insert(state, "\n") : submit(state);
+    case "backspace":
+      return deleteBackward(state);
+    case "delete":
+      return deleteForward(state);
+    case "left":
+      return isWordMotion(key.mods) ? moveWord(state, -1) : moveHorizontal(state, -1);
+    case "right":
+      return isWordMotion(key.mods) ? moveWord(state, 1) : moveHorizontal(state, 1);
+    case "up":
+      return moveVertical(state, -1);
+    case "down":
+      return moveVertical(state, 1);
+    case "home":
+      return moveLineStart(state);
+    case "end":
+      return moveLineEnd(state);
+    case "ctrl":
+      return applyCtrl(state, key.key, key.shift === true);
+    case "alt":
+      return applyAlt(state, key.key);
+    case "tab":
+      return key.shift === true ? clearSubmitted(state) : applyTab(state);
+    case "escape":
+    case "pageup":
+    case "pagedown":
+      return clearSubmitted(state);
+    default:
+      return assertNever(key, "applyKey");
+  }
+}
+
+function applyCtrl(state: EditorState, key: string, shift: boolean): EditorState {
+  switch (key) {
+    case "a":
+      return moveLineStart(state);
+    case "e":
+      return moveLineEnd(state);
+    case "u":
+      return deleteToLineStart(state);
+    case "k":
+      return deleteToLineEnd(state);
+    case "w":
+      return deleteWordBackward(state);
+    case "z":
+      return shift ? redo(state) : undo(state);
+    case "_":
+      return undo(state);
+    case "y":
+      return yank(state);
+    default:
+      return clearSubmitted(state);
+  }
+}
+
+/**
+ * Word left/right for the Emacs letters. Real terminals send
+ * CSI 1;3D / CSI 1;5C (handled on `left`/`right` via mods); Alt+b /
+ * Alt+f still arrive as `{ type: "alt", key: "b"|"f" }`. The
+ * synthetic `{ type: "alt", key: "left"|"right" }` names stay bound
+ * because existing tests construct them.
+ */
+function applyAlt(state: EditorState, key: string): EditorState {
+  const k = key.length === 1 ? key.toLowerCase() : key;
+  if (k === "left" || k === "b") return moveWord(state, -1);
+  if (k === "right" || k === "f") return moveWord(state, 1);
+  if (k === "d") return deleteWordForward(state);
+  if (k === "backspace" || k === "\x7f") return deleteWordBackward(state);
+  return clearSubmitted(state);
+}
+
+function isWordMotion(mods: KeyMods | undefined): boolean {
+  return mods?.alt === true || mods?.ctrl === true;
+}
+
+function clearSubmitted(state: EditorState): EditorState {
+  return state.submitted === null ? state : { ...state, submitted: null };
+}
+
+function snapshotOf(state: EditorState): EditorSnapshot {
+  return { text: state.text, cursor: state.cursor };
+}
+
+function beginGroup(state: EditorState, group: Exclude<EditGroup, "move" | null>): EditorState {
+  const coalesce = (group === "insert" || group === "delete") && state.lastGroup === group;
+  if (coalesce) return state;
+  return {
+    ...state,
+    undoStack: [...state.undoStack, snapshotOf(state)].slice(-UNDO_LIMIT),
+    redoStack: [],
+    lastGroup: group,
+  };
+}
+
+function commit(
+  state: EditorState,
+  text: string,
+  cursor: number,
+  group: Exclude<EditGroup, "move" | null>,
+): EditorState {
+  const base = beginGroup(state, group);
+  const clamped = Math.max(0, Math.min(cursor, text.length));
+  return {
+    ...base,
+    text,
+    cursor: clamped,
+    preferredColumn: columnOf(text, clamped),
+    submitted: null,
+    completion: null,
+  };
+}
+
+function kill(state: EditorState, text: string, cursor: number, killed: string): EditorState {
+  if (killed.length === 0) return clearSubmitted(state);
+  const next = commit(state, text, cursor, "delete");
+  return { ...next, killRing: [...next.killRing, killed].slice(-KILL_RING_LIMIT) };
+}
+
+function moveTo(state: EditorState, cursor: number): EditorState {
+  const clamped = Math.max(0, Math.min(cursor, state.text.length));
+  if (clamped === state.cursor && state.submitted === null && state.lastGroup === "move") {
+    return state;
+  }
+  return {
+    ...clearSubmitted(state),
+    cursor: clamped,
+    preferredColumn: columnOf(state.text, clamped),
+    lastGroup: "move",
+  };
+}
+
+function undo(state: EditorState): EditorState {
+  const prev = state.undoStack[state.undoStack.length - 1];
+  if (prev === undefined) return clearSubmitted(state);
+  return {
+    ...clearSubmitted(state),
+    text: prev.text,
+    cursor: prev.cursor,
+    preferredColumn: columnOf(prev.text, prev.cursor),
+    undoStack: state.undoStack.slice(0, -1),
+    redoStack: [...state.redoStack, snapshotOf(state)],
+    lastGroup: null,
+    completion: null,
+  };
+}
+
+function redo(state: EditorState): EditorState {
+  const next = state.redoStack[state.redoStack.length - 1];
+  if (next === undefined) return clearSubmitted(state);
+  return {
+    ...clearSubmitted(state),
+    text: next.text,
+    cursor: next.cursor,
+    preferredColumn: columnOf(next.text, next.cursor),
+    undoStack: [...state.undoStack, snapshotOf(state)].slice(-UNDO_LIMIT),
+    redoStack: state.redoStack.slice(0, -1),
+    lastGroup: null,
+    completion: null,
+  };
+}
+
+function yank(state: EditorState): EditorState {
+  const piece = state.killRing[state.killRing.length - 1];
+  if (piece === undefined) return clearSubmitted(state);
+  const text = state.text.slice(0, state.cursor) + piece + state.text.slice(state.cursor);
+  return commit(state, text, state.cursor + piece.length, "yank");
+}
+
+export function applyExternalText(state: EditorState, text: string): EditorState {
+  return commit(state, text, text.length, "yank");
+}
+
+function applyTab(state: EditorState): EditorState {
+  const token = pathTokenAtCursor(state.text, state.cursor);
+  if (token === null) return clearSubmitted(state);
+  const result = completePath(token.prefix, state.pathEntries);
+  if (result.candidates.length === 0) return clearSubmitted(state);
+  if (result.candidates.length === 1) {
+    return replaceToken(state, token, result.completed);
+  }
+  let next = state;
+  if (result.completed.length > token.prefix.length) {
+    next = replaceToken(state, token, result.completed);
+  }
+  const items = result.candidates.map((value) => ({ value, label: value }));
+  return { ...next, completion: createSelect(items) };
+}
+
+function replaceToken(state: EditorState, token: PathToken, replacement: string): EditorState {
+  const text = state.text.slice(0, token.start) + replacement + state.text.slice(token.end);
+  return commit(state, text, token.start + replacement.length, "yank");
+}
+
+function applyCompletionKey(state: EditorState, key: Key): EditorState | null {
+  const list = state.completion;
+  if (list === null) return null;
+  if (key.type === "up" || key.type === "down") {
+    return { ...state, completion: applySelectKey(list, key) };
+  }
+  if (key.type === "enter" || (key.type === "tab" && key.shift !== true)) {
+    return confirmCompletion(state);
+  }
+  if (key.type === "escape") {
+    return { ...state, completion: null };
+  }
+  return null;
+}
+
+function confirmCompletion(state: EditorState): EditorState {
+  const list = state.completion;
+  if (list === null) return state;
+  const item = list.items[list.selected];
+  const closed = { ...state, completion: null };
+  if (item === undefined) return closed;
+  const token = pathTokenAtCursor(closed.text, closed.cursor);
+  if (token === null) return closed;
+  return replaceToken(closed, token, item.value);
+}
+
+function insert(state: EditorState, grapheme: string): EditorState {
+  const text = state.text.slice(0, state.cursor) + grapheme + state.text.slice(state.cursor);
+  // grapheme.length is UTF-16 units of the inserted cluster, not columns.
+  return commit(state, text, state.cursor + grapheme.length, "insert");
+}
+
+function submit(state: EditorState): EditorState {
+  if (state.text.trim() === "") return { ...state, submitted: null };
+  const entry = state.text;
+  // A secret must not land in prompt history: recalling it later would
+  // paint the plaintext once secret mode is off.
+  const history = state.secret
+    ? state.history
+    : [entry, ...state.history.filter((h) => h !== entry)].slice(0, state.historyLimit);
+  return {
+    text: "",
+    cursor: 0,
+    preferredColumn: 0,
+    history,
+    historyLimit: state.historyLimit,
+    historyIndex: -1,
+    draft: null,
+    submitted: entry,
+    secret: state.secret,
+    pathEntries: state.pathEntries,
+    completion: null,
+    undoStack: [],
+    redoStack: [],
+    killRing: state.killRing,
+    lastGroup: null,
+  };
+}
+
+function deleteBackward(state: EditorState): EditorState {
+  if (state.cursor <= 0) return clearSubmitted(state);
+  const from = prevClusterStart(state.text, state.cursor);
+  const text = state.text.slice(0, from) + state.text.slice(state.cursor);
+  return commit(state, text, from, "delete");
+}
+
+function deleteForward(state: EditorState): EditorState {
+  if (state.cursor >= state.text.length) return clearSubmitted(state);
+  const to = nextClusterEnd(state.text, state.cursor);
+  const text = state.text.slice(0, state.cursor) + state.text.slice(to);
+  return commit(state, text, state.cursor, "delete");
+}
+
+function moveHorizontal(state: EditorState, dir: -1 | 1): EditorState {
+  const cursor = dir < 0
+    ? prevClusterStart(state.text, state.cursor)
+    : nextClusterEnd(state.text, state.cursor);
+  return moveTo(state, cursor);
+}
+
+function moveVertical(state: EditorState, dir: -1 | 1): EditorState {
+  const { lines, line } = locate(state.text, state.cursor);
+  const preferred = state.preferredColumn;
+  if (dir < 0 && line === 0) return historyPrev(state);
+  if (dir > 0 && line === lines.length - 1) return historyNext(state);
+
+  const targetLine = line + dir;
+  const target = lines[targetLine]!;
+  const newOffset = cursorAtColumn(target, preferred);
+  const cursor = indexOfLine(lines, targetLine, newOffset);
+  return { ...clearSubmitted(state), cursor, preferredColumn: preferred, lastGroup: "move" };
+}
+
+function moveLineStart(state: EditorState): EditorState {
+  const { lines, line } = locate(state.text, state.cursor);
+  return moveTo(state, indexOfLine(lines, line, 0));
+}
+
+function moveLineEnd(state: EditorState): EditorState {
+  const { lines, line } = locate(state.text, state.cursor);
+  const row = lines[line]!;
+  return moveTo(state, indexOfLine(lines, line, row.length));
+}
+
+function deleteToLineStart(state: EditorState): EditorState {
+  const { lines, line, offset } = locate(state.text, state.cursor);
+  const row = lines[line]!;
+  const killed = row.slice(0, offset);
+  const next = [...lines];
+  next[line] = row.slice(offset);
+  const text = next.join("\n");
+  return kill(state, text, indexOfLine(next, line, 0), killed);
+}
+
+function deleteToLineEnd(state: EditorState): EditorState {
+  const { lines, line, offset } = locate(state.text, state.cursor);
+  const row = lines[line]!;
+  const killed = row.slice(offset);
+  const next = [...lines];
+  next[line] = row.slice(0, offset);
+  return kill(state, next.join("\n"), state.cursor, killed);
+}
+
+function deleteWordBackward(state: EditorState): EditorState {
+  const to = wordOffset(state, -1);
+  if (to >= state.cursor) return clearSubmitted(state);
+  const killed = state.text.slice(to, state.cursor);
+  const text = state.text.slice(0, to) + state.text.slice(state.cursor);
+  return kill(state, text, to, killed);
+}
+
+function deleteWordForward(state: EditorState): EditorState {
+  const to = wordOffset(state, 1);
+  if (to <= state.cursor) return clearSubmitted(state);
+  const killed = state.text.slice(state.cursor, to);
+  const text = state.text.slice(0, state.cursor) + state.text.slice(to);
+  return kill(state, text, state.cursor, killed);
+}
+
+function moveWord(state: EditorState, dir: -1 | 1): EditorState {
+  return moveTo(state, wordOffset(state, dir));
+}
+
+function historyPrev(state: EditorState): EditorState {
+  if (state.secret) return clearSubmitted(state);
+  if (state.history.length === 0) return clearSubmitted(state);
+  const next = state.historyIndex === -1 ? 0 : state.historyIndex + 1;
+  if (next >= state.history.length) return clearSubmitted(state);
+  const draft = state.historyIndex === -1 ? state.text : state.draft;
+  const text = state.history[next]!;
+  // Cursor at start so another up stays on the first hard line and
+  // continues walking history instead of moving inside a multiline entry.
+  const base = commit(clearSubmitted(state), text, 0, "yank");
+  return { ...base, preferredColumn: 0, historyIndex: next, draft };
+}
+
+function historyNext(state: EditorState): EditorState {
+  if (state.secret) return clearSubmitted(state);
+  if (state.historyIndex === -1) return clearSubmitted(state);
+  const next = state.historyIndex - 1;
+  if (next < 0) {
+    const text = state.draft ?? "";
+    const base = commit(
+      { ...state, historyIndex: -1, draft: null, submitted: null },
+      text,
+      text.length,
+      "yank",
+    );
+    return base;
+  }
+  const text = state.history[next]!;
+  // Cursor at end so another down stays on the last hard line.
+  return {
+    ...commit({ ...state, submitted: null }, text, text.length, "yank"),
+    historyIndex: next,
+  };
+}
+
+function columnOf(text: string, cursor: number): number {
+  const { lines, line, offset } = locate(text, cursor);
+  return columnAt(lines[line]!, offset);
+}
+
+interface Location {
+  readonly lines: string[];
+  readonly line: number;
+  readonly offset: number;
+}
+
+function locate(text: string, cursor: number): Location {
+  const lines = text.split("\n");
+  let rest = Math.max(0, Math.min(cursor, text.length));
+  for (let line = 0; line < lines.length; line++) {
+    const len = lines[line]!.length;
+    if (rest <= len) return { lines, line, offset: rest };
+    rest -= len + 1;
+  }
+  const line = lines.length - 1;
+  return { lines, line, offset: lines[line]!.length };
+}
+
+function indexOfLine(lines: readonly string[], line: number, offset: number): number {
+  let i = 0;
+  for (let n = 0; n < line; n++) i += lines[n]!.length + 1;
+  return i + offset;
+}
+
+function columnAt(line: string, offset: number): number {
+  return displayWidth(line.slice(0, offset));
+}
+
+function cursorAtColumn(line: string, target: number): number {
+  let col = 0;
+  let i = 0;
+  for (const ch of line) {
+    const w = displayWidth(ch);
+    if (w > 0 && col + w > target) break;
+    col += w;
+    i += ch.length;
+  }
+  return i;
+}
+
+/**
+ * A newline is width 0 in displayWidth (it is a Cc) but it is a hard
+ * break, not a combining mark. Treating it as combining would let left
+ * skip past a whole line-break as if it were an accent.
+ */
+function isClusterBase(ch: string): boolean {
+  return ch === "\n" || displayWidth(ch) > 0;
+}
+
+function prevClusterStart(text: string, cursor: number): number {
+  if (cursor <= 0) return 0;
+  const chars = [...text.slice(0, cursor)];
+  while (chars.length > 0 && !isClusterBase(chars[chars.length - 1]!)) chars.pop();
+  if (chars.length > 0) chars.pop();
+  let n = 0;
+  for (const ch of chars) n += ch.length;
+  return n;
+}
+
+function nextClusterEnd(text: string, cursor: number): number {
+  if (cursor >= text.length) return text.length;
+  const chars = [...text.slice(cursor)];
+  if (chars.length === 0) return text.length;
+  let consumed = chars[0]!.length;
+  if (isClusterBase(chars[0]!)) {
+    for (let i = 1; i < chars.length; i++) {
+      const ch = chars[i]!;
+      if (isClusterBase(ch)) break;
+      consumed += ch.length;
+    }
+  }
+  return cursor + consumed;
+}
+
+function isAsciiWordChar(ch: string): boolean {
+  return /[A-Za-z0-9_]/.test(ch);
+}
+
+/**
+ * Word motion stays on the current hard line. Crossing a newline is a
+ * character motion; mixing the two made Ctrl+W at column 0 eat the
+ * previous line's last word, which is not what the bindings say.
+ */
+function wordOffset(state: EditorState, dir: -1 | 1): number {
+  const { lines, line, offset } = locate(state.text, state.cursor);
+  const row = lines[line]!;
+  const chars = [...row];
+  let i = 0;
+  let units = 0;
+  while (units < offset && i < chars.length) {
+    units += chars[i]!.length;
+    i++;
+  }
+
+  if (dir < 0) {
+    while (i > 0 && !isAsciiWordChar(chars[i - 1]!)) i--;
+    while (i > 0 && isAsciiWordChar(chars[i - 1]!)) i--;
+  } else {
+    while (i < chars.length && !isAsciiWordChar(chars[i]!)) i++;
+    while (i < chars.length && isAsciiWordChar(chars[i]!)) i++;
+  }
+
+  let newOffset = 0;
+  for (let j = 0; j < i; j++) newOffset += chars[j]!.length;
+  return indexOfLine(lines, line, newOffset);
+}
+
+interface VisualLine {
+  readonly text: string;
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * Same wrap rule as Text in text.ts (kept local: wrapLine is not part of
+ * the kernel's public surface and this card cannot change text.ts). A
+ * CJK character that would overflow starts a new line instead of being
+ * split, because a terminal cell cannot hold half of it.
+ */
+function wrapLogicalLine(s: string, width: number): VisualLine[] {
+  if (width <= 0) return [{ text: s, start: 0, end: s.length }];
+  if (s.length === 0) return [{ text: "", start: 0, end: 0 }];
+  const lines: VisualLine[] = [];
+  let start = 0;
+  let current = "";
+  let currentW = 0;
+  let i = 0;
+  for (const ch of s) {
+    const w = displayWidth(ch);
+    if (w > 0 && currentW + w > width && current.length > 0) {
+      lines.push({ text: current, start, end: i });
+      start = i;
+      current = ch;
+      currentW = w;
+    } else {
+      current += ch;
+      currentW += w;
+    }
+    i += ch.length;
+  }
+  lines.push({ text: current, start, end: i });
+  return lines;
+}
+
+export function renderEditor(state: EditorState, width: number): string[] {
+  const source = state.secret ? maskSecret(state.text) : state.text;
+  const out: string[] = [];
+  for (const hard of source.split("\n")) {
+    for (const vis of wrapLogicalLine(hard, width)) out.push(vis.text);
+  }
+  if (out.length === 0) out.push("");
+  if (state.completion !== null) {
+    out.push(...renderSelect(state.completion, width));
+  }
+  return out;
+}
+
+/** One mask cell per code point; newlines stay so wrap still matches. */
+function maskSecret(text: string): string {
+  let out = "";
+  for (const ch of text) out += ch === "\n" ? "\n" : "*";
+  return out;
+}
+
+export class Editor implements Component {
+  private secret: boolean;
+  private submitted: string | null = null;
+  private history: string[];
+  private readonly historyLimit: number;
+  private provider: AutocompleteProvider | undefined;
+  bindings: KeybindingsManager | undefined;
+  onInput: ((data: string) => void) | undefined;
+  private style: Style = IDENTITY;
+  /**
+   * Pi paints a horizontal rule above and below the buffer. Colour tracks
+   * the thinking level so a glance at the frame says which budget the next
+   * turn will spend (pi's behaviour). Identity until the Tui sets it.
+   */
+  borderColor: (s: string) => string = (s) => s;
+  readonly host: TUI;
+  private pi: PiEditor;
+
+  constructor(opts: CreateEditorOptions = {}) {
+    this.secret = opts.secret ?? false;
+    this.history = [...(opts.history ?? [])].reverse();
+    this.historyLimit = opts.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+    this.host = opts.tui ?? stubTui();
+    this.pi = this.createPi();
+    this.pi.setText(opts.text ?? "");
+  }
+
+  private createPi(): PiEditor {
+    const theme = identityEditorTheme();
+    const pi = new PiEditor(this.host, {
+      ...theme,
+      borderColor: (s) => this.borderColor(s),
+      selectList: {
+        selectedPrefix: (s) => paint(s, { ...PLAIN_ATTRS, selected: true }, this.style),
+        selectedText: (s) => paint(s, { ...PLAIN_ATTRS, selected: true }, this.style),
+        description: (s) => paint(s, { ...PLAIN_ATTRS, dim: true }, this.style),
+        scrollInfo: (s) => paint(s, { ...PLAIN_ATTRS, dim: true }, this.style),
+        noMatch: (s) => paint(s, { ...PLAIN_ATTRS, dim: true }, this.style),
+      },
+    });
+    if (!this.secret) {
+      for (const text of [...this.history].reverse()) pi.addToHistory(text);
+      if (this.provider) pi.setAutocompleteProvider(this.provider);
+    }
+    pi.onSubmit = (text) => {
+      this.submitted = text;
+      if (!this.secret && text.trim().length > 0) {
+        pi.addToHistory(text);
+        if (this.history[0] !== text) this.history.unshift(text);
+        this.history = this.history.slice(0, this.historyLimit);
+      }
+    };
+    return pi;
+  }
+
+  get focused(): boolean { return this.pi.focused; }
+  set focused(value: boolean) { this.pi.focused = value; }
+  setStyle(style: Style): void { this.style = style; }
+
+  handleInput(data: string): void {
+    if (this.onInput) this.onInput(data);
+    else this.acceptInput(data);
+  }
+
+  acceptInput(data: string): EditorState {
+    this.submitted = null;
+    const previous = getKeybindings();
+    if (this.bindings) setKeybindings(this.bindings);
+    try { this.pi.handleInput(data); }
+    finally { setKeybindings(previous); }
+    return this.state;
+  }
+
+  get autocompleteVisible(): boolean { return this.pi.isShowingAutocomplete(); }
+
+  setAutocompleteProvider(provider: AutocompleteProvider): void {
+    this.provider = provider;
+    if (!this.secret) this.pi.setAutocompleteProvider(provider);
+  }
+
+  invalidate(): void {
+    this.pi.invalidate();
+  }
+
+  get state(): EditorState {
+    const text = this.pi.getExpandedText();
+    const pos = this.pi.getCursor();
+    const cursor = this.pi.getLines().slice(0, pos.line).reduce((n, line) => n + line.length + 1, 0) + pos.col;
+    return { ...createEditor(), text, cursor, submitted: this.submitted, secret: this.secret,
+      history: this.history, historyLimit: this.historyLimit };
+  }
+
+  applyKey(key: Key): EditorState {
+    return this.acceptInput(encodeKey(key));
+  }
+
+  applyExternal(text: string): EditorState {
+    this.pi.setText(text);
+    this.submitted = null;
+    return this.state;
+  }
+
+  setSecret(secret: boolean): EditorState {
+    if (this.secret === secret) return this.state;
+    const focused = this.focused;
+    const text = this.secret ? "" : this.pi.getExpandedText();
+    this.secret = secret;
+    // Discard secret undo/history at the authentication boundary.
+    this.pi = this.createPi();
+    this.pi.focused = focused;
+    this.pi.setText(text);
+    return this.state;
+  }
+
+  render(width: number): string[] {
+    this.pi.borderColor = this.borderColor;
+    if (this.secret) {
+      // A display-only projection never passes plaintext to the renderer.
+      const masked = new PiEditor(this.host, identityEditorTheme());
+      masked.borderColor = this.borderColor;
+      masked.focused = this.focused;
+      masked.setText(maskSecret(this.pi.getText()));
+      for (const _ of this.pi.getText().slice(this.state.cursor)) masked.handleInput("\x1b[D");
+      return masked.render(width);
+    }
+    return this.pi.render(width);
+  }
+}