@wwwyo/pi-vim 0.0.0-stage → 0.14.2

package/input-keys.ts

@@ -0,0 +1,50 @@
+import { matchesKey } from "@earendil-works/pi-tui";
+import { getLineGraphemes } from "./motions.js";
+
+// Keyboard-input classification predicates. Pure functions over the raw
+// input chunk a terminal delivers to the editor — no editor state. Shared
+// by the EX mini-mode, insert, and normal-mode dispatch paths.
+
+export function isEscapeLikeInput(data: string): boolean {
+  return matchesKey(data, "escape") || matchesKey(data, "ctrl+[");
+}
+
+export function isEnterLikeInput(data: string): boolean {
+  return (
+    data === "\r" ||
+    data === "\n" ||
+    matchesKey(data, "enter") ||
+    matchesKey(data, "return")
+  );
+}
+
+export function isBackspaceLikeInput(data: string): boolean {
+  return (
+    data === "\x7f" ||
+    data === "\x08" ||
+    matchesKey(data, "backspace") ||
+    matchesKey(data, "ctrl+h")
+  );
+}
+
+export function isPrintableChunk(data: string): boolean {
+  if (data.length === 0) return false;
+  for (const char of data) {
+    const codePoint = char.codePointAt(0);
+    if (codePoint === undefined || codePoint < 32 || codePoint === 127)
+      return false;
+  }
+  return true;
+}
+
+export function isPrintableInput(data: string): boolean {
+  return isPrintableChunk(data) && getLineGraphemes(data).length === 1;
+}
+
+export function isDigit(data: string): boolean {
+  return data.length === 1 && data >= "0" && data <= "9";
+}
+
+export function isCountStarter(data: string): boolean {
+  return data.length === 1 && data >= "1" && data <= "9";
+}

package/mode-change-command.ts

@@ -0,0 +1,120 @@
+import { spawn } from "node:child_process";
+
+import type { ModeChangeSettings } from "./settings.js";
+import type { Mode } from "./types.js";
+
+const MODE_CHANGE_COMMAND_TIMEOUT_MS = 2000;
+
+type ModeChangeCommandRunner = (command: string) => void;
+type RunningModeChangeCommand = {
+  child: ReturnType<typeof spawn>;
+  timeout: ReturnType<typeof setTimeout>;
+};
+export type ModeChangeEvent = { mode: Mode; previousMode: Mode };
+
+let activeModeChangeCommand: RunningModeChangeCommand | null = null;
+let pendingModeChangeCommand: string | null = null;
+let modeChangeCommandRunner: ModeChangeCommandRunner = spawnModeChangeCommand;
+
+export function setModeChangeCommandRunnerForTests(
+  next: ModeChangeCommandRunner,
+): () => void {
+  const prev = modeChangeCommandRunner;
+  modeChangeCommandRunner = next;
+  return () => {
+    modeChangeCommandRunner = prev;
+  };
+}
+
+function spawnModeChangeCommand(command: string): void {
+  if (!command) return;
+  if (activeModeChangeCommand) {
+    pendingModeChangeCommand = command;
+    return;
+  }
+
+  startModeChangeCommand(command);
+}
+
+function startModeChangeCommand(command: string): void {
+  let child: ReturnType<typeof spawn>;
+  try {
+    child = spawn(command, {
+      shell: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+  } catch {
+    // spawn rejected synchronously (e.g., EMFILE) — never break the editor
+    runPendingModeChangeCommand();
+    return;
+  }
+
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timeout);
+    if (activeModeChangeCommand?.child !== child) return;
+    activeModeChangeCommand = null;
+    runPendingModeChangeCommand();
+  };
+  const timeout = setTimeout(() => {
+    try {
+      child.kill();
+    } catch {
+      // best effort timeout cleanup
+    }
+    finish();
+  }, MODE_CHANGE_COMMAND_TIMEOUT_MS);
+  timeout.unref?.();
+
+  activeModeChangeCommand = { child, timeout };
+  child.once("error", finish);
+  child.once("close", finish);
+}
+
+function runPendingModeChangeCommand(): void {
+  const pending = pendingModeChangeCommand;
+  pendingModeChangeCommand = null;
+  if (pending) startModeChangeCommand(pending);
+}
+
+function clearPendingModeChangeCommand(): void {
+  pendingModeChangeCommand = null;
+}
+
+export function cancelModeChangeCommands(): void {
+  pendingModeChangeCommand = null;
+  const active = activeModeChangeCommand;
+  activeModeChangeCommand = null;
+  if (!active) return;
+  clearTimeout(active.timeout);
+  try {
+    active.child.kill();
+  } catch {
+    // best effort session cleanup
+  }
+}
+
+export function createModeChangeHandler(
+  modeChange: ModeChangeSettings | undefined,
+  emitModeChange: (event: ModeChangeEvent) => void,
+): (mode: Mode, prevMode: Mode) => void {
+  const insert = modeChange?.insert;
+  const normal = modeChange?.normal;
+  return (mode, previousMode) => {
+    try {
+      emitModeChange({ mode, previousMode });
+    } catch {
+      // Subscribers must not break editing or configured mode-change commands.
+    }
+
+    const command = mode === "insert" ? insert : normal;
+    if (command) {
+      modeChangeCommandRunner(command);
+    } else {
+      clearPendingModeChangeCommand();
+    }
+  };
+}

package/mode-colors.ts

@@ -0,0 +1,97 @@
+import type { ModeColorSettings } from "./settings.js";
+
+const MODE_COLORS = {
+  insert: "borderMuted",
+  normal: "borderAccent",
+  visual: "customMessageLabel",
+  ex: "warning",
+} as const;
+const TOKEN = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+
+export type ModeColorKey = keyof typeof MODE_COLORS;
+export type ModeColorizers = Record<ModeColorKey, (s: string) => string>;
+export type ThemeLike = { fg(token: string, text: string): string };
+
+export function resolveModeColors(
+  colors?: ModeColorSettings,
+): Required<ModeColorSettings> {
+  return {
+    insert: colors?.insert ?? MODE_COLORS.insert,
+    normal: colors?.normal ?? MODE_COLORS.normal,
+    visual: colors?.visual ?? MODE_COLORS.visual,
+    ex: colors?.ex ?? MODE_COLORS.ex,
+  };
+}
+
+function colorizeWithTheme(
+  theme: ThemeLike,
+  token: string,
+  fallback: string,
+  text: string,
+): string {
+  const trimmedToken = token.trim();
+  if (TOKEN.test(trimmedToken)) {
+    try {
+      return theme.fg(trimmedToken, text);
+    } catch {
+      return theme.fg(fallback, text);
+    }
+  }
+  return theme.fg(fallback, text);
+}
+
+export function buildModeColorizers(
+  theme: ThemeLike,
+  colors: Required<ModeColorSettings>,
+  transform: (text: string) => string = (text) => text,
+): ModeColorizers {
+  const colorizer = (mode: ModeColorKey) => (text: string) =>
+    colorizeWithTheme(theme, colors[mode], MODE_COLORS[mode], transform(text));
+  return {
+    insert: colorizer("insert"),
+    normal: colorizer("normal"),
+    visual: colorizer("visual"),
+    ex: colorizer("ex"),
+  };
+}
+
+// Sentinel string passed through two border colorizers to compare the color
+// they emit without caring about the text they wrap.
+const BORDER_COLOR_PROBE = "|";
+
+// Builds a colorizer that renders Pi's neutral "thinking off" border color.
+// Used as the reference for the resting/default border so pi-vim can recolor
+// only that state and defer to any active thinking level or foreign highlight.
+export function buildOffBorderColor(theme: ThemeLike): (s: string) => string {
+  return (s: string) => {
+    try {
+      return theme.fg("thinkingOff", s);
+    } catch {
+      // Unknown token (e.g. a stripped-down theme): fall back to the raw text
+      // so the equality probe simply won't match a real colored border.
+      return s;
+    }
+  };
+}
+
+// Returns true when the host's current border color (`base`) is the neutral
+// resting default, meaning pi-vim may safely apply its own mode color. When
+// `offBorderColor` is unavailable, detection is disabled and this returns true
+// (legacy behavior: always apply the mode color). A probe that throws is
+// treated as "not neutral" so we defer rather than risk clobbering an unknown
+// highlight.
+export function isNeutralBorder(
+  base: unknown,
+  offBorderColor: ((s: string) => string) | null | undefined,
+): boolean {
+  if (typeof offBorderColor !== "function") return true;
+  if (typeof base !== "function") return true;
+  try {
+    return (
+      (base as (s: string) => string)(BORDER_COLOR_PROBE) ===
+      offBorderColor(BORDER_COLOR_PROBE)
+    );
+  } catch {
+    return false;
+  }
+}

package/mode-label.ts

@@ -0,0 +1,54 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getLineGraphemes } from "./motions.js";
+
+// Mode-label fitting for the footer. Pure, grapheme-aware string functions
+// that shrink the ` INSERT `/` NORMAL `/` EX … ` status label to a target
+// width without splitting a grapheme — no editor state. The `render()` path
+// composes the raw label (from editor state) and then fits it here.
+
+// Take as many trailing graphemes of `rawLabel` as fit within `width`,
+// measuring by visible width so wide/combining graphemes are never split.
+export function takeModeLabelSuffix(rawLabel: string, width: number): string {
+  if (width <= 0) return "";
+
+  const graphemes = getLineGraphemes(rawLabel);
+  const suffix: string[] = [];
+  let usedWidth = 0;
+
+  for (let i = graphemes.length - 1; i >= 0; i--) {
+    const grapheme = graphemes[i];
+    if (!grapheme) continue;
+
+    const segment = rawLabel.slice(grapheme.start, grapheme.end);
+    const segmentWidth = visibleWidth(segment);
+    if (usedWidth + segmentWidth > width) break;
+    suffix.push(segment);
+    usedWidth += segmentWidth;
+  }
+
+  return suffix.reverse().join("");
+}
+
+// Fit `rawLabel` into `width`. When it overflows, keep the leading mode
+// keyword (` INSERT `/` NORMAL `/` EX `) plus an ellipsis and as much of the
+// pending-command tail as fits; fall back to a plain right-truncation when
+// there is no recognizable keyword or no room for the keyword itself.
+export function fitModeLabel(rawLabel: string, width: number): string {
+  if (visibleWidth(rawLabel) <= width) return rawLabel;
+
+  const prefix = rawLabel.startsWith(" INSERT ")
+    ? " INSERT "
+    : rawLabel.startsWith(" NORMAL ")
+      ? " NORMAL "
+      : rawLabel.startsWith(" EX ")
+        ? " EX "
+        : "";
+
+  if (!prefix || visibleWidth(prefix) >= width) {
+    return truncateToWidth(rawLabel, width, "");
+  }
+
+  const suffixWidth = width - visibleWidth(prefix) - 1;
+  if (suffixWidth <= 0) return `${prefix}…`;
+  return `${prefix}…${takeModeLabelSuffix(rawLabel, suffixWidth)}`;
+}

package/motions.ts

@@ -0,0 +1,305 @@
+/**
+ * Motion calculation utilities for vim-mode
+ */
+
+import type { CharMotion } from "./types.js";
+
+// Character types for word boundary detection
+export type WordMotionClass = "word" | "WORD";
+
+enum CharType {
+  Space = 0,
+  Keyword = 1, // alphanumeric + underscore (or all non-space in WORD mode)
+  Other = 2, // punctuation/symbols
+}
+
+function getCharType(
+  c: string | undefined,
+  semanticClass: WordMotionClass = "word",
+): CharType {
+  if (!c || /\s/.test(c)) return CharType.Space;
+  if (semanticClass === "WORD") return CharType.Keyword;
+  if (/\w/.test(c)) return CharType.Keyword;
+  return CharType.Other;
+}
+
+function clampLineIndex(lines: readonly string[], lineIndex: number): number {
+  if (lines.length === 0) return 0;
+  if (!Number.isFinite(lineIndex)) return 0;
+  const normalized = Math.trunc(lineIndex);
+  return Math.max(0, Math.min(normalized, lines.length - 1));
+}
+
+/**
+ * Column of first non-whitespace char, or 0 for blank lines.
+ */
+export function findFirstNonWhitespaceColumn(line: string): number {
+  const match = line.search(/\S/);
+  return match === -1 ? 0 : match;
+}
+
+/**
+ * True when line matches ^\s*$.
+ */
+export function isBlankLine(line: string | undefined): boolean {
+  if (line === undefined) return true;
+  return /^\s*$/.test(line);
+}
+
+/**
+ * Paragraph start: non-blank line at BOF or after a blank line.
+ */
+export function isParagraphStart(
+  lines: readonly string[],
+  lineIndex: number,
+): boolean {
+  if (!Number.isInteger(lineIndex)) return false;
+  if (lineIndex < 0 || lineIndex >= lines.length) return false;
+  if (isBlankLine(lines[lineIndex])) return false;
+  if (lineIndex === 0) return true;
+  return isBlankLine(lines[lineIndex - 1]);
+}
+
+/**
+ * One step of } motion from current line index.
+ */
+export function findNextParagraphStart(
+  lines: readonly string[],
+  fromLine: number,
+): number {
+  if (lines.length === 0) return 0;
+
+  const start = clampLineIndex(lines, fromLine) + 1;
+  for (let i = start; i < lines.length; i++) {
+    if (isParagraphStart(lines, i)) return i;
+  }
+
+  return lines.length - 1;
+}
+
+/**
+ * One step of { motion from current line index.
+ */
+export function findPrevParagraphStart(
+  lines: readonly string[],
+  fromLine: number,
+): number {
+  if (lines.length === 0) return 0;
+
+  const start = clampLineIndex(lines, fromLine) - 1;
+  for (let i = start; i >= 0; i--) {
+    if (isParagraphStart(lines, i)) return i;
+  }
+
+  return 0;
+}
+
+/**
+ * Paragraph motion target for counted { / } semantics.
+ */
+export function findParagraphMotionTarget(
+  lines: readonly string[],
+  fromLine: number,
+  direction: "forward" | "backward",
+  count: number = 1,
+): number {
+  if (lines.length === 0) return 0;
+
+  const steps = Number.isFinite(count) && count > 0 ? Math.floor(count) : 1;
+  let currentLine = clampLineIndex(lines, fromLine);
+
+  for (let i = 0; i < steps; i++) {
+    const nextLine =
+      direction === "forward"
+        ? findNextParagraphStart(lines, currentLine)
+        : findPrevParagraphStart(lines, currentLine);
+
+    if (nextLine === currentLine) break;
+    currentLine = nextLine;
+  }
+
+  return currentLine;
+}
+
+/**
+ * Reverse a character motion direction (f ↔ F, t ↔ T).
+ */
+export function reverseCharMotion(motion: CharMotion): CharMotion {
+  const reverseMap: Record<CharMotion, CharMotion> = {
+    f: "F",
+    F: "f",
+    t: "T",
+    T: "t",
+  };
+  return reverseMap[motion];
+}
+
+const GRAPHEME_SEGMENTER =
+  typeof Intl !== "undefined" && typeof Intl.Segmenter === "function"
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : null;
+
+export function getLineGraphemes(
+  line: string,
+): Array<{ start: number; end: number }> {
+  const segments: Array<{ start: number; end: number }> = [];
+  if (GRAPHEME_SEGMENTER) {
+    for (const part of GRAPHEME_SEGMENTER.segment(line)) {
+      segments.push({
+        start: part.index,
+        end: part.index + part.segment.length,
+      });
+    }
+    return segments;
+  }
+  let start = 0;
+  for (const text of Array.from(line)) {
+    segments.push({ start, end: start + text.length });
+    start += text.length;
+  }
+  return segments;
+}
+
+/**
+ * Find target column for a character motion (f/F/t/T).
+ * @returns target column or null if not found
+ */
+export function findCharMotionTarget(
+  line: string,
+  col: number,
+  motion: CharMotion,
+  targetChar: string,
+  isRepeat: boolean = false,
+  count: number = 1,
+): number | null {
+  const isForward = motion === "f" || motion === "t";
+  const isTill = motion === "t" || motion === "T";
+  const steps = Number.isFinite(count) && count > 0 ? Math.floor(count) : 1;
+
+  const graphemes = getLineGraphemes(line);
+  let currentIndex = graphemes.findIndex((g) => col < g.end);
+  if (currentIndex === -1) currentIndex = graphemes.length;
+
+  for (let i = 0; i < steps; i++) {
+    const isFirst = i === 0;
+    const isFinal = i === steps - 1;
+    const tillRepeatOffset = isFirst && isTill && isRepeat ? 1 : 0;
+
+    if (isForward) {
+      const nextIndex = currentIndex + 1 + tillRepeatOffset;
+      let found = -1;
+      for (let j = nextIndex; j < graphemes.length; j++) {
+        const g = graphemes[j];
+        if (!g) continue;
+        // Use startsWith to allow matching base chars if targetChar lacks combining marks,
+        // or just exact match since targetChar is typically a full grapheme.
+        if (
+          line.slice(g.start, g.end) === targetChar ||
+          line.slice(g.start, g.end).startsWith(targetChar)
+        ) {
+          found = j;
+          break;
+        }
+      }
+      if (found === -1) return null;
+      if (isFinal) {
+        const targetGrapheme = graphemes[found];
+        if (!targetGrapheme) return null;
+        if (!isTill) return targetGrapheme.start;
+        const previousGrapheme = graphemes[found - 1];
+        return previousGrapheme ? previousGrapheme.start : null;
+      }
+      currentIndex = found;
+    } else {
+      const nextIndex = currentIndex - 1 - tillRepeatOffset;
+      let found = -1;
+      for (let j = nextIndex; j >= 0; j--) {
+        const g = graphemes[j];
+        if (!g) continue;
+        if (
+          line.slice(g.start, g.end) === targetChar ||
+          line.slice(g.start, g.end).startsWith(targetChar)
+        ) {
+          found = j;
+          break;
+        }
+      }
+      if (found === -1) return null;
+      if (isFinal) {
+        const targetGrapheme = graphemes[found];
+        if (!targetGrapheme) return null;
+        if (!isTill) return targetGrapheme.start;
+        const afterTarget = graphemes[found + 1];
+        return afterTarget ? afterTarget.start : line.length;
+      }
+      currentIndex = found;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Calculate word motion target column.
+ */
+export function findWordMotionTarget(
+  line: string,
+  col: number,
+  direction: "forward" | "backward",
+  target: "start" | "end",
+  semanticClass: WordMotionClass = "word",
+): number {
+  const len = line.length;
+  if (len === 0) return 0;
+
+  let i = Math.max(0, Math.min(col, len));
+
+  if (direction === "forward") {
+    if (i >= len) return len;
+
+    if (target === "start") {
+      // w: move to start of next word
+      const startType = getCharType(line[i], semanticClass);
+
+      // Skip current word/punct block
+      if (startType !== CharType.Space) {
+        while (i < len && getCharType(line[i], semanticClass) === startType)
+          i++;
+      }
+
+      // Skip whitespace
+      while (i < len && getCharType(line[i], semanticClass) === CharType.Space)
+        i++;
+
+      return i;
+    }
+
+    // e: move to end of current/next word
+    if (i < len - 1) i++;
+
+    // Skip whitespace forward
+    while (i < len && getCharType(line[i], semanticClass) === CharType.Space)
+      i++;
+
+    // Now at start of next word (or end of line). Find end.
+    if (i >= len) return len;
+
+    const type = getCharType(line[i], semanticClass);
+    while (i < len - 1 && getCharType(line[i + 1], semanticClass) === type) i++;
+
+    return i;
+  }
+
+  // b: move to start of previous word
+  if (i >= len) i = len - 1;
+  if (i > 0) i--;
+
+  // Skip whitespace backward
+  while (i > 0 && getCharType(line[i], semanticClass) === CharType.Space) i--;
+
+  // Now at end of prev word (or start of line). Find start.
+  const type = getCharType(line[i], semanticClass);
+  while (i > 0 && getCharType(line[i - 1], semanticClass) === type) i--;
+
+  return i;
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@wwwyo/pi-vim",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.14.2",
+  "description": "Vim-style modal editing for Pi's TUI editor",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "vim",
+    "editor"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lajarre/pi-vim.git"
+  },
+  "files": [
+    "*.ts",
+    "!*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "echo 'nothing to build'",
+    "format": "biome check --write .",
+    "lint": "biome check . && eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx/esm --test 'test/**/*.test.ts'",
+    "test:nvim": "node --import tsx/esm --test 'test/nvim-parity*.ts'",
+    "test:e2e": "node --import tsx/esm script/image-attachments-e2e.ts",
+    "test:smoke": "node --import tsx/esm script/consumer-smoke.ts",
+    "check": "npm run lint && npm run typecheck && npm run test",
+    "pack:check": "node --import tsx/esm script/pack-check.ts",
+    "scoreboard": "node --import tsx/esm script/scoreboard.ts",
+    "hooks:install": "lefthook install",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run pack:check && npm test"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.8",
+    "@eslint/js": "^9.25.1",
+    "@types/node": "^24.7.2",
+    "eslint": "^9.25.1",
+    "lefthook": "^2.1.4",
+    "tsx": "^4.19.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.31.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": ">=0.74.0"
+  }
+}