@pi-unipi/input-shortcuts 0.1.1

package/README.md

@@ -0,0 +1,116 @@
+# @pi-unipi/input-shortcuts
+
+Keyboard shortcuts for Pi's input box — stash/restore, undo/redo, clipboard operations, thinking toggle, and tab insertion. All accessible via a vim-style chord overlay triggered by `ALT+S`.
+
+## Features
+
+| Chord | Action | Description |
+|-------|--------|-------------|
+| `ALT+S → S` | Stash/Restore | Save input text to stash register, or restore it |
+| `ALT+S → U` | Undo | Pop from undo buffer (1s throttle) |
+| `ALT+S → R` | Redo | Push current text forward, restore previous |
+| `ALT+S → Y` | Copy | Copy input to system clipboard |
+| `ALT+S → D` | Cut | Copy to clipboard, then clear input |
+| `ALT+S → T` | Toggle Thinking | Cycle: off → low → medium → high → xhigh → off |
+| `ALT+S → A → [0-9]` | Append Register | Append from numbered register 0-9 |
+| `ALT+S → A → S` | Append Stash | Append from stash register |
+| `ALT+I` | Tab Insert | Insert literal tab character into input |
+
+## How It Works
+
+### Chord Overlay
+
+Press `ALT+S` to open a small overlay showing available actions with key hints. Press a single key within the overlay to execute the action. The overlay auto-closes after 300ms of inactivity or on `ESC`.
+
+For the **Append** sub-chord, pressing `A` transitions to a second overlay showing numbered registers `[0-9]` and the stash register `[S]`.
+
+### Registers
+
+- **Stash register**: 1 register for quick save/restore of input text
+- **Numbered registers**: 10 registers (0-9) for appending stored text snippets
+- **Persistence**: All registers saved to `.unipi/config/input-shortcuts.json` (per-project, atomic writes)
+
+### Undo/Redo
+
+- In-memory ring buffer, max 50 snapshots per session
+- **500ms debounce** on snapshot creation (prevents noise from rapid typing)
+- **1s throttle** on undo (prevents rapid-fire undo)
+- Redo buffer cleared on new snapshot (standard undo/redo semantics)
+- Not persisted across sessions
+
+### Clipboard
+
+Cross-platform clipboard detection with automatic fallback:
+
+| Platform | Read | Write |
+|----------|------|-------|
+| Linux (X11) | `xclip -selection clipboard -o` | `xclip -selection clipboard` |
+| Linux (alt) | `xsel --clipboard --output` | `xsel --clipboard --input` |
+| macOS | `pbpaste` | `pbcopy` |
+| Windows | `powershell Get-Clipboard` | `clip` / `powershell Set-Clipboard` |
+
+Detected tool is cached after first use. Returns graceful error if no clipboard tool is available.
+
+### Thinking Toggle
+
+Cycles through Pi's thinking levels in order:
+
+```
+off → low → medium → high → xhigh → off
+```
+
+## Settings
+
+Run `/unipi:stash-settings` to open a TUI overlay for customizing keybindings:
+
+- **Chord trigger key** — default `alt+s`
+- **Tab insert key** — default `alt+i`
+
+Both cycle through available ALT key combinations, excluding known conflicts (`alt+e` = cursorWordRight).
+
+Config persisted to `~/.unipi/config/input-shortcuts-config.json` (global).
+
+## Architecture
+
+```
+input-shortcuts/
+├── index.ts              # Re-exports
+├── src/
+│   ├── index.ts          # Extension entry — registers shortcuts + command
+│   ├── types.ts          # Shared types and constants
+│   ├── registers.ts      # RegisterStore — JSON persistence with atomic writes
+│   ├── undo-redo.ts      # UndoRedoBuffer — ring buffer with debounce/throttle
+│   ├── clipboard.ts      # Cross-platform clipboard detection + read/write
+│   ├── status.ts         # Status bar feedback with auto-clear
+│   ├── chord-overlay.ts  # ChordOverlay — TUI overlay component (root + register sub-chord)
+│   └── settings-overlay.ts # SettingsOverlay — SettingsList-based config UI
+├── tests/
+│   ├── clipboard.test.ts
+│   ├── registers.test.ts
+│   └── undo-redo.test.ts
+└── package.json
+```
+
+### Key Patterns
+
+- **TUI overlay**: Uses `ctx.ui.custom()` from pi-coding-agent (proven pattern from btw, compactor, footer)
+- **SettingsList**: Uses `SettingsList` from pi-tui for the settings overlay
+- **Atomic writes**: All file persistence uses write-to-tmp-then-rename pattern
+- **Status feedback**: Every action shows a brief success/error message in the status bar via `ctx.ui.setStatus()`
+
+## Testing
+
+```bash
+npm test --workspace=packages/input-shortcuts
+```
+
+19 tests across 3 suites:
+- **clipboard** (4 tests): detection fallback, copy/paste roundtrip, graceful errors
+- **RegisterStore** (8 tests): load/create, read/write stash/registers, corruption handling, atomic writes
+- **UndoRedoBuffer** (7 tests): undo/redo roundtrip, debounce, throttle, max size eviction, clear
+
+## Dependencies
+
+- `@pi-unipi/core` — shared constants and utilities
+- `@mariozechner/pi-coding-agent` — ExtensionAPI, ExtensionContext
+- `@mariozechner/pi-tui` — Key, Container, Text, SettingsList, Focusable

package/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @pi-unipi/input-shortcuts — Re-exports
+ */
+
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pi-unipi/input-shortcuts",
+  "version": "0.1.1",
+  "description": "Keyboard shortcuts for stash/restore, undo/redo, clipboard, and thinking toggle — chord-based overlay system",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/input-shortcuts"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "input-shortcuts",
+    "stash",
+    "undo",
+    "clipboard"
+  ],
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/**/*.test.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.0"
+  }
+}

package/src/chord-overlay.ts

@@ -0,0 +1,235 @@
+/**
+ * TUI overlay component for ALT+S chord mode.
+ *
+ * Two states: root chord (action menu) and register sub-chord (register list).
+ * Uses ctx.ui.custom() pattern from btw/compactor.
+ *
+ * IMPORTANT: The overlay ONLY captures the user's action selection.
+ * Actions are NOT executed inside the overlay — they are deferred to the
+ * caller via callbacks (onStash, onUndo, etc.). The caller closes the
+ * overlay via done(), then executes the action outside the overlay context
+ * where ctx.ui.getEditorText() / setEditorText() actually work.
+ *
+ * Closes on ESC or after selecting an action. No timeout.
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  Container,
+  Key,
+  matchesKey,
+  Text,
+  type Focusable,
+  type TUI,
+  type KeybindingsManager,
+} from "@mariozechner/pi-tui";
+import type { ChordState } from "./types.ts";
+import { THINKING_CYCLE } from "./types.ts";
+
+/** Theme-like interface matching pi-coding-agent's Theme */
+interface ThemeLike {
+  fg(color: string, text: string): string;
+  bg?(color: string, text: string): string;
+  bold?(text: string): string;
+  italic?(text: string): string;
+}
+
+/** Action callbacks — actions execute OUTSIDE the overlay context */
+export interface ChordCallbacks {
+  onStash: () => void;
+  onUndo: () => void;
+  onRedo: () => void;
+  onAppendRegister: (index: number) => void;
+  onAppendStash: () => void;
+  onCopy: () => void;
+  onCut: () => void;
+  onToggleThinking: () => void;
+}
+
+// ─── Action menu lines ──────────────────────────────────────────────────────
+
+const ROOT_ACTIONS: Array<{ key: string; label: string }> = [
+  { key: "S", label: "Stash / Restore" },
+  { key: "U", label: "Undo" },
+  { key: "R", label: "Redo" },
+  { key: "A", label: "Append from register" },
+  { key: "Y", label: "Copy to clipboard" },
+  { key: "D", label: "Cut to clipboard" },
+  { key: "T", label: "Toggle thinking" },
+];
+
+function buildRegisterActions(): Array<{ key: string; label: string }> {
+  const actions: Array<{ key: string; label: string }> = [];
+  for (let i = 0; i <= 9; i++) {
+    actions.push({ key: String(i), label: `Register ${i}` });
+  }
+  actions.push({ key: "S", label: "Stash register" });
+  return actions;
+}
+
+// ─── ChordOverlay Component ─────────────────────────────────────────────────
+
+export class ChordOverlay extends Container implements Focusable {
+  private _focused = true;
+  private state: ChordState = "chord_root";
+  private actionLines: Text[] = [];
+  private tui: TUI;
+  private theme: ThemeLike;
+  private done: () => void;
+  private callbacks: ChordCallbacks;
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+  }
+
+  constructor(
+    tui: TUI,
+    theme: ThemeLike,
+    _keybindings: KeybindingsManager,
+    done: () => void,
+    callbacks: ChordCallbacks,
+  ) {
+    super();
+    this.tui = tui;
+    this.theme = theme;
+    this.done = done;
+    this.callbacks = callbacks;
+
+    this.renderRootMenu();
+  }
+
+  private renderRootMenu(): void {
+    this.state = "chord_root";
+    this.actionLines = ROOT_ACTIONS.map(
+      (a) => new Text(`  ${this.theme.fg("accent", `[${a.key}]`)} ${a.label}`, 1, 0),
+    );
+    this.requestRender();
+  }
+
+  private renderRegisterMenu(): void {
+    this.state = "chord_reg";
+    const regActions = buildRegisterActions();
+    this.actionLines = regActions.map(
+      (a) => new Text(`  ${this.theme.fg("accent", `[${a.key}]`)} ${a.label}`, 1, 0),
+    );
+    this.requestRender();
+  }
+
+  private requestRender(): void {
+    this.tui.requestRender();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.escape)) {
+      this.close();
+      return;
+    }
+
+    const key = data.toLowerCase();
+
+    if (this.state === "chord_root") {
+      this.handleRootKey(key);
+    } else if (this.state === "chord_reg") {
+      this.handleRegKey(key);
+    }
+  }
+
+  private handleRootKey(key: string): void {
+    switch (key) {
+      case "s":
+        this.closeThenExecute(() => this.callbacks.onStash());
+        break;
+      case "u":
+        this.closeThenExecute(() => this.callbacks.onUndo());
+        break;
+      case "r":
+        this.closeThenExecute(() => this.callbacks.onRedo());
+        break;
+      case "a":
+        this.enterRegChord();
+        return; // don't close — show register sub-menu
+      case "y":
+        this.closeThenExecute(() => this.callbacks.onCopy());
+        break;
+      case "d":
+        this.closeThenExecute(() => this.callbacks.onCut());
+        break;
+      case "t":
+        this.closeThenExecute(() => this.callbacks.onToggleThinking());
+        break;
+      default:
+        // Unknown key — silent close
+        this.close();
+        break;
+    }
+  }
+
+  private handleRegKey(key: string): void {
+    if (key === "s") {
+      this.closeThenExecute(() => this.callbacks.onAppendStash());
+    } else if (/^[0-9]$/.test(key)) {
+      const index = parseInt(key, 10);
+      this.closeThenExecute(() => this.callbacks.onAppendRegister(index));
+    } else {
+      // Unknown key — silent close
+      this.close();
+    }
+  }
+
+  private enterRegChord(): void {
+    this.renderRegisterMenu();
+  }
+
+  /**
+   * Close the overlay, then execute the action.
+   * The action runs AFTER the overlay is dismissed, so ctx.ui.getEditorText()
+   * and setEditorText() work correctly (they don't work while overlay is open).
+   */
+  private closeThenExecute(action: () => void): void {
+    this.done(); // close the overlay
+    // Use setTimeout(0) to defer action to next tick — overlay will be dismissed by then
+    setTimeout(action, 0);
+  }
+
+  // ─── Cleanup ───────────────────────────────────────────────────────────────
+
+  private close(): void {
+    this.done();
+  }
+
+  dispose(): void {}
+
+  render(width: number): string[] {
+    const dialogWidth = Math.min(40, Math.max(28, width));
+    const innerWidth = dialogWidth - 2;
+
+    const lines: string[] = [];
+
+    // Top border
+    lines.push(this.theme.fg("borderMuted", `┌${"─".repeat(innerWidth)}┐`));
+
+    // Title
+    const title = this.state === "chord_root" ? "Input Shortcuts" : "Append from register";
+    const titlePadded = title.padEnd(innerWidth);
+    lines.push(`${this.theme.fg("borderMuted", "│")}${this.theme.fg("accent", titlePadded)}${this.theme.fg("borderMuted", "│")}`);
+
+    // Separator
+    lines.push(this.theme.fg("borderMuted", `├${"─".repeat(innerWidth)}┤`));
+
+    // Action lines
+    for (const line of this.actionLines) {
+      const rendered = line.render(innerWidth)[0] ?? "";
+      const padded = rendered.padEnd(innerWidth);
+      lines.push(`${this.theme.fg("borderMuted", "│")}${padded}${this.theme.fg("borderMuted", "│")}`);
+    }
+
+    // Bottom border
+    lines.push(this.theme.fg("borderMuted", `└${"─".repeat(innerWidth)}┘`));
+
+    return lines;
+  }
+}

package/src/clipboard.ts

@@ -0,0 +1,119 @@
+/**
+ * Cross-platform clipboard read/write using child_process.
+ * Detection order: xclip → xsel → pbcopy/pbpaste → clip/powershell.
+ * Caches detected command on first use.
+ */
+
+import { execSync } from "node:child_process";
+
+export interface ClipboardResult {
+  ok: boolean;
+  text?: string;
+  reason?: string;
+}
+
+type ClipboardTool = "xclip" | "xsel" | "pbcopy" | "clip" | "powershell" | null;
+
+let cachedTool: ClipboardTool | undefined; // undefined = not yet detected
+
+/**
+ * Detect available clipboard command. Caches result.
+ */
+export function detectClipboard(): ClipboardTool {
+  if (cachedTool !== undefined) return cachedTool;
+
+  const tools: Array<{ name: ClipboardTool; test: string }> = [
+    { name: "xclip", test: "xclip -selection clipboard -o" },
+    { name: "xsel", test: "xsel --clipboard --output" },
+    { name: "pbcopy", test: "pbpaste" },
+    { name: "clip", test: "echo test | clip" },
+    { name: "powershell", test: "powershell -command Get-Clipboard" },
+  ];
+
+  for (const tool of tools) {
+    try {
+      execSync(tool.test, { stdio: "ignore", timeout: 2000 });
+      cachedTool = tool.name;
+      return cachedTool;
+    } catch {
+      // Try next tool
+    }
+  }
+
+  cachedTool = null;
+  return null;
+}
+
+/**
+ * Copy text to system clipboard.
+ */
+export function copyToClipboard(text: string): ClipboardResult {
+  const tool = detectClipboard();
+  if (!tool) return { ok: false, reason: "clipboard unavailable" };
+
+  try {
+    switch (tool) {
+      case "xclip":
+        execSync("xclip -selection clipboard", { input: text, timeout: 2000 });
+        break;
+      case "xsel":
+        execSync("xsel --clipboard --input", { input: text, timeout: 2000 });
+        break;
+      case "pbcopy":
+        execSync("pbcopy", { input: text, timeout: 2000 });
+        break;
+      case "clip":
+        execSync("clip", { input: text, timeout: 2000 });
+        break;
+      case "powershell":
+        execSync(`powershell -command "Set-Clipboard -Value '${text.replace(/'/g, "''")}'"`, { timeout: 2000 });
+        break;
+    }
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: "clipboard write failed" };
+  }
+}
+
+/**
+ * Read text from system clipboard.
+ */
+export function pasteFromClipboard(): ClipboardResult {
+  const tool = detectClipboard();
+  if (!tool) return { ok: false, reason: "clipboard unavailable" };
+
+  try {
+    let text: string;
+    switch (tool) {
+      case "xclip":
+        text = execSync("xclip -selection clipboard -o", { encoding: "utf-8", timeout: 2000 }).trimEnd();
+        break;
+      case "xsel":
+        text = execSync("xsel --clipboard --output", { encoding: "utf-8", timeout: 2000 }).trimEnd();
+        break;
+      case "pbcopy":
+        // pbcopy is write-only; use pbpaste for reading
+        text = execSync("pbpaste", { encoding: "utf-8", timeout: 2000 }).trimEnd();
+        break;
+      case "clip":
+        // clip is write-only on Windows; use powershell for reading
+        text = execSync("powershell -command Get-Clipboard", { encoding: "utf-8", timeout: 2000 }).trimEnd();
+        break;
+      case "powershell":
+        text = execSync("powershell -command Get-Clipboard", { encoding: "utf-8", timeout: 2000 }).trimEnd();
+        break;
+      default:
+        return { ok: false, reason: "clipboard unavailable" };
+    }
+    return { ok: true, text };
+  } catch {
+    return { ok: false, reason: "clipboard read failed" };
+  }
+}
+
+/**
+ * Reset cached tool detection (for testing).
+ */
+export function resetClipboardCache(): void {
+  cachedTool = undefined;
+}

package/src/index.ts

@@ -0,0 +1,411 @@
+/**
+ * @pi-unipi/input-shortcuts — Extension entry point
+ *
+ * Registers ALT+S (chord overlay) and ALT+I (tab insert) shortcuts.
+ * Provides /unipi:stash-settings command for keybinding customization.
+ *
+ * ARCHITECTURE:
+ * - The overlay ONLY captures action selection (pure UI, no side effects)
+ * - All actions execute OUTSIDE the overlay via callbacks after done()
+ * - Undo works via onTerminalInput: snapshots text before each keypress
+ * - Cut/Copy: overlay closes immediately, then action runs (non-blocking)
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Key } from "@mariozechner/pi-tui";
+import { MODULES, emitEvent, UNIPI_EVENTS, INPUT_SHORTCUTS_COMMANDS } from "@pi-unipi/core";
+import { RegisterStore } from "./registers.ts";
+import { UndoRedoBuffer } from "./undo-redo.ts";
+import { ChordOverlay, type ChordCallbacks } from "./chord-overlay.ts";
+import { SettingsOverlay } from "./settings-overlay.ts";
+import { loadConfig } from "./settings-overlay.ts";
+import { copyToClipboard } from "./clipboard.ts";
+
+// ─── Status feedback ────────────────────────────────────────────────────────
+
+const STATUS_KEY = "input-shortcuts";
+const STATUS_SUCCESS_MS = 2000;
+const STATUS_ERROR_MS = 3000;
+
+function showSuccess(ctx: ExtensionContext, text: string): void {
+  ctx.ui.setStatus(STATUS_KEY, text);
+  setTimeout(() => {
+    try { ctx.ui.setStatus(STATUS_KEY, undefined); } catch {}
+  }, STATUS_SUCCESS_MS);
+}
+
+function showError(ctx: ExtensionContext, text: string): void {
+  ctx.ui.setStatus(STATUS_KEY, text);
+  setTimeout(() => {
+    try { ctx.ui.setStatus(STATUS_KEY, undefined); } catch {}
+  }, STATUS_ERROR_MS);
+}
+
+// ─── Extension ──────────────────────────────────────────────────────────────
+
+export default function inputShortcutsExtension(pi: ExtensionAPI): void {
+  // Shared state
+  const registers = new RegisterStore();
+  const undoRedo = new UndoRedoBuffer();
+
+  // Persistent UI reference (captured on first handler call, persists for session)
+  let ui: ExtensionContext["ui"] | null = null;
+  let inputListenerRegistered = false;
+  let suppressInputListener = false; // set during undo/redo to prevent self-referencing snapshots
+
+  // ─── Text change detection via onTerminalInput ────────────────────────
+  // Snapshots the editor text BEFORE each keypress, enabling undo for typed text.
+  //
+  // Three independent triggers commit a snapshot (they don't conflict):
+  //   1. Pause: user stops typing for 500ms → snapshot the text before this typing session
+  //   2. Count: user types 20+ characters since last snapshot → snapshot mid-typing
+  //   3. Time: 3 seconds elapsed since last snapshot (even if still typing) → snapshot
+  //
+  // How it works:
+  //   - On each keypress, capture text BEFORE the editor processes it
+  //   - `pendingSnapshot` = text before the current typing session started (first keypress)
+  //   - `keystrokeCount` = how many edit keys pressed since last snapshot
+  //   - `lastSnapshotAt` = timestamp of last snapshot commit
+  //   - 500ms timer resets on each keypress (fires only on pause)
+  //
+  // Example: user types "hello world" continuously:
+  //   - Key 1: pendingSnapshot = "", count=1
+  //   - Key 10: count=10 (no trigger yet)
+  //   - Key 20: count=20 → COMMIT snapshot="", reset. Now pendingSnapshot=current
+  //   - User pauses 500ms → COMMIT snapshot=current, reset
+  //
+  // Example: user types slowly (1 char per second):
+  //   - Key 1: pendingSnapshot="", count=1, timer starts
+  //   - Key 2 (1s later): timer was reset, count=2
+  //   - ... (timer fires after each pause between keys)
+  //   - Each pause triggers a snapshot
+
+  let pendingSnapshot: string | null = null;
+  let keystrokeCount = 0;
+  let lastSnapshotAt = 0;
+  let snapshotTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const SNAPSHOT_PAUSE_MS = 500;    // pause trigger
+  const SNAPSHOT_COUNT_THRESHOLD = 20; // character count trigger
+  const SNAPSHOT_TIME_MS = 3000;    // time trigger
+
+  /** Commit the pending snapshot and reset all tracking state. */
+  function commitSnapshot(): void {
+    if (pendingSnapshot !== null) {
+      undoRedo.snapshot(pendingSnapshot);
+    }
+    pendingSnapshot = null;
+    keystrokeCount = 0;
+    lastSnapshotAt = Date.now();
+    if (snapshotTimer) {
+      clearTimeout(snapshotTimer);
+      snapshotTimer = null;
+    }
+  }
+
+  function setupInputListener(): void {
+    if (inputListenerRegistered || !ui) return;
+    inputListenerRegistered = true;
+
+    ui.onTerminalInput((data: string) => {
+      if (!ui || suppressInputListener) return;
+
+      // Only snapshot for edit keys (printable, backspace, delete, enter)
+      const isEditKey = data.length === 1 || data === "\x7f" || data === "\x1b[3~" || data === "\r" || data === "\n";
+      if (!isEditKey) return;
+
+      // Capture text BEFORE the keypress is processed by the editor
+      const textBefore = ui.getEditorText();
+
+      // On first keypress of a new session, store the pending snapshot
+      if (pendingSnapshot === null) {
+        pendingSnapshot = textBefore;
+        lastSnapshotAt = Date.now();
+      }
+
+      keystrokeCount++;
+
+      // ─── Trigger 1: Character count threshold (20 chars) ─────────
+      if (keystrokeCount >= SNAPSHOT_COUNT_THRESHOLD) {
+        commitSnapshot();
+        // Don't return — let the pause timer restart below
+      }
+
+      // ─── Trigger 2: Time threshold (3 seconds) ───────────────────
+      if (pendingSnapshot !== null && Date.now() - lastSnapshotAt >= SNAPSHOT_TIME_MS) {
+        commitSnapshot();
+      }
+
+      // ─── Trigger 3: Pause timer (500ms after last keypress) ──────
+      // Reset the pause timer on each keypress
+      if (snapshotTimer) {
+        clearTimeout(snapshotTimer);
+      }
+      snapshotTimer = setTimeout(() => {
+        // User stopped typing — commit the snapshot
+        if (pendingSnapshot !== null) {
+          commitSnapshot();
+        }
+      }, SNAPSHOT_PAUSE_MS);
+    });
+  }
+
+  // ─── Action implementations ───────────────────────────────────────────
+  // These run OUTSIDE the overlay — editor API is fully accessible.
+
+  function doStash(ctx: ExtensionContext): void {
+    const text = ctx.ui.getEditorText();
+    if (text.length > 0) {
+      undoRedo.snapshot(text); // snapshot before clearing
+      registers.setStash(text);
+      ctx.ui.setEditorText("");
+      showSuccess(ctx, "✓ stash saved");
+    } else {
+      const stash = registers.getStash();
+      if (stash.length === 0) {
+        showError(ctx, "stash empty");
+        return;
+      }
+      undoRedo.snapshot(""); // snapshot empty state before restoring
+      ctx.ui.setEditorText(stash);
+      showSuccess(ctx, "✓ stash restored");
+    }
+  }
+
+  function doUndo(ctx: ExtensionContext): void {
+    suppressInputListener = true;
+    const current = ctx.ui.getEditorText();
+    const result = undoRedo.undo(current);
+    if (result.ok) {
+      ctx.ui.setEditorText(result.text);
+      showSuccess(ctx, "✓ undo");
+    } else {
+      showError(ctx, "nothing to undo");
+    }
+    suppressInputListener = false;
+  }
+
+  function doRedo(ctx: ExtensionContext): void {
+    suppressInputListener = true;
+    const current = ctx.ui.getEditorText();
+    const result = undoRedo.redo(current);
+    if (result.ok) {
+      ctx.ui.setEditorText(result.text);
+      showSuccess(ctx, "✓ redo");
+    } else {
+      showError(ctx, "nothing to redo");
+    }
+    suppressInputListener = false;
+  }
+
+  function doAppendRegister(ctx: ExtensionContext, index: number): void {
+    const regText = registers.getRegister(index);
+    if (regText.length === 0) {
+      showError(ctx, `register ${index} empty`);
+      return;
+    }
+    const current = ctx.ui.getEditorText();
+    undoRedo.snapshot(current);
+    ctx.ui.setEditorText(current + regText);
+    showSuccess(ctx, `✓ register ${index} appended`);
+  }
+
+  function doAppendStash(ctx: ExtensionContext): void {
+    const stashText = registers.getStash();
+    if (stashText.length === 0) {
+      showError(ctx, "stash empty");
+      return;
+    }
+    const current = ctx.ui.getEditorText();
+    undoRedo.snapshot(current);
+    ctx.ui.setEditorText(current + stashText);
+    showSuccess(ctx, "✓ stash appended");
+  }
+
+  function doCopy(ctx: ExtensionContext): void {
+    const text = ctx.ui.getEditorText();
+    if (text.length === 0) {
+      showError(ctx, "nothing to copy");
+      return;
+    }
+    const result = copyToClipboard(text);
+    if (result.ok) {
+      showSuccess(ctx, "✓ copied");
+    } else {
+      showError(ctx, result.reason ?? "clipboard unavailable");
+    }
+  }
+
+  function doCut(ctx: ExtensionContext): void {
+    const text = ctx.ui.getEditorText();
+    if (text.length === 0) {
+      showError(ctx, "nothing to cut");
+      return;
+    }
+    const result = copyToClipboard(text);
+    if (result.ok) {
+      undoRedo.snapshot(text); // snapshot before clearing
+      ctx.ui.setEditorText("");
+      showSuccess(ctx, "✓ cut");
+    } else {
+      showError(ctx, result.reason ?? "clipboard unavailable");
+    }
+  }
+
+  function doToggleThinking(): void {
+    const current = pi.getThinkingLevel();
+    const THINKING_CYCLE = ["off", "low", "medium", "high", "xhigh"] as const;
+    const idx = THINKING_CYCLE.indexOf(current as any);
+    const nextIdx = idx >= 0 ? (idx + 1) % THINKING_CYCLE.length : 0;
+    const next = THINKING_CYCLE[nextIdx];
+    pi.setThinkingLevel(next as any);
+    // Note: no ctx available here for status, but thinking level is visible in UI
+  }
+
+  // ─── Register ALT+S shortcut — opens chord overlay ─────────────────────
+
+  pi.registerShortcut(Key.alt("s"), {
+    description: "Input shortcuts — stash, undo, redo, copy, cut, toggle thinking",
+    handler: async (ctx: ExtensionContext) => {
+      if (!ctx.hasUI) return;
+
+      // Capture persistent UI reference and setup input listener (once)
+      if (!ui) {
+        ui = ctx.ui;
+        setupInputListener();
+      }
+
+      // Suppress input listener while overlay is open.
+      // The onTerminalInput handler fires for the ALT+S keypress itself,
+      // capturing the current text as a pending snapshot. If we don't suppress,
+      // that snapshot would be committed after undo runs, creating a "undo undoes undo" loop.
+      suppressInputListener = true;
+      if (snapshotTimer) { clearTimeout(snapshotTimer); snapshotTimer = null; }
+      pendingSnapshot = null;
+      keystrokeCount = 0;
+
+      void ctx.ui.custom<void>(
+        async (tui, theme, keybindings, done) => {
+          const wrappedDone = () => {
+            suppressInputListener = false;
+            done();
+          };
+
+          const callbacks: ChordCallbacks = {
+            onStash: () => doStash(ctx),
+            onUndo: () => doUndo(ctx),
+            onRedo: () => doRedo(ctx),
+            onAppendRegister: (index) => doAppendRegister(ctx, index),
+            onAppendStash: () => doAppendStash(ctx),
+            onCopy: () => doCopy(ctx),
+            onCut: () => doCut(ctx),
+            onToggleThinking: () => doToggleThinking(),
+          };
+
+          return new ChordOverlay(tui, theme, keybindings, wrappedDone, callbacks);
+        },
+        {
+          overlay: true,
+          overlayOptions: {
+            width: 42,
+            maxHeight: 20,
+            anchor: "top-center",
+            margin: { top: 2, left: 2, right: 2 },
+          },
+        },
+      );
+    },
+  });
+
+  // ─── Register ALT+I shortcut — insert tab ──────────────────────────────
+
+  pi.registerShortcut(Key.alt("i"), {
+    description: "Insert tab character into input",
+    handler: async (ctx: ExtensionContext) => {
+      const text = ctx.ui.getEditorText();
+      ctx.ui.setEditorText(text + "\t");
+    },
+  });
+
+  // ─── Register /unipi:stash-settings command ────────────────────────────
+
+  pi.registerCommand(`unipi:${INPUT_SHORTCUTS_COMMANDS.STASH_SETTINGS}`, {
+    description: "Open input shortcuts settings overlay to customize keybindings",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      if (!ctx.hasUI) return;
+
+      void ctx.ui.custom<void>(
+        async (_tui, _theme, _keybindings, done) => {
+          return new SettingsOverlay(done);
+        },
+        {
+          overlay: true,
+          overlayOptions: {
+            width: "60%",
+            minWidth: 40,
+            maxHeight: "50%",
+            anchor: "top-center",
+            margin: { top: 2, left: 2, right: 2 },
+          },
+        },
+      );
+    },
+  });
+
+  // ─── Session lifecycle ─────────────────────────────────────────────────
+
+  pi.on("session_shutdown", async () => {
+    if (snapshotTimer) {
+      clearTimeout(snapshotTimer);
+      snapshotTimer = null;
+    }
+    pendingSnapshot = null;
+    keystrokeCount = 0;
+    lastSnapshotAt = 0;
+    undoRedo.clear();
+  });
+
+  // ─── Info-screen registration ────────────────────────────────────────────
+
+  const globalObj = globalThis as any;
+  const registry = globalObj.__unipi_info_registry;
+  if (registry) {
+    registry.registerGroup({
+      id: "input-shortcuts",
+      name: "Input Shortcuts",
+      icon: "⌨️",
+      priority: 115,
+      config: {
+        showByDefault: true,
+        stats: [
+          { id: "chordKey", label: "Chord key", show: true },
+          { id: "tabInsertKey", label: "Tab insert key", show: true },
+          { id: "registersUsed", label: "Registers used", show: true },
+          { id: "stashStatus", label: "Stash", show: true },
+        ],
+      },
+      dataProvider: async () => {
+        const config = loadConfig();
+        let used = 0;
+        for (let i = 0; i <= 9; i++) {
+          if (registers.getRegister(i).length > 0) used++;
+        }
+        return {
+          chordKey: { value: config.chordKey, detail: "Key to open shortcuts overlay" },
+          tabInsertKey: { value: config.tabInsertKey, detail: "Key to insert tab" },
+          registersUsed: { value: `${used}/10`, detail: "Non-empty numbered registers" },
+          stashStatus: { value: registers.getStash().length > 0 ? "set" : "empty", detail: "Stash register" },
+        };
+      },
+    });
+  }
+
+  // ─── Module ready event ──────────────────────────────────────────────────
+
+  emitEvent(pi as any, UNIPI_EVENTS.MODULE_READY, {
+    name: MODULES.INPUT_SHORTCUTS,
+    version: "0.1.0",
+    commands: [`unipi:${INPUT_SHORTCUTS_COMMANDS.STASH_SETTINGS}`],
+    tools: [],
+  });
+}

package/src/registers.ts

@@ -0,0 +1,92 @@
+/**
+ * Register store with JSON file persistence.
+ * 10 numbered registers (0-9) + 1 stash register (S).
+ * File: .unipi/config/input-shortcuts.json
+ * Atomic writes (write to .tmp then rename).
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { RegisterData } from "./types.ts";
+import { REGISTERS_FILE } from "./types.ts";
+
+const EMPTY_DATA: RegisterData = {
+  stash: "",
+  registers: ["", "", "", "", "", "", "", "", "", ""],
+};
+
+export class RegisterStore {
+  private data: RegisterData | null = null;
+  private filePath: string;
+  private loaded = false;
+
+  constructor(baseDir?: string) {
+    this.filePath = baseDir ? join(baseDir, REGISTERS_FILE) : REGISTERS_FILE;
+  }
+
+  /** Get the stash register contents. */
+  getStash(): string {
+    this.ensureLoaded();
+    return this.data!.stash;
+  }
+
+  /** Set the stash register contents and persist. */
+  setStash(text: string): void {
+    this.ensureLoaded();
+    this.data!.stash = text;
+    this.save();
+  }
+
+  /** Get a numbered register (0-9). */
+  getRegister(index: number): string {
+    if (index < 0 || index > 9) return "";
+    this.ensureLoaded();
+    return this.data!.registers[index] ?? "";
+  }
+
+  /** Set a numbered register (0-9) and persist. */
+  setRegister(index: number, text: string): void {
+    if (index < 0 || index > 9) return;
+    this.ensureLoaded();
+    this.data!.registers[index] = text;
+    this.save();
+  }
+
+  /** Lazy load from disk on first access. */
+  private ensureLoaded(): void {
+    if (this.loaded) return;
+    this.loaded = true;
+
+    try {
+      if (existsSync(this.filePath)) {
+        const raw = readFileSync(this.filePath, "utf-8");
+        const parsed = JSON.parse(raw) as Partial<RegisterData>;
+        this.data = {
+          stash: typeof parsed.stash === "string" ? parsed.stash : "",
+          registers: Array.isArray(parsed.registers) && parsed.registers.length === 10
+            ? parsed.registers.map((r) => (typeof r === "string" ? r : ""))
+            : [...EMPTY_DATA.registers],
+        };
+      } else {
+        this.data = { ...EMPTY_DATA, registers: [...EMPTY_DATA.registers] };
+      }
+    } catch {
+      this.data = { ...EMPTY_DATA, registers: [...EMPTY_DATA.registers] };
+    }
+  }
+
+  /** Atomic write: write to .tmp then rename. */
+  private save(): void {
+    try {
+      const dir = dirname(this.filePath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      const tmpPath = this.filePath + ".tmp";
+      writeFileSync(tmpPath, JSON.stringify(this.data, null, 2), "utf-8");
+      renameSync(tmpPath, this.filePath);
+    } catch {
+      // Silent fail — register persistence is best-effort
+    }
+  }
+}

package/src/settings-overlay.ts

@@ -0,0 +1,142 @@
+/**
+ * Settings TUI overlay for customizing shortcut keybindings.
+ * Uses SettingsList from pi-tui following compactor pattern.
+ * Persists config to .unipi/config/input-shortcuts-config.json.
+ */
+
+import type { Component } from "@mariozechner/pi-tui";
+import { SettingsList, type SettingItem, type SettingsListTheme } from "@mariozechner/pi-tui";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { InputShortcutsConfig } from "./types.ts";
+import { CONFIG_FILE, DEFAULT_CONFIG } from "./types.ts";
+
+// ─── Available ALT key options ───────────────────────────────────────────────
+
+const ALT_KEY_OPTIONS = [
+  "alt+a", "alt+b", "alt+c", "alt+d", "alt+e", "alt+f", "alt+g",
+  "alt+h", "alt+i", "alt+j", "alt+k", "alt+l", "alt+m", "alt+n",
+  "alt+o", "alt+p", "alt+q", "alt+r", "alt+s", "alt+t", "alt+u",
+  "alt+v", "alt+w", "alt+x", "alt+y", "alt+z",
+];
+
+// Known conflicts — exclude from options
+const CONFLICTS = new Set(["alt+e"]); // alt+e = cursorWordRight
+
+const FREE_ALT_KEYS = ALT_KEY_OPTIONS.filter((k) => !CONFLICTS.has(k));
+
+// ─── Config persistence ─────────────────────────────────────────────────────
+
+/** Load config from disk, returns defaults if missing. */
+export function loadConfig(baseDir?: string): InputShortcutsConfig {
+  const filePath = baseDir ? join(baseDir, CONFIG_FILE) : CONFIG_FILE;
+  try {
+    if (existsSync(filePath)) {
+      const raw = readFileSync(filePath, "utf-8");
+      const parsed = JSON.parse(raw) as Partial<InputShortcutsConfig>;
+      return {
+        chordKey: typeof parsed.chordKey === "string" ? parsed.chordKey : DEFAULT_CONFIG.chordKey,
+        tabInsertKey: typeof parsed.tabInsertKey === "string" ? parsed.tabInsertKey : DEFAULT_CONFIG.tabInsertKey,
+      };
+    }
+  } catch {
+    // Fall through to defaults
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/** Save config to disk with atomic write. */
+export function saveConfig(config: InputShortcutsConfig, baseDir?: string): void {
+  const filePath = baseDir ? join(baseDir, CONFIG_FILE) : CONFIG_FILE;
+  try {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    const tmpPath = filePath + ".tmp";
+    writeFileSync(tmpPath, JSON.stringify(config, null, 2), "utf-8");
+    renameSync(tmpPath, filePath);
+  } catch {
+    // Silent fail — config persistence is best-effort
+  }
+}
+
+// ─── SettingsOverlay Component ──────────────────────────────────────────────
+
+const THEME: SettingsListTheme = {
+  label: (text, selected) => (selected ? `\x1b[1;36m${text}\x1b[0m` : text),
+  value: (text, selected) => (selected ? `\x1b[1;33m${text}\x1b[0m` : `\x1b[33m${text}\x1b[0m`),
+  description: (text) => `\x1b[2m${text}\x1b[0m`,
+  cursor: "▸ ",
+  hint: (text) => `\x1b[2m${text}\x1b[0m`,
+};
+
+export class SettingsOverlay implements Component {
+  private list: SettingsList;
+  private config: InputShortcutsConfig;
+  private baseDir?: string;
+  private onSaved?: (config: InputShortcutsConfig) => void;
+
+  constructor(
+    done: () => void,
+    baseDir?: string,
+    onSaved?: (config: InputShortcutsConfig) => void,
+  ) {
+    this.baseDir = baseDir;
+    this.onSaved = onSaved;
+    this.config = loadConfig(baseDir);
+
+    const items = this.buildItems();
+    this.list = new SettingsList(
+      items,
+      10,
+      THEME,
+      (id, newValue) => this.handleChange(id, newValue),
+      () => {
+        saveConfig(this.config, this.baseDir);
+        this.onSaved?.(this.config);
+        done();
+      },
+    );
+  }
+
+  private buildItems(): SettingItem[] {
+    return [
+      {
+        id: "chordKey",
+        label: "Chord trigger key",
+        description: "Key to open the input shortcuts overlay",
+        currentValue: this.config.chordKey,
+        values: FREE_ALT_KEYS,
+      },
+      {
+        id: "tabInsertKey",
+        label: "Tab insert key",
+        description: "Key to insert a literal tab character",
+        currentValue: this.config.tabInsertKey,
+        values: FREE_ALT_KEYS,
+      },
+    ];
+  }
+
+  private handleChange(id: string, newValue: string): void {
+    if (id === "chordKey") {
+      this.config.chordKey = newValue;
+    } else if (id === "tabInsertKey") {
+      this.config.tabInsertKey = newValue;
+    }
+    this.list.updateValue(id, newValue);
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data);
+  }
+
+  invalidate(): void {
+    this.list.invalidate();
+  }
+
+  render(width: number): string[] {
+    return this.list.render(width);
+  }
+}

package/src/status.ts

@@ -0,0 +1,35 @@
+/**
+ * Status bar feedback helper using ctx.ui.setStatus() with auto-clear.
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { STATUS_SUCCESS_MS, STATUS_ERROR_MS } from "./types.ts";
+
+const STATUS_KEY = "input-shortcuts";
+
+/** Show a success status message with auto-clear. */
+export function showSuccess(ctx: ExtensionContext, text: string, durationMs = STATUS_SUCCESS_MS): void {
+  showStatus(ctx, text, durationMs);
+}
+
+/** Show an error status message with auto-clear. */
+export function showError(ctx: ExtensionContext, text: string, durationMs = STATUS_ERROR_MS): void {
+  showStatus(ctx, text, durationMs);
+}
+
+/** Show status text with auto-clear after duration. */
+export function showStatus(ctx: ExtensionContext, text: string, durationMs: number): void {
+  ctx.ui.setStatus(STATUS_KEY, text);
+  setTimeout(() => {
+    try {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+    } catch {
+      // Context may be gone — ignore
+    }
+  }, durationMs);
+}
+
+/** Clear the status bar entry immediately. */
+export function clearStatus(ctx: ExtensionContext): void {
+  ctx.ui.setStatus(STATUS_KEY, undefined);
+}

package/src/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared type definitions for input-shortcuts package.
+ */
+
+export interface TextSnapshot {
+  text: string;
+  timestamp: number;
+}
+
+export interface RegisterData {
+  stash: string;
+  registers: string[];
+}
+
+export interface InputShortcutsConfig {
+  chordKey: string;
+  tabInsertKey: string;
+}
+
+export type ChordAction =
+  | "stash"
+  | "redo"
+  | "undo"
+  | "appendRegister"
+  | "appendStash"
+  | "copy"
+  | "cut"
+  | "toggleThinking"
+  | "tab";
+
+export type ChordState = "idle" | "chord_root" | "chord_reg";
+
+export const DEFAULT_CONFIG: InputShortcutsConfig = {
+  chordKey: "alt+s",
+  tabInsertKey: "alt+i",
+};
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+export const UNDO_DEBOUNCE_MS = 500;
+export const MAX_UNDO_SNAPSHOTS = 50;
+export const STATUS_SUCCESS_MS = 2000;
+export const STATUS_ERROR_MS = 3000;
+export const REGISTERS_FILE = ".unipi/config/input-shortcuts.json";
+export const CONFIG_FILE = ".unipi/config/input-shortcuts-config.json";
+
+// Thinking level cycle for toggle action
+export const THINKING_CYCLE = ["off", "low", "medium", "high", "xhigh"] as const;

package/src/undo-redo.ts

@@ -0,0 +1,86 @@
+/**
+ * In-memory ring buffer for undo/redo with debounce and throttle.
+ *
+ * - Max 50 snapshots in undo stack
+ * - 500ms debounce on snapshot creation
+ * - 1s throttle on undo
+ * - Redo buffer cleared on new snapshot
+ */
+
+import type { TextSnapshot } from "./types.ts";
+import { MAX_UNDO_SNAPSHOTS, UNDO_DEBOUNCE_MS } from "./types.ts";
+
+export interface UndoRedoResult {
+  text: string;
+  ok: boolean;
+  reason?: string;
+}
+
+export class UndoRedoBuffer {
+  private undoStack: TextSnapshot[] = [];
+  private redoStack: TextSnapshot[] = [];
+  private lastSnapshotAt = 0;
+  private lastUndoAt = 0;
+
+  /**
+   * Take a snapshot of current text BEFORE it changes.
+   * Pushes to undo stack, clears redo stack.
+   * 500ms debounce: skips if last snapshot was within 500ms.
+   */
+  snapshot(text: string): void {
+    const now = Date.now();
+    if (now - this.lastSnapshotAt < UNDO_DEBOUNCE_MS) return;
+
+    this.undoStack.push({ text, timestamp: now });
+    if (this.undoStack.length > MAX_UNDO_SNAPSHOTS) {
+      this.undoStack.shift();
+    }
+    this.redoStack = [];
+    this.lastSnapshotAt = now;
+  }
+
+  /**
+   * Undo: pop from undo stack, push current text to redo.
+   */
+  undo(currentText: string): UndoRedoResult {
+    if (this.undoStack.length === 0) {
+      return { text: currentText, ok: false, reason: "nothing to undo" };
+    }
+
+    const snapshot = this.undoStack.pop()!;
+    this.redoStack.push({ text: currentText, timestamp: Date.now() });
+    return { text: snapshot.text, ok: true };
+  }
+
+  /**
+   * Redo: pop from redo stack, push current text to undo.
+   * No throttle on redo.
+   */
+  redo(currentText: string): UndoRedoResult {
+    if (this.redoStack.length === 0) {
+      return { text: currentText, ok: false, reason: "nothing to redo" };
+    }
+
+    const snapshot = this.redoStack.pop()!;
+    this.undoStack.push({ text: currentText, timestamp: Date.now() });
+    return { text: snapshot.text, ok: true };
+  }
+
+  /** Check if undo stack has entries. */
+  hasUndo(): boolean {
+    return this.undoStack.length > 0;
+  }
+
+  /** Check if redo stack has entries. */
+  hasRedo(): boolean {
+    return this.redoStack.length > 0;
+  }
+
+  /** Clear both stacks. Call on session shutdown. */
+  clear(): void {
+    this.undoStack = [];
+    this.redoStack = [];
+    this.lastSnapshotAt = 0;
+    this.lastUndoAt = 0;
+  }
+}