gentle-pi 3.7.0 → 4.1.0

package/lib/theme-customization.ts

@@ -0,0 +1,52 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync, realpathSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { colorToRgb, parseColor } from "@earendil-works/pi-tui";
+
+const MAX_BYTES = 256_000;
+const HEX = /^#[0-9a-fA-F]{6}$/;
+const REFERENCE = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+/** Read only the installed source supplied by Pi; never use the active theme as a fallback. */
+export function sourcePalettePreview(name: string, sourcePath: string | undefined): { title: string; sample: string } {
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name) || !sourcePath || !isAbsolute(sourcePath)) throw new Error("Installed theme source unavailable.");
+	// Pi's installed themes can live behind platform symlinks. Resolve the
+	// Pi-supplied path, then open the target without following another symlink.
+	const path = realpathSync(sourcePath);
+	const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+	let text: string;
+	try {
+		const stat = fstatSync(fd);
+		if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error("Theme source unavailable or too large.");
+		const bytes = readFileSync(fd);
+		if (bytes.length > MAX_BYTES) throw new Error("Theme source too large.");
+		text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} finally { closeSync(fd); }
+	const document: unknown = JSON.parse(text);
+	if (!document || typeof document !== "object" || Array.isArray(document)) throw new Error("Invalid theme source.");
+	const { name: sourceName, colors, vars } = document as Record<string, unknown>;
+	if (sourceName !== name || !colors || typeof colors !== "object" || Array.isArray(colors)) throw new Error("Theme source does not match installed theme.");
+	if (vars !== undefined && (!vars || typeof vars !== "object" || Array.isArray(vars))) throw new Error("Invalid theme variables.");
+	const palette = colors as Record<string, unknown>;
+	const variables = (vars ?? {}) as Record<string, unknown>;
+	const escape = (role: "accent" | "text", background: boolean): string => {
+		let value: unknown = palette[role];
+		const seen = new Set<string>();
+		while (typeof value === "string" && REFERENCE.test(value)) {
+			if (seen.has(value) || !Object.hasOwn(variables, value)) throw new Error("Invalid theme color reference.");
+			seen.add(value);
+			value = variables[value];
+		}
+		const prefix = background ? 48 : 38;
+		if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 255) return `\x1b[${prefix};5;${value}m`;
+		if (typeof value === "string" && HEX.test(value)) return `\x1b[${prefix};2;${parseInt(value.slice(1, 3), 16)};${parseInt(value.slice(3, 5), 16)};${parseInt(value.slice(5, 7), 16)}m`;
+		// Pi 0.99.1's built-in palettes use OKHSL. Delegate the exact color
+		// grammar, finite/range checks and conversion to the public host utility;
+		// do not broaden this source-only preview to arbitrary CSS colors.
+		if (typeof value === "string" && value.startsWith("okhsl(")) {
+			const { r, g, b } = colorToRgb(parseColor(value));
+			return `\x1b[${prefix};2;${r};${g};${b}m`;
+		}
+		throw new Error("Invalid theme palette color.");
+	};
+	return { title: `${name} · source palette`, sample: `${escape("accent", true)}  \x1b[0m ${escape("text", false)}Aa  sample text\x1b[0m` };
+}

package/lib/vim-editor-adapter.ts

@@ -0,0 +1,383 @@
+import { CURSOR_MARKER, Editor, visibleWidth } from "@earendil-works/pi-tui";
+import { createRequire } from "node:module";
+
+// Private shape audited against @earendil-works/pi-tui 0.99.1, 0.99.2, 1.0.0 and 1.1.0:
+// editor.js state/pastes/history, sticky cursor reset, layoutText/render geometry,
+// autocomplete cancellation and { state, pastes, pasteCounter } undo restoration;
+// undo-stack.js clone-on-push/pop snapshots. The two 0.99 releases ship identical
+// editor/undo-stack sources; 1.0.0 is a touched-contract audit, not byte identity.
+// The 1.1.0 touched-contract audit retains clone-on-push snapshots with the
+// paste registry, cursor resets, layoutText/render geometry and history exit.
+// cancelAutocomplete aborts/debounces requests before clearing its UI;
+// the adapter still calls that host-owned method, never mutating its request state.
+// Actual installed bundled/unbundled tests exercise identity, edit/undo, paste,
+// selection, wrapping/scroll and autocomplete; fabricated metadata tests only
+// prove exact-version admission for the older audited releases.
+// Never silently adapt another build: undo also owns the paste registry.
+interface Position { line: number; col: number }
+interface State { lines: string[]; cursorLine: number; cursorCol: number }
+interface Snapshot { state: State; pastes: Map<number, string>; pasteCounter: number }
+interface Stack { stack: Snapshot[]; length: number; push(snapshot: Snapshot): void; pop(): Snapshot | undefined }
+interface InsertSession { prefix: Snapshot[]; before: Snapshot; text: string; anchor: number }
+const insertSessions = new WeakMap<object, InsertSession>();
+interface LayoutLine { text: string; hasCursor: boolean; cursorPos?: number }
+interface PrivateEditor {
+  state: State;
+  getText(): string;
+  getCursor(): Position;
+  onChange?: (text: string) => void;
+  pastes: Map<number, string>;
+  pasteCounter: number;
+  undoStack: Stack;
+  history: string[];
+  historyIndex: number;
+  historyDraft: State | null;
+  lastAction: string | null;
+  preferredVisualCol: number | null;
+  snappedFromCursorCol: number | null;
+  scrollOffset: number;
+  renderedVisibleLineCount: number;
+  paddingX: number;
+  layoutText(width: number): LayoutLine[];
+  render(width: number): string[];
+  lastWidth: number;
+  pushUndoSnapshot(): void;
+  undo(): void;
+  setCursorCol(col: number): void;
+  autocompleteState: unknown;
+  cancelAutocomplete(): void;
+  exitHistoryBrowsing(): void;
+}
+
+// The single audited-release source for the adapter and Gentle Shell's runtime
+// identity gates. Add a release only after re-auditing the files named above.
+export const AUDITED_PI_EDITOR_VERSIONS = Object.freeze(["0.99.1", "0.99.2", "1.0.0", "1.1.0"] as const);
+export type AuditedPiEditorVersion = (typeof AUDITED_PI_EDITOR_VERSIONS)[number];
+
+export function isAuditedPiEditorVersion(version: unknown): version is AuditedPiEditorVersion {
+  return typeof version === "string" && (AUDITED_PI_EDITOR_VERSIONS as readonly string[]).includes(version);
+}
+// Pi aliases only ES imports of host packages. This raw require walks
+// node_modules from the extension, which a git install lacks (#1586), so an
+// unresolved host leaves the version unknown and the identity gate closed.
+const importedTuiMetadata: unknown = (() => {
+  try { return createRequire(import.meta.url)("@earendil-works/pi-tui/package.json"); } catch { return undefined; }
+})();
+const IMPORTED_TUI_VERSION = typeof importedTuiMetadata === "object" && importedTuiMetadata !== null &&
+  "version" in importedTuiMetadata ? importedTuiMetadata.version : undefined;
+
+// The caller supplies the Editor constructor from the same Pi/TUI package pair
+// as the version metadata. An arbitrary object with matching fields is not an editor.
+function hasEditorIdentity(value: unknown, version: string, editorClass: typeof Editor, verifiedVersion?: string): boolean {
+  if (!isAuditedPiEditorVersion(version) || typeof value !== "object" || value === null ||
+      (verifiedVersion !== undefined ? version !== verifiedVersion :
+        editorClass === Editor ? version !== IMPORTED_TUI_VERSION : true) || !(value instanceof editorClass)) return false;
+  let prototype: unknown = Object.getPrototypeOf(value);
+  for (let depth = 0; depth < 3; depth++) {
+    if (prototype === editorClass.prototype) return true;
+    if (typeof prototype !== "object" || prototype === null || !Object.hasOwn(prototype, "constructor")) return false;
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  return false;
+}
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const marker = /\[paste #(\d+)(?: (?:\+\d+ lines|\d+ chars))?\]/g;
+
+// Only CSI SGR and Pi's own zero-width cursor marker are expected in editor
+// text. Unknown escapes leave the unmodified frame intact (fail closed).
+function highlightRenderedRow(row: string, chunk: LayoutLine, left: number, right: number, padding: number): string | undefined {
+  const cursor = chunk.hasCursor ? chunk.cursorPos : undefined;
+  const tokens = row.match(/\x1b\[[0-9;]*m|\x1b\][^\x07]*(?:\x07|\x1b\\)|\x1b_[^\x07\x1b]*(?:\x07|\x1b\\)|[^\x1b]/g);
+  if (!tokens || tokens.join("") !== row) return undefined;
+  let plain = "";
+  for (const token of tokens) if (!token.startsWith("\x1b")) plain += token;
+  const before = " ".repeat(padding);
+  if (!plain.startsWith(before + chunk.text)) return undefined;
+  // Pi's fake cursor inserts one space only when it sits at the end.
+  const expected = before + chunk.text + (cursor === chunk.text.length ? " " : "");
+  if (!plain.startsWith(expected)) return undefined;
+  let result = "";
+  let col = 0;
+  let selected = false;
+  let inverse = false;
+  let nativeInverse = false;
+  for (const token of tokens) {
+    if (token.startsWith("\x1b[")) {
+      const codes = token.slice(2, -1).split(";").map(Number);
+      for (let i = 0; i < codes.length; i++) {
+        const code = codes[i];
+        if ((code === 38 || code === 48 || code === 58) && codes[i + 1] === 2 && i + 4 < codes.length) i += 4;
+        else if ((code === 38 || code === 48 || code === 58) && codes[i + 1] === 5 && i + 2 < codes.length) i += 2;
+        else if (code === 0 || code === 27) nativeInverse = inverse = false;
+        else if (code === 7) nativeInverse = inverse = true;
+      }
+      result += token;
+      if (selected && !inverse) { result += "\x1b[7m"; inverse = true; }
+    } else if (token.startsWith("\x1b")) {
+      if (token !== CURSOR_MARKER) return undefined;
+      result += token;
+    } else {
+      const local = col - padding;
+      const shouldSelect = local >= left && local < right && local < chunk.text.length;
+      if (shouldSelect !== selected) {
+        // SGR 27 changes only reverse video; keep foreground/background intact.
+        if (shouldSelect || !nativeInverse && inverse) result += shouldSelect ? "\x1b[7m" : "\x1b[27m";
+        selected = shouldSelect;
+        inverse = shouldSelect || nativeInverse;
+      }
+      result += token;
+      col++;
+    }
+  }
+  if (selected && !nativeInverse) result += "\x1b[27m";
+  return result;
+}
+
+function boundaries(line: string, pastes: Map<number, string>): number[] {
+  const units = [...segmenter.segment(line)].map((part) => part.index);
+  for (const match of line.matchAll(marker)) {
+    if (!pastes.has(Number(match[1]))) continue;
+    const start = match.index;
+    const end = start + match[0].length;
+    for (let i = units.length - 1; i >= 0; i--) {
+      if (units[i]! > start && units[i]! < end) units.splice(i, 1);
+    }
+  }
+  return [...units, line.length];
+}
+
+function assertUniquePastes(editor: PrivateEditor): void {
+  const registered = new Set<number>();
+  for (const match of editor.getText().matchAll(marker)) {
+    const id = Number(match[1]);
+    if (!editor.pastes.has(id)) continue;
+    if (registered.has(id)) throw new Error("Duplicate registered paste marker: private Vim editing is unsafe");
+    registered.add(id);
+  }
+}
+
+function assertPosition(editor: PrivateEditor, pos: Position): void {
+  assertUniquePastes(editor);
+  const line = editor.state.lines[pos.line];
+  if (line === undefined || !Number.isInteger(pos.col) || !boundaries(line, editor.pastes).includes(pos.col)) {
+    throw new Error("Cursor must be on a valid grapheme or paste boundary");
+  }
+}
+
+function hasSnapshotShape(value: unknown): value is Snapshot {
+  if (typeof value !== "object" || value === null || !("state" in value) ||
+      !("pastes" in value) || !("pasteCounter" in value)) return false;
+  const state = value.state;
+  return typeof state === "object" && state !== null && "lines" in state &&
+    Array.isArray(state.lines) && state.lines.length > 0 && state.lines.every((line) => typeof line === "string") &&
+    "cursorLine" in state && Number.isInteger(state.cursorLine) &&
+    typeof state.cursorLine === "number" && state.cursorLine >= 0 && state.cursorLine < state.lines.length &&
+    "cursorCol" in state && typeof state.cursorCol === "number" && Number.isInteger(state.cursorCol) &&
+    state.cursorCol >= 0 && state.cursorCol <= state.lines[state.cursorLine].length &&
+    value.pastes instanceof Map && [...value.pastes].every(([id, text]) => Number.isInteger(id) && id > 0 && typeof text === "string") &&
+    typeof value.pasteCounter === "number" && Number.isInteger(value.pasteCounter) && value.pasteCounter >= 0;
+}
+
+export function createVimEditorAdapter(value: unknown, version: string, editorClass: typeof Editor = Editor, verifiedVersion?: string) {
+  if (!hasEditorIdentity(value, version, editorClass, verifiedVersion)) throw new Error("Unsupported Pi editor layout/version");
+  const editor = value as unknown as PrivateEditor;
+  const s = editor.state;
+  if (!s || !Array.isArray(s.lines) || s.lines.length === 0 || !s.lines.every((line) => typeof line === "string") ||
+      !Number.isInteger(s.cursorLine) || !Number.isInteger(s.cursorCol) || !(editor.pastes instanceof Map) ||
+      !Number.isInteger(editor.pasteCounter) || !Array.isArray(editor.history) ||
+      typeof editor.undoStack?.push !== "function" || typeof editor.undoStack?.pop !== "function" ||
+      !Array.isArray(editor.undoStack.stack) || editor.undoStack.length !== editor.undoStack.stack.length ||
+      !hasSnapshotShape(editor) || !editor.undoStack.stack.every(hasSnapshotShape) ||
+      typeof editor.getText !== "function" || typeof editor.getCursor !== "function" ||
+      !editor.history.every((line) => typeof line === "string") ||
+      typeof editor.pushUndoSnapshot !== "function" || typeof editor.undo !== "function" || typeof editor.setCursorCol !== "function" ||
+      typeof editor.cancelAutocomplete !== "function" || typeof editor.exitHistoryBrowsing !== "function" ||
+      typeof editor.layoutText !== "function" || typeof editor.render !== "function" ||
+      !Number.isInteger(editor.paddingX) || editor.paddingX < 0) {
+    throw new Error("Unsupported Pi editor layout/version");
+  }
+  assertPosition(editor, { line: s.cursorLine, col: s.cursorCol });
+  return {
+    dismissAutocomplete(): void { editor.cancelAutocomplete(); },
+    undo(): void { assertUniquePastes(editor); editor.undo(); },
+    beginInsertSession(): void {
+      assertUniquePastes(editor);
+      if (insertSessions.has(editor)) throw new Error("Insert session already active");
+      const cursor = editor.getCursor();
+      const anchor = editor.state.lines.slice(0, cursor.line).reduce((n, line) => n + line.length + 1, 0) + cursor.col;
+      insertSessions.set(editor, { prefix: editor.undoStack.stack.slice(), anchor,
+        before: structuredClone({ state: editor.state, pastes: editor.pastes, pasteCounter: editor.pasteCounter }), text: editor.getText() });
+    },
+    markInsertAnchor(): void {
+      assertUniquePastes(editor);
+      const session = insertSessions.get(editor);
+      if (!session) return;
+      const cursor = editor.getCursor();
+      session.anchor = editor.state.lines.slice(0, cursor.line).reduce((n, line) => n + line.length + 1, 0) + cursor.col;
+      session.text = editor.getText();
+    },
+    endInsertSession(): string | undefined {
+      const session = insertSessions.get(editor);
+      insertSessions.delete(editor);
+      assertUniquePastes(editor);
+      if (!session) return;
+      const stack = editor.undoStack;
+      // Submission clears Pi's stack. Never resurrect a pre-submit snapshot.
+      const depth = session.prefix.length;
+      if (stack.length < depth || stack.length !== stack.stack.length ||
+          session.prefix.some((snapshot, index) => stack.stack[index] !== snapshot)) return;
+      const after = editor.getText();
+      const inserted = after.startsWith(session.text.slice(0, session.anchor)) &&
+        after.endsWith(session.text.slice(session.anchor)) ? after.slice(session.anchor, after.length - (session.text.length - session.anchor)) : undefined;
+      if (after === session.before.state.lines.join("\n") && editor.pasteCounter === session.before.pasteCounter) {
+        stack.stack.splice(depth);
+        editor.lastAction = null;
+        return;
+      }
+      // A mutation without a Pi snapshot is not an editor-owned insert session.
+      if (stack.length === depth) return;
+      stack.stack.splice(depth);
+      stack.push(session.before);
+      editor.lastAction = null;
+      // A repeat can only carry an insertion at its original anchor. Reject
+      // collapsed paste additions and edits to pre-existing text, even if Pi
+      // successfully grouped the original session into one undo snapshot.
+      return inserted && editor.pasteCounter === session.before.pasteCounter &&
+        ![...inserted.matchAll(marker)].some((match) => editor.pastes.has(Number(match[1]))) ? inserted : undefined;
+    },
+    motionBoundaries(): number[][] {
+      assertUniquePastes(editor);
+      return editor.state.lines.map((line) => boundaries(line, editor.pastes));
+    },
+    move(pos: Position): void {
+      assertPosition(editor, pos);
+      editor.state.cursorLine = pos.line;
+      editor.setCursorCol(pos.col);
+      editor.lastAction = null;
+      if (editor.autocompleteState) editor.cancelAutocomplete();
+    },
+    moveByGraphemes(delta: number): void {
+      if (!Number.isInteger(delta)) throw new Error("Invalid motion");
+      const positions = editor.state.lines.flatMap((line, index) =>
+        boundaries(line, editor.pastes).map((col) => ({ line: index, col })));
+      const current = editor.getCursor();
+      const at = positions.findIndex((p) => p.line === current.line && p.col === current.col);
+      if (at < 0) throw new Error("Invalid cursor boundary");
+      const target = positions[Math.max(0, Math.min(positions.length - 1, at + delta))]!;
+      this.move(target);
+    },
+    readRange(start: Position, end: Position): string {
+      assertPosition(editor, start);
+      assertPosition(editor, end);
+      const offset = (p: Position) => editor.state.lines.slice(0, p.line).reduce((n, line) => n + line.length + 1, 0) + p.col;
+      const a = offset(start), b = offset(end);
+      if (b < a) throw new Error("Invalid selection range");
+      const source = editor.getText();
+      for (const match of source.matchAll(marker)) {
+        if (editor.pastes.has(Number(match[1])) && a < match.index + match[0].length && b > match.index)
+          throw new Error("Selection cannot edit collapsed paste marker");
+      }
+      return source.slice(a, b);
+    },
+    replace(start: Position, end: Position, text: string): void {
+      assertPosition(editor, start);
+      assertPosition(editor, end);
+      const source = editor.getText();
+      const offset = (p: Position) => editor.state.lines.slice(0, p.line).reduce((n, line) => n + line.length + 1, 0) + p.col;
+      const a = offset(start);
+      const b = offset(end);
+      if (b < a || (b === a && !text) || text.includes("\r")) throw new Error("Invalid operator range or replacement");
+      // No registry surgery: a range intersecting a collapsed paste is unsafe.
+      for (const match of source.matchAll(marker)) {
+        if (editor.pastes.has(Number(match[1])) && a < match.index + match[0].length && b > match.index) {
+          throw new Error("Operator cannot edit collapsed paste marker");
+        }
+      }
+      const next = source.slice(0, a) + text + source.slice(b);
+      const registered = new Set<number>();
+      for (const match of next.matchAll(marker)) {
+        const id = Number(match[1]);
+        if (!editor.pastes.has(id)) continue;
+        if (registered.has(id)) throw new Error("Duplicate registered paste marker: private Vim editing is unsafe");
+        registered.add(id);
+      }
+      if (next === source) return;
+      const lines = next.split("\n");
+      const prefix = next.slice(0, a + text.length).split("\n");
+      editor.cancelAutocomplete();
+      editor.exitHistoryBrowsing();
+      editor.pushUndoSnapshot();
+      editor.state.lines = lines;
+      editor.state.cursorLine = prefix.length - 1;
+      editor.setCursorCol(prefix.at(-1)!.length);
+      editor.lastAction = null;
+      editor.scrollOffset = 0;
+      editor.onChange?.(next);
+    },
+    renderSelection(width: number, start: Position, end: Position, rendered?: string[]): string[] {
+      assertPosition(editor, start);
+      assertPosition(editor, end);
+      if (!Number.isInteger(width) || width < 1) throw new Error("Invalid render width");
+      const offset = (pos: Position) => editor.state.lines.slice(0, pos.line)
+        .reduce((n, line) => n + line.length + 1, 0) + pos.col;
+      const from = offset(start);
+      const to = offset(end);
+      if (from === to) return rendered ?? editor.render(width);
+      const selectionFrom = Math.min(from, to);
+      const selectionTo = Math.max(from, to);
+      // Observe Pi's completed render; never replace its layout method or
+      // reconstruct its cursor, borders, autocomplete, or padded row geometry.
+      const rows = rendered ?? editor.render(width);
+      const maxPadding = Math.max(0, Math.floor((width - 1) / 2));
+      const padding = Math.min(editor.paddingX, maxPadding);
+      const layoutWidth = Math.max(1, width - padding * 2 - (padding ? 0 : 1));
+      if (editor.lastWidth !== layoutWidth || !Number.isInteger(editor.scrollOffset) || editor.scrollOffset < 0) return rows;
+      const layout = editor.layoutText(layoutWidth);
+      if (!Number.isInteger(editor.renderedVisibleLineCount) || editor.renderedVisibleLineCount < 1 ||
+          editor.renderedVisibleLineCount + 2 > rows.length) return rows;
+      const visible = layout.slice(editor.scrollOffset, editor.scrollOffset + editor.renderedVisibleLineCount);
+      if (visible.length !== editor.renderedVisibleLineCount) return rows;
+      let logicalLine = 0;
+      let searchFrom = 0;
+      // Advance through hidden wraps before mapping visible chunks.
+      for (const hidden of layout.slice(0, editor.scrollOffset)) {
+        if (typeof hidden.text !== "string") return rows;
+        let index = editor.state.lines[logicalLine]?.indexOf(hidden.text, searchFrom) ?? -1;
+        while (index < 0 && logicalLine + 1 < editor.state.lines.length) {
+          logicalLine++;
+          searchFrom = 0;
+          index = editor.state.lines[logicalLine]!.indexOf(hidden.text, searchFrom);
+        }
+        if (index < 0) return rows;
+        searchFrom = index + hidden.text.length;
+      }
+      const replacements: Array<[number, string]> = [];
+      for (let row = 0; row < visible.length; row++) {
+        const chunk = visible[row]!;
+        if (typeof chunk.text !== "string" || typeof chunk.hasCursor !== "boolean" ||
+            (chunk.hasCursor && (!Number.isInteger(chunk.cursorPos) || chunk.cursorPos! < 0 || chunk.cursorPos! > chunk.text.length))) return rows;
+        let index = editor.state.lines[logicalLine]?.indexOf(chunk.text, searchFrom) ?? -1;
+        while (index < 0 && logicalLine + 1 < editor.state.lines.length) {
+          logicalLine++;
+          searchFrom = 0;
+          index = editor.state.lines[logicalLine]!.indexOf(chunk.text, searchFrom);
+        }
+        if (index < 0) return rows;
+        searchFrom = index + chunk.text.length;
+        const chunkStart = offset({ line: logicalLine, col: index });
+        const left = Math.max(0, Math.min(chunk.text.length, selectionFrom - chunkStart));
+        const right = Math.max(0, Math.min(chunk.text.length, selectionTo - chunkStart));
+        if (right <= left) continue;
+        const original = rows[row + 1]!;
+        const prefix = " ".repeat(padding);
+        if (!original.startsWith(prefix)) return rows;
+        const result = highlightRenderedRow(original, chunk, left, right, padding);
+        if (result === undefined || visibleWidth(result) !== visibleWidth(original)) return rows;
+        replacements.push([row + 1, result]);
+      }
+      const result = rows.slice();
+      for (const [index, replacement] of replacements) result[index] = replacement;
+      return result;
+    },
+  };
+}

package/lib/vim-normal-engine.ts

@@ -0,0 +1,154 @@
+export interface VimPosition { line: number; col: number }
+export interface VimMotion { cursor: VimPosition; insert?: string; handled: boolean }
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const word = /[\p{L}\p{N}_]/u;
+const whitespace = /\s/u;
+function kind(char: string): number { return whitespace.test(char) ? 0 : word.test(char) ? 1 : 2; }
+
+export class VimNormalEngine {
+  private digits = "";
+  private awaitingG = false;
+  private gLine: number | undefined;
+  private preferred: number | undefined;
+  private pendingFind: { direction: number; till: boolean; count: number } | undefined;
+  private lastFind: { char: string; direction: number; till: boolean; target: VimPosition; landing: VimPosition } | undefined;
+
+  reset(): void {
+    this.digits = ""; this.awaitingG = false; this.gLine = undefined; this.preferred = undefined;
+    this.pendingFind = undefined; this.lastFind = undefined;
+  }
+
+  cancelPendingFind(): boolean {
+    if (!this.pendingFind) return false;
+    this.pendingFind = undefined;
+    this.digits = "";
+    return true;
+  }
+
+  input(key: string, text: string, cursor: VimPosition, motionBoundaries?: number[][]): VimMotion {
+    const lines = text.split("\n");
+    const positions = motionBoundaries ?? lines.map((line) => [...segmenter.segment(line)].map((part) => part.index).concat(line.length));
+    const firstNonWhitespace = (line: number): number => {
+      const stops = positions[line]!;
+      return stops.find((col, index) => index === stops.length - 1 || !whitespace.test(lines[line]!.slice(col, stops[index + 1]))) ?? 0;
+    };
+    const result = (line: number, col: number, insert?: string): VimMotion => ({
+      cursor: { line, col }, handled: true, ...(insert === undefined ? {} : { insert }),
+    });
+    const find = this.pendingFind;
+    if (find) {
+      this.pendingFind = undefined;
+      if ([...segmenter.segment(key)].length !== 1 || key.includes("\n")) return { cursor, handled: false };
+      return this.findOnLine(key, find.direction, find.till, find.count, text, cursor, positions);
+    }
+    if (/^[1-9]$/.test(key) || /^[0-9]+[^0-9]$/.test(key)) {
+      if (key.length === 1) { this.digits += key; return result(cursor.line, cursor.col); }
+      this.digits = key.slice(0, -1);
+      key = key.at(-1)!;
+    } else if (key === "0" && this.digits) {
+      this.digits += key;
+      return result(cursor.line, cursor.col);
+    }
+    const count = Math.min(10000, Number(this.digits) || 1);
+    const explicit = this.digits.length > 0;
+    this.digits = "";
+    if (this.awaitingG) {
+      this.awaitingG = false;
+      if (key === "g") {
+        this.preferred = undefined;
+        const line = this.gLine ?? 0;
+        this.gLine = undefined;
+        return result(Math.min(lines.length - 1, line), 0);
+      }
+      this.gLine = undefined;
+    }
+    if (key === "g") { this.awaitingG = true; this.gLine = explicit ? count - 1 : undefined; return result(cursor.line, cursor.col); }
+    if (key === "f" || key === "F" || key === "t" || key === "T") {
+      this.pendingFind = { direction: key === "f" || key === "t" ? 1 : -1, till: key === "t" || key === "T", count };
+      return result(cursor.line, cursor.col);
+    }
+    if (key === ";" || key === ",") {
+      if (!this.lastFind) return result(cursor.line, cursor.col);
+      const { char, direction, till, target, landing } = this.lastFind;
+      const motion = this.findOnLine(char, direction * (key === ";" ? 1 : -1), till, count, text, cursor, positions,
+        till && cursor.line === landing.line && cursor.col === landing.col ? target : undefined);
+      if (this.lastFind) this.lastFind.direction = direction;
+      return motion;
+    }
+    const current = positions[cursor.line] ?? [0];
+    const colIndex = Math.max(0, current.indexOf(cursor.col));
+    if (key === "h" || key === "l" || key === "Space" || key === " ") {
+      this.preferred = undefined;
+      return result(cursor.line, current[Math.max(0, Math.min(current.length - 1, colIndex + (key === "h" ? -count : count)))]!);
+    }
+    if (key === "j" || key === "k") {
+      this.preferred ??= colIndex;
+      const line = Math.max(0, Math.min(lines.length - 1, cursor.line + (key === "j" ? count : -count)));
+      return result(line, positions[line]![Math.min(this.preferred, positions[line]!.length - 1)]!);
+    }
+    this.preferred = undefined;
+    if (key === "0") return result(cursor.line, 0);
+    if (key === "^") return result(cursor.line, firstNonWhitespace(cursor.line));
+    if (key === "$" || key === "A") return result(cursor.line, lines[cursor.line]!.length, key === "A" ? "" : undefined);
+    if (key === "G") return result(Math.min(lines.length - 1, explicit ? count - 1 : lines.length - 1), 0);
+    if (key === "i") return result(cursor.line, cursor.col, "");
+    if (key === "I") return result(cursor.line, firstNonWhitespace(cursor.line), "");
+    if (key === "a") return result(cursor.line, current[Math.min(current.length - 1, colIndex + 1)]!, "");
+    if (key === "o") return result(cursor.line, lines[cursor.line]!.length, "\n");
+    if (key === "O") return result(cursor.line, 0, "\n");
+    if (key === "w" || key === "e" || key === "b") {
+      const units = lines.flatMap((line, index) => [...segmenter.segment(line)].map((part) => ({ line: index, col: part.index, char: part.segment })).concat(
+        index < lines.length - 1 ? [{ line: index, col: line.length, char: "\n" }] : []));
+      if (!units.length) return result(cursor.line, cursor.col);
+      let at = units.findIndex((p) => p.line === cursor.line && p.col === cursor.col);
+      if (at < 0) at = units.length;
+      for (let n = 0; n < count; n++) {
+        if (key === "w") {
+          const currentKind = kind(units[Math.min(at, units.length - 1)]!.char);
+          if (currentKind !== 0) while (at < units.length && kind(units[at]!.char) === currentKind) at++;
+          while (at < units.length && kind(units[at]!.char) === 0) at++;
+        } else if (key === "e") {
+          if (at < units.length - 1) at++;
+          while (at < units.length - 1 && kind(units[at]!.char) === 0) at++;
+          const group = kind(units[Math.min(at, units.length - 1)]!.char);
+          while (at < units.length - 1 && kind(units[at + 1]!.char) === group) at++;
+        } else {
+          at = Math.max(0, at - 1);
+          while (at > 0 && kind(units[at]!.char) === 0) at--;
+          const group = kind(units[at]!.char);
+          while (at > 0 && kind(units[at - 1]!.char) === group) at--;
+        }
+      }
+      const target = units[Math.min(at, units.length - 1)]!;
+      return result(target.line, target.col);
+    }
+    return { cursor, handled: false };
+  }
+
+  private findOnLine(char: string, direction: number, till: boolean, count: number, text: string,
+    cursor: VimPosition, positions: number[][], skip?: VimPosition): VimMotion {
+    const line = text.split("\n")[cursor.line];
+    const stops = positions[cursor.line];
+    if (line === undefined || !stops) return { cursor, handled: true };
+    let at = stops.indexOf(cursor.col);
+    if (at < 0) return { cursor, handled: true };
+    // Search only complete motion units: registered paste placeholders are
+    // atomic even if the target occurs inside their displayed marker.
+    for (let n = 0; n < count; n++) {
+      let found = -1;
+      for (let i = at + direction; i >= 0 && i < stops.length - 1; i += direction) {
+        if (skip?.line === cursor.line && skip.col === stops[i]) continue;
+        if (line.slice(stops[i], stops[i + 1]) === char) { found = i; break; }
+      }
+      if (found < 0) return { cursor, handled: true };
+      at = found;
+      skip = undefined;
+    }
+    const col = stops[Math.max(0, Math.min(stops.length - 1, at - (till ? direction : 0)))]!;
+    const landing = { line: cursor.line, col };
+    this.preferred = undefined;
+    this.lastFind = { char, direction, till, target: { line: cursor.line, col: stops[at]! }, landing };
+    return { cursor: landing, handled: true };
+  }
+}