pi-image-tools 1.0.10 → 1.0.11

package/CHANGELOG.md

@@ -1,25 +1,11 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [1.0.10] - 2026-04-22
-
-### Added
-- Added preview width resolution from Pi terminal settings so inline and recent-image previews can honor `terminal.imageWidthCells`.
+## [1.0.11] - 2026-04-25
 
 ### Changed
-- Updated recent image selection previews to resolve terminal settings from the active session working directory before rendering.
-- Windows Sixel fallback now activates only when native terminal image support is unavailable, with environment toggles to force or disable Sixel rendering.
-- Clarified README global install and config paths when `PI_CODING_AGENT_DIR` is set.
-- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.68.1.
-
-### Fixed
-- Ensured generated Sixel output is emitted as a complete DCS sequence and preserved inline image protocol rows during preview width fitting.
+- Avoid Pi's built-in image paste shortcut by default while preserving the previous primary shortcut when users disable or rebind `app.clipboard.pasteImage` (thanks to @danielcherubini for reporting this in PR #3).
+- Replaced the placeholder `enabled` config with validated `debug`, explicit `shortcuts.pasteImage`, configurable built-in conflict avoidance, and built-in warning suppression settings.
+- Removed obsolete packaged README image assets now that the README uses a GitHub-hosted image.
 
 ## [1.0.9] - 2026-04-01
 
@@ -74,12 +60,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Rewrote README.md with professional documentation standards
 - Added comprehensive feature documentation, configuration reference, and usage examples
 
-## [1.0.1] - 2026-03-04
-
-- Included `asset/` in the npm package whitelist so README image assets ship in the tarball.
-
-## [1.0.0] - 2026-03-02
+## 1.0.0
 
 - Standardized repository layout to `src/` + root shim entrypoint.
 - Added TypeScript/Bundler project config, package metadata, and publish whitelist.
-- Added standard docs, license, and config template/runtime placeholder files.
+- Added standard docs, license, and initial runtime config files.

package/README.md

@@ -1,5 +1,7 @@
 # 🖼️ pi-image-tools
 
+[![npm version](https://img.shields.io/npm/v/pi-image-tools?style=flat-square)](https://www.npmjs.com/package/pi-image-tools) [![License](https://img.shields.io/github/license/MasuRii/pi-image-tools?style=flat-square)](LICENSE)
+
 Image attachment and preview extension for the **Pi coding agent**.
 
 `pi-image-tools` lets you attach clipboard images or recent screenshots to your next user message, then preview them inline in the TUI before the message is sent.
@@ -93,8 +95,16 @@ Selecting an entry queues that image for your next message.
 
 | Platform | Shortcuts |
 |----------|-----------|
-| Windows | `Alt+V`, `Ctrl+Alt+V` |
-| Linux / macOS | `Ctrl+V`, `Alt+V`, `Ctrl+Alt+V` |
+| Windows | `Ctrl+Alt+V`; `Alt+V` when Pi's built-in `app.clipboard.pasteImage` shortcut is disabled or rebound |
+| Linux / macOS | `Alt+V`, `Ctrl+Alt+V`; `Ctrl+V` when Pi's built-in `app.clipboard.pasteImage` shortcut is disabled or rebound |
+
+Pi's built-in image paste shortcut is not overridden by default. To keep the previous primary shortcut behavior without startup conflict warnings, disable the built-in binding manually in `~/.pi/agent/keybindings.json`:
+
+```json
+{
+  "app.clipboard.pasteImage": []
+}
+```
 
 ## Configuration
 
@@ -124,12 +134,85 @@ Starter template:
 
 ```json
 {
-  "enabled": true
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
 }
 ```
 
 See `config/config.example.json` for the same template.
 
+#### Debug logging
+
+Debug logging is disabled by default. Set `debug` to `true` to append debug events to `debug/debug.log` inside the extension directory:
+
+```json
+{
+  "debug": true,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+When `debug` is `false` or omitted, no debug log file is opened or written.
+
+#### Custom shortcuts
+
+Set `shortcuts.pasteImage` to choose the exact shortcuts registered by `pi-image-tools`. The value can be a single shortcut string or an array of shortcut strings. Add multiple entries when you want several key combinations to run the same paste-image action:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v", "alt+v", "ctrl+shift+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+A single shortcut is also valid:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": "ctrl+alt+v",
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+Config changes are applied the next time the extension loads, so restart Pi or reload extensions after editing `config.json`.
+
+Not every terminal can transmit every key combination to Pi. Triple-modifier shortcuts such as `ctrl+shift+alt+v` may be intercepted by the OS, terminal, shell, SSH, or tmux before Pi can see them. If a configured shortcut does not work, try a simpler shortcut such as `ctrl+alt+v`, `ctrl+shift+v`, `alt+p`, `f8`, or another function key.
+
+Keep `shortcuts.avoidBuiltinConflicts` set to `true` to skip configured paste-image shortcuts that overlap any effective Pi built-in shortcut. Keep `shortcuts.suppressBuiltinConflictWarnings` set to `true` when your goal is specifically to remove Pi's startup conflict warning noise. Both options use the same safe mechanism: `pi-image-tools` does not register the overlapping shortcut, so Pi has nothing to warn about. For example, `ctrl+p` is skipped because Pi uses it for built-in model/session actions.
+
+If both options are `false`, Pi handles conflicts itself. Non-reserved built-in conflicts may be taken over by `pi-image-tools`, but Pi can still print a startup warning. Reserved built-in shortcuts cannot be stolen through the extension shortcut API; Pi skips those registrations before `pi-image-tools` can handle them. To use a reserved Pi shortcut, rebind or disable the relevant built-in action in `~/.pi/agent/keybindings.json`, then restart Pi or reload extensions.
+
+Use an empty array to disable the extension's paste-image shortcuts while keeping `/paste-image` available:
+
+```json
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": [],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}
+```
+
+If `shortcuts.pasteImage` is omitted, `pi-image-tools` uses non-conflicting defaults and automatically restores the previous primary shortcut when Pi's built-in `app.clipboard.pasteImage` binding is disabled or rebound.
+
 ## Default recent-image search locations
 
 ### Windows
@@ -200,16 +283,16 @@ pi-image-tools/
 │   ├── index.ts                # Extension bootstrap and message flow
 │   ├── commands.ts             # /paste-image command registration
 │   ├── clipboard.ts            # Cross-platform clipboard image reading
+│   ├── config.ts               # Runtime config loading and validation
+│   ├── debug-logger.ts         # File-based debug logging
 │   ├── recent-images.ts        # Recent image discovery and cache management
 │   ├── image-preview.ts        # Preview building and Sixel/native rendering
 │   ├── inline-user-preview.ts  # Inline preview patching for user messages
 │   ├── keybindings.ts          # Keyboard shortcut registration
 │   ├── temp-file.ts            # Temporary file management and cleanup
 │   └── types.ts                # Shared TypeScript types
-├── config/
-│   └── config.example.json     # Starter runtime config
-└── asset/
-    └── pi-image-tools.png      # README preview image
+└── config/
+    └── config.example.json     # Starter runtime config
 ```
 
 ## Troubleshooting

package/config/config.example.json

@@ -1,3 +1,8 @@
-{
-  "enabled": true
-}
+{
+  "debug": false,
+  "shortcuts": {
+    "pasteImage": ["ctrl+alt+v"],
+    "avoidBuiltinConflicts": true,
+    "suppressBuiltinConflictWarnings": true
+  }
+}

package/package.json

@@ -1,67 +1,66 @@
-{
-  "name": "pi-image-tools",
-  "version": "1.0.10",
-  "description": "Image attachment and rendering extension for Pi TUI",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "asset",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "test": "node --test",
-    "check": "npm run lint && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-coding-agent",
-    "pi-tui",
-    "coding-agent",
-    "image",
-    "image-attachment",
-    "image-preview",
-    "clipboard",
-    "preview",
-    "windows"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-image-tools.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-image-tools#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-image-tools/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.68.1",
-    "@mariozechner/pi-tui": "^0.68.1"
-  },
-  "optionalDependencies": {
-    "@mariozechner/clipboard": "^0.3.2"
-  }
-}
+{
+  "name": "pi-image-tools",
+  "version": "1.0.11",
+  "description": "Image attachment and rendering extension for Pi TUI",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "node --test",
+    "check": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi-tui",
+    "coding-agent",
+    "image",
+    "image-attachment",
+    "image-preview",
+    "clipboard",
+    "preview",
+    "windows"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-image-tools.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-image-tools#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-image-tools/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "@mariozechner/pi-tui": "^0.70.2"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "^0.3.3"
+  }
+}

package/src/config.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { KeyId } from "@mariozechner/pi-tui";
+
+const CONFIG_FILE_NAME = "config.json";
+const EXTENSION_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export interface ImageToolsShortcutConfig {
+  avoidBuiltinConflicts: boolean;
+  suppressBuiltinConflictWarnings: boolean;
+  pasteImage?: KeyId[];
+}
+
+export interface ImageToolsConfig {
+  debug: boolean;
+  shortcuts: ImageToolsShortcutConfig;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function getExtensionRoot(): string {
+  return EXTENSION_ROOT;
+}
+
+export function getConfigPath(): string {
+  return join(getExtensionRoot(), CONFIG_FILE_NAME);
+}
+
+function formatConfigPath(path: string, property: string): string {
+  return `${path}${property.length > 0 ? ` property \"${property}\"` : ""}`;
+}
+
+function parseBoolean(value: unknown, property: string, path: string): boolean {
+  if (value === undefined) {
+    return false;
+  }
+
+  if (typeof value !== "boolean") {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: expected a boolean.`);
+  }
+
+  return value;
+}
+
+function normalizeShortcut(value: unknown, property: string, path: string): KeyId {
+  if (typeof value !== "string") {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: expected a string shortcut.`);
+  }
+
+  const shortcut = value.trim();
+  if (shortcut.length === 0) {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, property)}: shortcut cannot be empty.`);
+  }
+
+  return shortcut as KeyId;
+}
+
+function parseShortcutList(value: unknown, property: string, path: string): KeyId[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const rawShortcuts = Array.isArray(value) ? value : [value];
+  const shortcuts: KeyId[] = [];
+  const seen = new Set<string>();
+
+  for (const [index, rawShortcut] of rawShortcuts.entries()) {
+    const shortcut = normalizeShortcut(rawShortcut, `${property}[${index}]`, path);
+    const normalized = shortcut.toLowerCase();
+    if (seen.has(normalized)) {
+      continue;
+    }
+
+    seen.add(normalized);
+    shortcuts.push(shortcut);
+  }
+
+  return shortcuts;
+}
+
+function parseShortcutConfig(value: unknown, path: string): ImageToolsShortcutConfig {
+  if (value === undefined) {
+    return {
+      avoidBuiltinConflicts: false,
+      suppressBuiltinConflictWarnings: false,
+    };
+  }
+
+  if (!isRecord(value)) {
+    throw new Error(`Invalid pi-image-tools config at ${formatConfigPath(path, "shortcuts")}: expected an object.`);
+  }
+
+  const avoidBuiltinConflicts = parseBoolean(
+    value.avoidBuiltinConflicts,
+    "shortcuts.avoidBuiltinConflicts",
+    path,
+  );
+  const suppressBuiltinConflictWarnings = parseBoolean(
+    value.suppressBuiltinConflictWarnings,
+    "shortcuts.suppressBuiltinConflictWarnings",
+    path,
+  );
+  const pasteImage = parseShortcutList(value.pasteImage, "shortcuts.pasteImage", path);
+
+  return pasteImage === undefined
+    ? { avoidBuiltinConflicts, suppressBuiltinConflictWarnings }
+    : { avoidBuiltinConflicts, suppressBuiltinConflictWarnings, pasteImage };
+}
+
+function parseConfig(rawConfig: unknown, path: string): ImageToolsConfig {
+  if (!isRecord(rawConfig)) {
+    throw new Error(`Invalid pi-image-tools config at ${path}: expected a JSON object.`);
+  }
+
+  return {
+    debug: parseBoolean(rawConfig.debug, "debug", path),
+    shortcuts: parseShortcutConfig(rawConfig.shortcuts, path),
+  };
+}
+
+export function loadImageToolsConfig(path = getConfigPath()): ImageToolsConfig {
+  if (!existsSync(path)) {
+    return {
+      debug: false,
+      shortcuts: {
+        avoidBuiltinConflicts: false,
+        suppressBuiltinConflictWarnings: false,
+      },
+    };
+  }
+
+  try {
+    const rawConfig = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+    return parseConfig(rawConfig, path);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid pi-image-tools config at ${path}: ${error.message}`);
+    }
+
+    throw error;
+  }
+}

package/src/debug-logger.ts

@@ -0,0 +1,48 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { getExtensionRoot, type ImageToolsConfig } from "./config.js";
+
+const DEBUG_DIRECTORY_NAME = "debug";
+const DEBUG_LOG_FILE_NAME = "debug.log";
+
+type DebugFields = Record<string, unknown>;
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  return "Unknown error";
+}
+
+export class DebugLogger {
+  private readonly logPath: string | undefined;
+
+  private constructor(private readonly enabled: boolean) {
+    this.logPath = enabled ? join(getExtensionRoot(), DEBUG_DIRECTORY_NAME, DEBUG_LOG_FILE_NAME) : undefined;
+  }
+
+  static create(config: ImageToolsConfig): DebugLogger {
+    return new DebugLogger(config.debug);
+  }
+
+  log(event: string, fields: DebugFields = {}): void {
+    if (!this.enabled || !this.logPath) {
+      return;
+    }
+
+    const debugDirectory = join(getExtensionRoot(), DEBUG_DIRECTORY_NAME);
+
+    try {
+      mkdirSync(debugDirectory, { recursive: true });
+      appendFileSync(
+        this.logPath,
+        `${JSON.stringify({ timestamp: new Date().toISOString(), event, ...fields })}\n`,
+        "utf-8",
+      );
+    } catch (error) {
+      throw new Error(`pi-image-tools debug logging failed at ${this.logPath}: ${getErrorMessage(error)}`);
+    }
+  }
+}

package/src/index.ts

@@ -2,6 +2,8 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
 import { readClipboardImage } from "./clipboard.js";
 import { registerPasteImageCommand } from "./commands.js";
+import { loadImageToolsConfig } from "./config.js";
+import { DebugLogger } from "./debug-logger.js";
 import {
   IMAGE_PREVIEW_CUSTOM_TYPE,
   buildPreviewItems,
@@ -144,8 +146,15 @@ function showRecentSelectionPreview(
 }
 
 export default function imageToolsExtension(pi: ExtensionAPI): void {
+  const config = loadImageToolsConfig();
+  const logger = DebugLogger.create(config);
   const pendingImages: PendingImage[] = [];
 
+  logger.log("extension.initialize", {
+    debug: config.debug,
+    pasteImageShortcutsConfigured: config.shortcuts.pasteImage !== undefined,
+  });
+
   registerInlineUserImagePreview(pi);
   registerImagePreviewDisplay(pi);
 
@@ -249,7 +258,7 @@ export default function imageToolsExtension(pi: ExtensionAPI): void {
     };
   });
 
-  registerImagePasteKeybindings(pi, pasteImageFromClipboard);
+  registerImagePasteKeybindings(pi, pasteImageFromClipboard, { config, logger });
   registerPasteImageCommand(pi, {
     fromClipboard: pasteImageFromClipboard,
     fromRecent: pasteImageFromRecent,

package/src/keybindings.ts

@@ -1,9 +1,222 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { KeyId } from "@mariozechner/pi-tui";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 
+import { getAgentDir, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { TUI_KEYBINDINGS, type KeyId, type KeybindingsConfig } from "@mariozechner/pi-tui";
+
+import { isRecord, type ImageToolsConfig } from "./config.js";
+import type { DebugLogger } from "./debug-logger.js";
 import type { PasteImageHandler } from "./types.js";
 
-function getImagePasteShortcuts(platform: NodeJS.Platform = process.platform): KeyId[] {
+type KeybindingDefaults = Record<string, KeyId | KeyId[]>;
+
+const LEGACY_KEYBINDING_NAME_MIGRATIONS: Record<string, string> = {
+  cursorUp: "tui.editor.cursorUp",
+  cursorDown: "tui.editor.cursorDown",
+  cursorLeft: "tui.editor.cursorLeft",
+  cursorRight: "tui.editor.cursorRight",
+  cursorWordLeft: "tui.editor.cursorWordLeft",
+  cursorWordRight: "tui.editor.cursorWordRight",
+  cursorLineStart: "tui.editor.cursorLineStart",
+  cursorLineEnd: "tui.editor.cursorLineEnd",
+  jumpForward: "tui.editor.jumpForward",
+  jumpBackward: "tui.editor.jumpBackward",
+  pageUp: "tui.editor.pageUp",
+  pageDown: "tui.editor.pageDown",
+  deleteCharBackward: "tui.editor.deleteCharBackward",
+  deleteCharForward: "tui.editor.deleteCharForward",
+  deleteWordBackward: "tui.editor.deleteWordBackward",
+  deleteWordForward: "tui.editor.deleteWordForward",
+  deleteToLineStart: "tui.editor.deleteToLineStart",
+  deleteToLineEnd: "tui.editor.deleteToLineEnd",
+  yank: "tui.editor.yank",
+  yankPop: "tui.editor.yankPop",
+  undo: "tui.editor.undo",
+  newLine: "tui.input.newLine",
+  submit: "tui.input.submit",
+  tab: "tui.input.tab",
+  copy: "tui.input.copy",
+  selectUp: "tui.select.up",
+  selectDown: "tui.select.down",
+  selectPageUp: "tui.select.pageUp",
+  selectPageDown: "tui.select.pageDown",
+  selectConfirm: "tui.select.confirm",
+  selectCancel: "tui.select.cancel",
+  interrupt: "app.interrupt",
+  clear: "app.clear",
+  exit: "app.exit",
+  suspend: "app.suspend",
+  cycleThinkingLevel: "app.thinking.cycle",
+  cycleModelForward: "app.model.cycleForward",
+  cycleModelBackward: "app.model.cycleBackward",
+  selectModel: "app.model.select",
+  expandTools: "app.tools.expand",
+  toggleThinking: "app.thinking.toggle",
+  toggleSessionNamedFilter: "app.session.toggleNamedFilter",
+  externalEditor: "app.editor.external",
+  followUp: "app.message.followUp",
+  dequeue: "app.message.dequeue",
+  pasteImage: "app.clipboard.pasteImage",
+  newSession: "app.session.new",
+  tree: "app.session.tree",
+  fork: "app.session.fork",
+  resume: "app.session.resume",
+  treeFoldOrUp: "app.tree.foldOrUp",
+  treeUnfoldOrDown: "app.tree.unfoldOrDown",
+  treeEditLabel: "app.tree.editLabel",
+  treeToggleLabelTimestamp: "app.tree.toggleLabelTimestamp",
+  toggleSessionPath: "app.session.togglePath",
+  toggleSessionSort: "app.session.toggleSort",
+  renameSession: "app.session.rename",
+  deleteSession: "app.session.delete",
+  deleteSessionNoninvasive: "app.session.deleteNoninvasive",
+};
+
+const APP_KEYBINDING_DEFAULTS: KeybindingDefaults = {
+  "app.interrupt": "escape",
+  "app.clear": "ctrl+c",
+  "app.exit": "ctrl+d",
+  "app.suspend": process.platform === "win32" ? [] : "ctrl+z",
+  "app.thinking.cycle": "shift+tab",
+  "app.model.cycleForward": "ctrl+p",
+  "app.model.cycleBackward": "shift+ctrl+p",
+  "app.model.select": "ctrl+l",
+  "app.tools.expand": "ctrl+o",
+  "app.thinking.toggle": "ctrl+t",
+  "app.session.toggleNamedFilter": "ctrl+n",
+  "app.editor.external": "ctrl+g",
+  "app.message.followUp": "alt+enter",
+  "app.message.dequeue": "alt+up",
+  "app.clipboard.pasteImage": process.platform === "win32" ? "alt+v" : "ctrl+v",
+  "app.session.new": [],
+  "app.session.tree": [],
+  "app.session.fork": [],
+  "app.session.resume": [],
+  "app.tree.foldOrUp": ["ctrl+left", "alt+left"],
+  "app.tree.unfoldOrDown": ["ctrl+right", "alt+right"],
+  "app.tree.editLabel": "shift+l",
+  "app.tree.toggleLabelTimestamp": "shift+t",
+  "app.session.togglePath": "ctrl+p",
+  "app.session.toggleSort": "ctrl+s",
+  "app.session.rename": "ctrl+r",
+  "app.session.delete": "ctrl+d",
+  "app.session.deleteNoninvasive": "ctrl+backspace",
+  "app.models.save": "ctrl+s",
+  "app.models.enableAll": "ctrl+a",
+  "app.models.clearAll": "ctrl+x",
+  "app.models.toggleProvider": "ctrl+p",
+  "app.models.reorderUp": "alt+up",
+  "app.models.reorderDown": "alt+down",
+  "app.tree.filter.default": "ctrl+d",
+  "app.tree.filter.noTools": "ctrl+t",
+  "app.tree.filter.userOnly": "ctrl+u",
+  "app.tree.filter.labeledOnly": "ctrl+l",
+  "app.tree.filter.all": "ctrl+a",
+  "app.tree.filter.cycleForward": "ctrl+o",
+  "app.tree.filter.cycleBackward": "shift+ctrl+o",
+};
+
+export interface RegisterImagePasteKeybindingsOptions {
+  config: ImageToolsConfig;
+  logger: DebugLogger;
+}
+
+function toShortcutList(shortcuts: KeybindingsConfig[string]): KeyId[] {
+  if (shortcuts === undefined) {
+    return [];
+  }
+
+  return Array.isArray(shortcuts) ? shortcuts : [shortcuts];
+}
+
+function normalizeKeybinding(value: unknown): KeybindingsConfig[string] | undefined {
+  if (typeof value === "string") {
+    return value as KeyId;
+  }
+
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    return value as KeyId[];
+  }
+
+  return undefined;
+}
+
+function normalizeShortcutKey(shortcut: KeyId): string {
+  return shortcut.toLowerCase();
+}
+
+function readKeybindingsConfig(): Record<string, unknown> | undefined {
+  const keybindingsPath = join(getAgentDir(), "keybindings.json");
+  if (!existsSync(keybindingsPath)) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(keybindingsPath, "utf-8")) as unknown;
+    return isRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function migrateKeybindingName(key: string): string {
+  return LEGACY_KEYBINDING_NAME_MIGRATIONS[key] ?? key;
+}
+
+function normalizeUserKeybindings(rawConfig: Record<string, unknown> | undefined): KeybindingsConfig {
+  if (!rawConfig) {
+    return {};
+  }
+
+  const userKeybindings: KeybindingsConfig = {};
+  for (const [key, value] of Object.entries(rawConfig)) {
+    const normalizedValue = normalizeKeybinding(value);
+    if (normalizedValue === undefined) {
+      continue;
+    }
+
+    const migratedKey = migrateKeybindingName(key);
+    if (migratedKey !== key && Object.hasOwn(rawConfig, migratedKey)) {
+      continue;
+    }
+
+    userKeybindings[migratedKey] = normalizedValue;
+  }
+
+  return userKeybindings;
+}
+
+function getBuiltinKeybindingDefaults(): KeybindingDefaults {
+  const tuiDefaults: KeybindingDefaults = {};
+  for (const [keybinding, definition] of Object.entries(TUI_KEYBINDINGS)) {
+    tuiDefaults[keybinding] = definition.defaultKeys;
+  }
+
+  return {
+    ...tuiDefaults,
+    ...APP_KEYBINDING_DEFAULTS,
+  };
+}
+
+function getConfiguredBuiltinShortcuts(): Set<string> {
+  const defaults = getBuiltinKeybindingDefaults();
+  const userKeybindings = normalizeUserKeybindings(readKeybindingsConfig());
+  const builtinShortcuts = new Set<string>();
+
+  for (const [keybinding, defaultShortcuts] of Object.entries(defaults)) {
+    const configuredShortcuts = Object.hasOwn(userKeybindings, keybinding)
+      ? userKeybindings[keybinding]
+      : defaultShortcuts;
+
+    for (const shortcut of toShortcutList(configuredShortcuts)) {
+      builtinShortcuts.add(normalizeShortcutKey(shortcut));
+    }
+  }
+
+  return builtinShortcuts;
+}
+
+function getImagePasteShortcutCandidates(platform: NodeJS.Platform): KeyId[] {
   if (platform === "win32") {
     return ["alt+v", "ctrl+alt+v"];
   }
@@ -11,8 +224,48 @@ function getImagePasteShortcuts(platform: NodeJS.Platform = process.platform): K
   return ["ctrl+v", "alt+v", "ctrl+alt+v"];
 }
 
-export function registerImagePasteKeybindings(pi: ExtensionAPI, handler: PasteImageHandler): void {
-  for (const shortcut of getImagePasteShortcuts()) {
+function removeBuiltinConflicts(shortcuts: readonly KeyId[]): KeyId[] {
+  const builtinShortcuts = getConfiguredBuiltinShortcuts();
+
+  return shortcuts.filter((shortcut) => !builtinShortcuts.has(normalizeShortcutKey(shortcut)));
+}
+
+function getImagePasteShortcuts(
+  config: ImageToolsConfig,
+  platform: NodeJS.Platform = process.platform,
+): KeyId[] {
+  const shouldAvoidBuiltinConflicts =
+    config.shortcuts.avoidBuiltinConflicts || config.shortcuts.suppressBuiltinConflictWarnings;
+
+  if (config.shortcuts.pasteImage !== undefined) {
+    return shouldAvoidBuiltinConflicts
+      ? removeBuiltinConflicts(config.shortcuts.pasteImage)
+      : config.shortcuts.pasteImage;
+  }
+
+  return removeBuiltinConflicts(getImagePasteShortcutCandidates(platform));
+}
+
+export function registerImagePasteKeybindings(
+  pi: ExtensionAPI,
+  handler: PasteImageHandler,
+  options: RegisterImagePasteKeybindingsOptions,
+): void {
+  const configuredShortcuts = options.config.shortcuts.pasteImage;
+  const shortcuts = getImagePasteShortcuts(options.config);
+  const skippedShortcuts = configuredShortcuts?.filter(
+    (shortcut) => !shortcuts.some((registeredShortcut) => normalizeShortcutKey(registeredShortcut) === normalizeShortcutKey(shortcut)),
+  ) ?? [];
+
+  options.logger.log("keybindings.register", {
+    avoidBuiltinConflicts: options.config.shortcuts.avoidBuiltinConflicts,
+    suppressBuiltinConflictWarnings: options.config.shortcuts.suppressBuiltinConflictWarnings,
+    configured: configuredShortcuts !== undefined,
+    registeredShortcuts: shortcuts,
+    skippedShortcuts,
+  });
+
+  for (const shortcut of shortcuts) {
     pi.registerShortcut(shortcut, {
       description: "Attach clipboard image to draft (send when ready)",
       handler,

package/src/sixel-protocol.ts

@@ -1,57 +1,57 @@
-const SIXEL_IMAGE_LINE_MARKER = "\x1b_Gm=0;\x1b\\";
-const KITTY_IMAGE_LINE_MARKER = "\x1b_G";
-const ITERM_IMAGE_LINE_MARKER = "\x1b]1337;File=";
-const SIXEL_DCS_PREFIX = "\x1bP";
-const STRING_TERMINATOR = "\x1b\\";
-const MAX_IMAGE_ROWS = 80;
-
-function sanitizeRows(rows: number): number {
-  return Math.max(1, Math.min(Math.trunc(rows), MAX_IMAGE_ROWS));
-}
-
-function normalizeSixelOutput(value: string): string {
-  return value.replace(/\r?\n/g, "").replace(/\s+$/g, "");
-}
-
-/**
- * Ensure the PowerShell Sixel output is emitted as a complete DCS sequence.
- * Some converters return only the sixel payload body; terminals need the
- * enclosing ESC P ... ESC \\ wrapper to render it as an image.
- */
-export function ensureCompleteSixelSequence(sequence: string): string {
-  let normalized = normalizeSixelOutput(sequence);
-  if (normalized.length === 0) {
-    return "";
-  }
-
-  if (!normalized.startsWith(SIXEL_DCS_PREFIX)) {
-    normalized = `${SIXEL_DCS_PREFIX}${normalized.startsWith("q") ? normalized : `q${normalized}`}`;
-  }
-
-  if (!normalized.endsWith(STRING_TERMINATOR)) {
-    normalized = `${normalized}${STRING_TERMINATOR}`;
-  }
-
-  return normalized;
-}
-
-export function buildSixelRenderLines(sequence: string, rows: number): string[] {
-  const safeRows = sanitizeRows(rows);
-  const completeSequence = ensureCompleteSixelSequence(sequence);
-  if (completeSequence.length === 0) {
-    return [];
-  }
-
-  const lines = Array.from({ length: Math.max(0, safeRows - 1) }, () => "");
-  const moveUp = safeRows > 1 ? `\x1b[${safeRows - 1}A` : "";
-  return [...lines, `${SIXEL_IMAGE_LINE_MARKER}${moveUp}${completeSequence}`];
-}
-
-export function isInlineImageProtocolLine(line: string): boolean {
-  return (
-    line.includes(SIXEL_IMAGE_LINE_MARKER) ||
-    line.includes(KITTY_IMAGE_LINE_MARKER) ||
-    line.includes(ITERM_IMAGE_LINE_MARKER) ||
-    line.includes(SIXEL_DCS_PREFIX)
-  );
-}
+const SIXEL_IMAGE_LINE_MARKER = "\x1b_Gm=0;\x1b\\";
+const KITTY_IMAGE_LINE_MARKER = "\x1b_G";
+const ITERM_IMAGE_LINE_MARKER = "\x1b]1337;File=";
+const SIXEL_DCS_PREFIX = "\x1bP";
+const STRING_TERMINATOR = "\x1b\\";
+const MAX_IMAGE_ROWS = 80;
+
+function sanitizeRows(rows: number): number {
+  return Math.max(1, Math.min(Math.trunc(rows), MAX_IMAGE_ROWS));
+}
+
+function normalizeSixelOutput(value: string): string {
+  return value.replace(/\r?\n/g, "").replace(/\s+$/g, "");
+}
+
+/**
+ * Ensure the PowerShell Sixel output is emitted as a complete DCS sequence.
+ * Some converters return only the sixel payload body; terminals need the
+ * enclosing ESC P ... ESC \\ wrapper to render it as an image.
+ */
+export function ensureCompleteSixelSequence(sequence: string): string {
+  let normalized = normalizeSixelOutput(sequence);
+  if (normalized.length === 0) {
+    return "";
+  }
+
+  if (!normalized.startsWith(SIXEL_DCS_PREFIX)) {
+    normalized = `${SIXEL_DCS_PREFIX}${normalized.startsWith("q") ? normalized : `q${normalized}`}`;
+  }
+
+  if (!normalized.endsWith(STRING_TERMINATOR)) {
+    normalized = `${normalized}${STRING_TERMINATOR}`;
+  }
+
+  return normalized;
+}
+
+export function buildSixelRenderLines(sequence: string, rows: number): string[] {
+  const safeRows = sanitizeRows(rows);
+  const completeSequence = ensureCompleteSixelSequence(sequence);
+  if (completeSequence.length === 0) {
+    return [];
+  }
+
+  const lines = Array.from({ length: Math.max(0, safeRows - 1) }, () => "");
+  const moveUp = safeRows > 1 ? `\x1b[${safeRows - 1}A` : "";
+  return [...lines, `${SIXEL_IMAGE_LINE_MARKER}${moveUp}${completeSequence}`];
+}
+
+export function isInlineImageProtocolLine(line: string): boolean {
+  return (
+    line.includes(SIXEL_IMAGE_LINE_MARKER) ||
+    line.includes(KITTY_IMAGE_LINE_MARKER) ||
+    line.includes(ITERM_IMAGE_LINE_MARKER) ||
+    line.includes(SIXEL_DCS_PREFIX)
+  );
+}

package/src/terminal-image-width.ts

@@ -1,90 +1,90 @@
-import { SettingsManager, getAgentDir } from "@mariozechner/pi-coding-agent";
-import { resolve } from "node:path";
-
-export const DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS = 60;
-
-export interface TerminalImageWidthOptions {
-  cwd?: string;
-  agentDir?: string;
-}
-
-interface SettingsWithOptionalTerminalWidth {
-  terminal?: {
-    imageWidthCells?: unknown;
-  };
-}
-
-type SettingsManagerWithOptionalWidthGetter = SettingsManager & {
-  getImageWidthCells?: () => number;
-};
-
-let activeTerminalSettingsCwd = process.cwd();
-
-function normalizeDirectoryPath(value: string | undefined): string | undefined {
-  if (typeof value !== "string") {
-    return undefined;
-  }
-
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return undefined;
-  }
-
-  return resolve(trimmed);
-}
-
-function normalizeImageWidthCells(value: unknown): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) {
-    return DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS;
-  }
-
-  return Math.max(1, Math.floor(value));
-}
-
-function readRawImageWidthCells(settings: unknown): unknown {
-  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
-    return undefined;
-  }
-
-  return (settings as SettingsWithOptionalTerminalWidth).terminal?.imageWidthCells;
-}
-
-function resolveSettingsManagerImageWidthCells(settingsManager: SettingsManager): unknown {
-  const settingsManagerWithOptionalWidthGetter =
-    settingsManager as SettingsManagerWithOptionalWidthGetter;
-
-  if (typeof settingsManagerWithOptionalWidthGetter.getImageWidthCells === "function") {
-    return settingsManagerWithOptionalWidthGetter.getImageWidthCells();
-  }
-
-  const projectWidth = readRawImageWidthCells(settingsManager.getProjectSettings());
-  if (projectWidth !== undefined) {
-    return projectWidth;
-  }
-
-  return readRawImageWidthCells(settingsManager.getGlobalSettings());
-}
-
-export function setActiveTerminalImageSettingsCwd(cwd: string | undefined): void {
-  const normalized = normalizeDirectoryPath(cwd);
-  if (normalized) {
-    activeTerminalSettingsCwd = normalized;
-  }
-}
-
-export function resolveTerminalImageWidthCells(
-  options: TerminalImageWidthOptions = {},
-): number {
-  const cwd = normalizeDirectoryPath(options.cwd) ?? activeTerminalSettingsCwd;
-
-  try {
-    const settingsManager = SettingsManager.create(
-      cwd,
-      normalizeDirectoryPath(options.agentDir) ?? getAgentDir(),
-    );
-
-    return normalizeImageWidthCells(resolveSettingsManagerImageWidthCells(settingsManager));
-  } catch {
-    return DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS;
-  }
-}
+import { SettingsManager, getAgentDir } from "@mariozechner/pi-coding-agent";
+import { resolve } from "node:path";
+
+export const DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS = 60;
+
+export interface TerminalImageWidthOptions {
+  cwd?: string;
+  agentDir?: string;
+}
+
+interface SettingsWithOptionalTerminalWidth {
+  terminal?: {
+    imageWidthCells?: unknown;
+  };
+}
+
+type SettingsManagerWithOptionalWidthGetter = SettingsManager & {
+  getImageWidthCells?: () => number;
+};
+
+let activeTerminalSettingsCwd = process.cwd();
+
+function normalizeDirectoryPath(value: string | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  return resolve(trimmed);
+}
+
+function normalizeImageWidthCells(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS;
+  }
+
+  return Math.max(1, Math.floor(value));
+}
+
+function readRawImageWidthCells(settings: unknown): unknown {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+    return undefined;
+  }
+
+  return (settings as SettingsWithOptionalTerminalWidth).terminal?.imageWidthCells;
+}
+
+function resolveSettingsManagerImageWidthCells(settingsManager: SettingsManager): unknown {
+  const settingsManagerWithOptionalWidthGetter =
+    settingsManager as SettingsManagerWithOptionalWidthGetter;
+
+  if (typeof settingsManagerWithOptionalWidthGetter.getImageWidthCells === "function") {
+    return settingsManagerWithOptionalWidthGetter.getImageWidthCells();
+  }
+
+  const projectWidth = readRawImageWidthCells(settingsManager.getProjectSettings());
+  if (projectWidth !== undefined) {
+    return projectWidth;
+  }
+
+  return readRawImageWidthCells(settingsManager.getGlobalSettings());
+}
+
+export function setActiveTerminalImageSettingsCwd(cwd: string | undefined): void {
+  const normalized = normalizeDirectoryPath(cwd);
+  if (normalized) {
+    activeTerminalSettingsCwd = normalized;
+  }
+}
+
+export function resolveTerminalImageWidthCells(
+  options: TerminalImageWidthOptions = {},
+): number {
+  const cwd = normalizeDirectoryPath(options.cwd) ?? activeTerminalSettingsCwd;
+
+  try {
+    const settingsManager = SettingsManager.create(
+      cwd,
+      normalizeDirectoryPath(options.agentDir) ?? getAgentDir(),
+    );
+
+    return normalizeImageWidthCells(resolveSettingsManagerImageWidthCells(settingsManager));
+  } catch {
+    return DEFAULT_TERMINAL_IMAGE_WIDTH_CELLS;
+  }
+}