pi-pretty-tui 0.3.0 → 0.3.1

package/README.md

@@ -23,7 +23,7 @@ pi install npm:pi-pretty-tui
 
 Restart Pi or run `/reload` after installation.
 
-Pi may warn that built-in tools are being overridden. This is expected: pi-pretty-tui re-registers Pi's built-in tools and delegates execution to their original implementations, changing only their TUI renderers.
+pi-pretty-tui registers renderers without replacing tool implementations. Extensions that provide tools with built-in names, such as `bash`, keep their own execution and renderers.
 
 ## Working with tool calls
 
@@ -83,6 +83,21 @@ In fullscreen, interactive activity/tool rows and copy controls tolerate same-ro
 
 In compact and full, compaction summaries use a theme-colored `compaction ▸/▾` card. The original token count, shortcut hint and complete summary remain available; click the title/body or use native `Ctrl+O` to toggle expansion. Compaction cost notices remain separate. Clean retains Pi’s original compaction box.
 
+## Optional border-free selection copying
+
+The experimental **Selection copy** option excludes plugin borders, titles and layout padding from mouse-selected text in fullscreen mode. Literal box-drawing characters in content are preserved. It is **off by default** and applies to clean, compact and full.
+
+Open `/pretty-tui` and select `Selection copy` to toggle it, or run:
+
+```text
+/pretty-tui selection-copy on
+/pretty-tui selection-copy off
+```
+
+The choice is stored as `selectionCopy` in `pretty-tui.json`; toggling automatically reloads Pi. `/pretty-tui status` shows the configured value. When off, no selection-copy/compositor/terminal-write hooks or private row annotations are installed. Disabling the whole extension also disables this feature, while preserving its saved preference. Regular-mode terminal-owned selection is unchanged.
+
+This is an opt-in feature while terminal acceptance and internal-API compatibility are being evaluated. Long transcripts retain additional annotation memory; see [the exploration and GC measurements](docs/selection-copy-exploration.md) in the source repository.
+
 ## Copy user messages
 
 In fullscreen mode, left-click a user bubble's body or border to copy its complete original text, preserving Markdown, indentation, and line breaks without the bubble frame. Existing links and code-block `[Copy]` controls retain priority; dragging to select text does not trigger whole-message copy. Pi's native clipboard path provides copy feedback. This copies text, not image attachments. Regular mode keeps terminal-owned mouse selection and copying.
@@ -108,11 +123,13 @@ npm install
 npm test
 ```
 
-The suite covers live and restored activity timelines, retries and terminal states, user/steering/compaction/native-renderer boundaries, ten-second UI-status replacement, stale-timer and flash cleanup on reload and shutdown, standalone severity styling, built-in and third-party tools, expandable thinking, parallel completion ownership, orphaned calls, duplicate-summary prevention, durable response timing and answer-only copy controls, adaptive user chat bubbles, complete prototype-patch restoration, and fullscreen code-block copy hit regions. GitHub Actions runs the same checks on every push and pull request.
+The suite covers live and restored activity timelines, retries and terminal states, user/steering/compaction/native-renderer boundaries, ten-second UI-status replacement, stale-timer and flash cleanup on reload and shutdown, standalone severity styling, built-in and third-party tools, expandable thinking, parallel completion ownership, orphaned calls, duplicate-summary prevention, durable response timing and answer-only copy controls, adaptive user chat bubbles, complete prototype-patch restoration, and fullscreen code-block copy hit regions. It also uses Pi's real extension loader to check coexistence with a same-named replacement tool. GitHub Actions runs the same checks on every push and pull request.
+
+To additionally exercise a local checkout of [pi-bash-bg](https://github.com/mapleluvr/pi-bash-bg), set `PI_BASH_BG_EXTENSION` to its `index.ts` before running `npm test`. This optional integration test executes foreground and automatically backgrounded commands and checks their status and logs.
 
 ## Compatibility notice
 
-The current development and regression-test baseline is **Pi 1.3.0**. User chat bubbles support its direct Markdown layout, using themed, full-width User panels in full/compact and transparent, content-sized bubbles in clean. Nested execution requires Pi 0.99.0 or later; this is a feature requirement, not a promise that every older Pi release is tested.
+The current development and regression-test baseline is **Pi 1.4.0**. User chat bubbles support its direct Markdown layout, using themed, full-width User panels in full/compact and transparent, content-sized bubbles in clean. Nested execution requires Pi 0.99.0 or later; this is a feature requirement, not a promise that every older Pi release is tested.
 
 Tool rendering uses Pi's documented extension APIs. Active-tool state follows Pi's built-in execution transitions through its exported interactive components. Clean-mode thought details use the activity hierarchy's own disclosure state; full and compact modes retain Pi's built-in Thinking visibility control. Rendering native user messages as adaptive chat bubbles, rounding the native prompt editor, changing unordered-list markers, and enhancing fenced code blocks require reload-safe runtime patches because Pi does not currently expose public renderer hooks for those presentation details. Markdown enhancements are activated only while rendering user and assistant messages in the main transcript; Markdown created by extension overlays keeps Pi's native layout. Markdown parsing, syntax highlighting, and terminal semantic zones remain handled by Pi.
 

package/README.zh-CN.md

@@ -23,7 +23,7 @@ pi install npm:pi-pretty-tui
 
 安装后重启 Pi，或运行 `/reload`。
 
-Pi 可能会提示内置工具被覆盖。这是正常现象：pi-pretty-tui 会重新注册 Pi 的内置工具，并将实际执行委托给原始实现，只修改它们的 TUI 渲染方式。
+pi-pretty-tui 只注册渲染器，不替换工具实现。提供 `bash` 等内置同名工具的扩展仍使用自己的执行逻辑和 renderer。
 
 ## 使用工具调用
 
@@ -83,6 +83,21 @@ fullscreen 模式下，活动树/工具交互行与复制入口允许同一行
 
 compact 和 full 中，压缩摘要使用主题配色的 `compaction ▸/▾` 卡片，保留原始 token 数、快捷键提示和完整摘要；点击标题/正文或使用原生 `Ctrl+O` 切换展开。压缩费用提示仍独立显示，clean 保留 Pi 原生压缩消息样式。
 
+## 可选的无边框选区复制
+
+实验性的 **Selection copy** 选项可在 fullscreen 模式下，从鼠标选区的复制结果中排除插件绘制的边框、标题和布局留白，保留正文里真实存在的框线字符。**默认关闭**，适用于 clean、compact 和 full。
+
+打开 `/pretty-tui`，选择 `Selection copy` 切换，或直接执行：
+
+```text
+/pretty-tui selection-copy on
+/pretty-tui selection-copy off
+```
+
+选择会保存为 `pretty-tui.json` 中的 `selectionCopy`，切换后自动重载 Pi；`/pretty-tui status` 可查看配置值。关闭时不安装选区复制、叠加层或终端写入补丁，也不生成私有行标记。禁用整个插件时，本功能也不会启用，但会保留开关偏好。regular 模式由终端管理的选区保持原样。
+
+目前仍需实际终端验收，并依赖 Pi 内部接口，因此作为可选功能保留。长会话会额外保留标记相关内存；源码仓库中的[探索与垃圾回收报告](docs/selection-copy-exploration.md)记录了测试范围和测量结果。
+
 ## 复制用户消息
 
 fullscreen 模式下，左键点击用户气泡的正文或边框，可复制完整原始文本，保留 Markdown、缩进和换行，不包含气泡边框。已有链接和代码块 `[Copy]` 控件保留优先级；拖动选择文本不会触发整条复制。复制使用 Pi 原生剪贴板路径及反馈，只复制文本，不复制图片附件。regular 模式保留终端自身的鼠标选择与复制行为。
@@ -108,11 +123,13 @@ npm install
 npm test
 ```
 
-测试覆盖实时与历史恢复的活动时间线、自动重试与终止状态、用户/steer/compaction/原生 renderer 边界、十秒 UI 状态替换、reload 与 shutdown 时的旧 timer 与状态清理、独立严重级别样式、内置与第三方工具、可展开思考、并行工具完成归属、孤立 tool call、重复摘要防护、可持久化的工作时长与仅回答复制控件、自适应用户聊天气泡、原型补丁的完整恢复，以及 fullscreen 代码块复制的点击区域。GitHub Actions 会在每次 push 和 pull request 时运行相同检查。
+测试覆盖实时与历史恢复的活动时间线、自动重试与终止状态、用户/steer/compaction/原生 renderer 边界、十秒 UI 状态替换、reload 与 shutdown 时的旧 timer 与状态清理、独立严重级别样式、内置与第三方工具、可展开思考、并行工具完成归属、孤立 tool call、重复摘要防护、可持久化的工作时长与仅回答复制控件、自适应用户聊天气泡、原型补丁的完整恢复，以及 fullscreen 代码块复制的点击区域。测试还使用 Pi 的真实扩展加载器检查同名替换工具的共存。GitHub Actions 会在每次 push 和 pull request 时运行相同检查。
+
+如需额外测试本地 [pi-bash-bg](https://github.com/mapleluvr/pi-bash-bg) 仓库，运行 `npm test` 前将 `PI_BASH_BG_EXTENSION` 指向其 `index.ts`。该可选集成测试会执行前台和自动转后台的命令，并检查状态和日志。
 
 ## 兼容性说明
 
-当前开发与回归测试基线为 **Pi 1.3.0**。用户气泡已适配该版本直接使用 Markdown 的布局，full/compact 使用带底色、铺满宽度的 User 面板，clean 使用透明、按内容自适应的气泡。嵌套执行需要 Pi 0.99.0 及以后；这是功能要求，不代表每个旧版都经过测试。
+当前开发与回归测试基线为 **Pi 1.4.0**。用户气泡已适配该版本直接使用 Markdown 的布局，full/compact 使用带底色、铺满宽度的 User 面板，clean 使用透明、按内容自适应的气泡。嵌套执行需要 Pi 0.99.0 及以后；这是功能要求，不代表每个旧版都经过测试。
 
 工具渲染使用 Pi 的公开扩展 API。活动工具状态通过 Pi 导出的交互组件跟随其内置执行状态变化；clean 模式的 thought 详情使用活动时间线自身的展开状态，full 和 compact 模式则保留 Pi 内置的 Thinking 可见性控制。由于 Pi 目前没有为这些展示细节提供公开渲染钩子，自适应的原生用户消息气泡、原生输入编辑器圆角、无序列表标记和围栏代码块增强需要使用可安全重载的运行时补丁。Markdown 增强仅在渲染主 transcript 中的用户消息和助手回复时启用；扩展 overlay 创建的 Markdown 保持 Pi 原生布局。Markdown 解析、语法高亮和终端语义区域仍由 Pi 处理。
 

package/extensions/full-frame.ts

@@ -1,3 +1,4 @@
+import { selectableRow, selectionMetadataActive } from "./selection-ranges.js";
 import { cardSurface } from "./card-surface.js";
 import { isNativeImageRow, stripAnsiBackgrounds } from "./ansi-style.js";
 import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
@@ -44,7 +45,7 @@ function renderPanel(
 ): NativeFrame {
   const palette = ["borderMuted", "text", "accent", "success", "error", titleColor, borderColor]
     .map((role) => theme.fg(role, "x")).join("|") + (theme.bold?.("x") ?? "x") +
-    cardSurface(theme, borderColor, background).signature;
+    cardSurface(theme, borderColor, background).signature + selectionMetadataActive();
   const sectionKey = titleColor + borderColor + footer + background + JSON.stringify([...sections]);
   const cached = cacheOwner ? frameCache.get(cacheOwner) : undefined;
   if (cached && cached.title === title && cached.width === width && cached.palette === palette && cached.sections === sectionKey &&
@@ -58,6 +59,7 @@ function renderPanel(
   const border = (s: string) => theme.fg(borderColor, s);
   const plainCaption = truncateToWidth(title, width - 6, "…");
   const caption = theme.fg(titleColor, theme.bold?.(plainCaption) ?? plainCaption);
+  const copyRanges: Array<Array<[number, number]>> | undefined = selectionMetadataActive() ? [[]] : undefined;
   const lines = [border("╭─ ") + caption + border(" " + "─".repeat(Math.max(0, width - visibleWidth(plainCaption) - 5)) + "╮")];
   source.forEach((row, sourceY) => {
     const section = sections.get(sourceY);
@@ -66,19 +68,28 @@ function renderPanel(
       const label = theme.fg(section.color, plainLabel);
       sourceRows.set(lines.length, sourceY);
       lines.push(border("├─ ") + label + border(" " + "─".repeat(Math.max(0, width - visibleWidth(plainLabel) - 5)) + "┤"));
+      copyRanges?.push([]);
     }
     sourceRows.set(lines.length, sourceY);
-    if (isNativeImageRow(row)) lines.push(row);
+    if (isNativeImageRow(row)) { lines.push(row); copyRanges?.push([]); }
     else {
       const content = stripAnsiBackgrounds(row);
-      lines.push(border("│ ") + content + " ".repeat(Math.max(0, contentWidth - visibleWidth(content))) + border(" │"));
+      const length = visibleWidth(content);
+      lines.push(border("│ ") + content + " ".repeat(Math.max(0, contentWidth - length)) + border(" │"));
+      copyRanges?.push([[2, 2 + Math.max(1, Math.min(contentWidth, length))]]);
     }
   });
   const footerFits = footer && visibleWidth(footer) + 6 <= width;
   lines.push(footerFits
     ? border("╰" + "─".repeat(width - visibleWidth(footer) - 5) + " " + footer + " ─╯")
     : border("╰" + "─".repeat(width - 2) + "╯"));
-  const frame = { lines: lines.map((line) => cardBackground(line, width, theme, background, borderColor)), sourceRows, contentWidth, inset: 2 };
+  copyRanges?.push([]);
+  // Apply backgrounds before adding this frame's annotations so the width
+  // cache doesn't retain an extra marked variant of every newly painted row.
+  const frame = { lines: lines.map((line, i) => {
+    const painted = cardBackground(line, width, theme, background, borderColor);
+    return copyRanges ? selectableRow(painted, width, copyRanges[i]) : painted;
+  }), sourceRows, contentWidth, inset: 2 };
   if (cacheOwner) frameCache.set(cacheOwner, { title, source: source.slice(), width, palette, sections: sectionKey, frame });
   return frame;
 }
@@ -98,7 +109,7 @@ export function frameNativeRows(
   const cached = gutterFrames.get(frame);
   if (cached) return cached;
   const padded = { ...frame, inset: frame.inset + margin,
-    lines: frame.lines.map((line) => isNativeImageRow(line) ? line : " ".repeat(margin) + line + " ".repeat(margin)),
+    lines: frame.lines.map((line) => isNativeImageRow(line) ? line : selectableRow(" ".repeat(margin) + line + " ".repeat(margin), width, [[margin, width - margin]])),
   };
   gutterFrames.set(frame, padded);
   return padded;

package/extensions/index.ts

@@ -1,7 +1,8 @@
+import { installSelectionCopy, selectableRow, selectionMetadataActive } from "./selection-ranges.js";
 import { isNativeImageRow } from "./ansi-style.js";
 import { cardMargin, cardBackground, frameNativeRows, nativeFrameWidth } from "./full-frame.js";
 import { ThoughtPresentation } from "./thought-presentation.js";
-import { isThirdPartyTool, renderToolProjection, toolLabel, type ToolProjection } from "./tool-presentation.js";
+import { isThirdPartyTool, renderToolProjection, THIRD_PARTY_TOOL, toolLabel, type ToolProjection } from "./tool-presentation.js";
 import { NestedTools, NESTED_SNAPSHOT_ENTRY } from "./nested-tools.js";
 import {
   AssistantMessageComponent,
@@ -62,6 +63,8 @@ const RESPONSE_FOOTER_ENTRY_TYPE = "pretty-tui-response-footer";
 type PrettyTuiConfig = {
   enabled?: boolean;
   mode?: PrettyTuiMode;
+  /** Exclude plugin decoration from fullscreen selections. Opt-in. */
+  selectionCopy?: boolean;
   /** Legacy location used by the first mode implementation. */
   bash?: {
     mode?: "full" | "compact";
@@ -676,7 +679,9 @@ export default function prettyTui(pi: ExtensionAPI) {
         { value: "full", label: "full", description: "Full tool details and output" },
         { value: "compact", label: "compact", description: "Concise summaries for all built-in tools" },
         { value: "clean", label: "clean", description: "Group supported tools into Running/Done status" },
-        { value: "status", label: "status", description: "Show the current mode" },
+        { value: "selection-copy on", label: "selection-copy on", description: "Copy selected text without UI borders in fullscreen mode; enable and reload" },
+        { value: "selection-copy off", label: "selection-copy off", description: "Restore native selection copying and reload" },
+        { value: "status", label: "status", description: "Show the current settings" },
       ];
       const filtered = items.filter((item) => item.value.startsWith(prefix.trim().toLowerCase()));
       return filtered.length > 0 ? filtered : null;
@@ -687,7 +692,7 @@ export default function prettyTui(pi: ExtensionAPI) {
       if (!requested) {
         if (!ctx.hasUI) {
           ctx.ui.notify(
-            `pi-pretty-tui: ${config.enabled !== false ? "enabled" : "disabled"} · mode: ${renderMode}`,
+            `pi-pretty-tui: ${config.enabled !== false ? "enabled" : "disabled"} · mode: ${renderMode} · selection copy: ${config.selectionCopy === true ? "on" : "off"}`,
             "info",
           );
           return;
@@ -696,9 +701,12 @@ export default function prettyTui(pi: ExtensionAPI) {
         const full = `Full — full tool details and output${renderMode === "full" ? " (current)" : ""}`;
         const compact = `Compact — concise tool summaries and nested calls${renderMode === "compact" ? " (current)" : ""}`;
         const clean = `Clean — group supported tools into Running/Done status${renderMode === "clean" ? " (current)" : ""}`;
-        const selected = await ctx.ui.select("pi-pretty-tui settings", [enabled, full, compact, clean]);
+        const selectionCopy = `Selection copy — ${config.selectionCopy === true ? "on" : "off"} · copy text without UI borders (fullscreen, experimental)`;
+        const selected = await ctx.ui.select("pi-pretty-tui settings", [enabled, full, compact, clean, selectionCopy]);
         if (!selected) return;
-        requested = selected === enabled
+        requested = selected === selectionCopy
+          ? config.selectionCopy === true ? "selection-copy off" : "selection-copy on"
+          : selected === enabled
           ? config.enabled !== false ? "disable" : "enable"
           : selected === full
             ? "full"
@@ -709,11 +717,28 @@ export default function prettyTui(pi: ExtensionAPI) {
 
       if (requested === "status") {
         ctx.ui.notify(
-          `pi-pretty-tui: ${config.enabled !== false ? "enabled" : "disabled"} · mode: ${renderMode}`,
+          `pi-pretty-tui: ${config.enabled !== false ? "enabled" : "disabled"} · mode: ${renderMode} · selection copy: ${config.selectionCopy === true ? "on" : "off"}`,
           "info",
         );
         return;
       }
+      if (requested === "selection-copy on" || requested === "selection-copy off") {
+        const selectionCopy = requested.endsWith(" on");
+        try {
+          saveConfig({ ...config, selectionCopy });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          ctx.ui.notify(`Could not save selection-copy setting: ${message}`, "error");
+          return;
+        }
+        ctx.ui.notify(`Border-free selection copying ${selectionCopy ? "enabled" : "disabled"}; reloading…`, "info");
+        try { await ctx.reload(); }
+        catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          ctx.ui.notify(`Setting saved, but automatic reload failed: ${message}`, "warning");
+        }
+        return;
+      }
       if (requested === "enable" || requested === "disable") {
         const enabled = requested === "enable";
         try {
@@ -737,7 +762,7 @@ export default function prettyTui(pi: ExtensionAPI) {
         }
       }
       if (requested !== "full" && requested !== "compact" && requested !== "clean") {
-        ctx.ui.notify("Usage: /pretty-tui [enable|disable|full|compact|clean|status]", "error");
+        ctx.ui.notify("Usage: /pretty-tui [enable|disable|full|compact|clean|status|selection-copy on|selection-copy off]", "error");
         return;
       }
 
@@ -764,6 +789,7 @@ export default function prettyTui(pi: ExtensionAPI) {
   // render patches or override built-in tools until the next enabled reload.
   if (!activeForSession) return;
   pi.on("session_shutdown", stopWorkingElapsedTimer);
+  if (config.selectionCopy === true) pi.on("session_shutdown", installSelectionCopy());
 
   // Give Pi's main prompt editor a complete rounded frame. Render the native
   // editor at a two-column narrower width so cursor layout, wrapping, IME, and
@@ -812,9 +838,9 @@ export default function prettyTui(pi: ExtensionAPI) {
 
       return lines.map((line, index) => {
         const fitted = fitInnerWidth(line);
-        if (index === 0) return this.borderColor("╭") + fitted + this.borderColor("╮");
-        if (index === bottomBorderIndex) return this.borderColor("╰") + fitted + this.borderColor("╯");
-        if (index < bottomBorderIndex) return this.borderColor("│") + fitted + this.borderColor("│");
+        if (index === 0) return selectableRow(this.borderColor("╭") + fitted + this.borderColor("╮"), width, []);
+        if (index === bottomBorderIndex) return selectableRow(this.borderColor("╰") + fitted + this.borderColor("╯"), width, []);
+        if (index < bottomBorderIndex) return selectableRow(this.borderColor("│") + fitted + this.borderColor("│"), width, [[1, width - 1]]);
         // Autocomplete remains outside the input frame, aligned to its content.
         return " " + fitted + " ";
       });
@@ -980,9 +1006,10 @@ export default function prettyTui(pi: ExtensionAPI) {
           const bottom = border("╰" + "─".repeat(Math.max(0, measured.frameWidth - 2)) + "╯");
           const body = measured.body.map((line: string) => {
             const padding = " ".repeat(Math.max(0, measured.contentWidth - visibleWidth(line)));
-            return border("│ ") + line + padding + border(" │");
+            return selectableRow(border("│ ") + line + padding + border(" │"), measured.frameWidth, [[2, 2 + Math.max(1, Math.min(measured.contentWidth, visibleWidth(line)))]]);
           });
-          return [top, ...body, bottom].map((line: string) => left + line + right);
+          return [selectableRow(top, measured.frameWidth, []), ...body, selectableRow(bottom, measured.frameWidth, [])]
+            .map((line: string) => selectableRow(left + line + right, width, [[measured.leftPad, width - measured.rightPad]]));
         },
         handleMouse(event: any) {
           const measured = layout(event.width);
@@ -2274,6 +2301,21 @@ export default function prettyTui(pi: ExtensionAPI) {
       return originalInvalidate.call(this);
     };
 
+    const copyRows = new WeakMap<object, { source: string[]; padding: number; lines: string[] }>();
+    const selectableMarkdown = (owner: any, source: string[]) => {
+      if (!selectionMetadataActive()) return source;
+      const padding = Math.max(0, Number(owner.paddingX) || 0);
+      if (!padding) return source;
+      const cached = copyRows.get(owner);
+      if (cached?.source === source && cached.padding === padding) return cached.lines;
+      const lines = source.map(line => {
+        const width = visibleWidth(line);
+        return selectableRow(line, width, [[Math.min(padding, width), Math.max(Math.min(padding, width), width - padding)]]);
+      });
+      copyRows.set(owner, { source, padding, lines });
+      return lines;
+    };
+
     const patchedRender = function (this: any, width: number): string[] {
       const scoped = transcriptMarkdownActive();
       mouseClickHitTests.set(this, (event) => fullscreenTui &&
@@ -2293,7 +2335,7 @@ export default function prettyTui(pi: ExtensionAPI) {
       if (needsRender) this[codeBlockCollectionKey] = [];
 
       const lines = originalRender.call(this, width);
-      if (!needsRender) return lines;
+      if (!needsRender) return selectableMarkdown(this, lines);
 
       const regions: Array<{ xStart: number; xEnd: number; y: number; code: string }> = [];
       let searchFrom = 0;
@@ -2321,7 +2363,7 @@ export default function prettyTui(pi: ExtensionAPI) {
       }
       this[codeBlockRegionsKey] = regions;
       delete this[codeBlockCollectionKey];
-      return lines;
+      return selectableMarkdown(this, lines);
     };
 
     const patchedRenderToken = function (
@@ -2479,14 +2521,12 @@ export default function prettyTui(pi: ExtensionAPI) {
         (showCopyButton ? this.theme.codeBlockBorder(` ${copyLabel} `) : "") + frameBorder("╮");
       const framedCodeWidth = Math.max(1, frameWidth - 4);
       const lines = [
-        styledTopRule,
-        ...codeLines.map((line) =>
-          frameBorder("│ ") +
-          line +
-          " ".repeat(Math.max(0, framedCodeWidth - visibleWidth(line))) +
-          frameBorder(" │")
-        ),
-        frameBorder(`╰${"─".repeat(Math.max(0, frameWidth - 2))}╯`),
+        selectableRow(styledTopRule, frameWidth, []),
+        ...codeLines.map((line) => selectableRow(
+          frameBorder("│ ") + line +
+          " ".repeat(Math.max(0, framedCodeWidth - visibleWidth(line))) + frameBorder(" │"),
+          frameWidth, [[2, frameWidth - 2]])),
+        selectableRow(frameBorder(`╰${"─".repeat(Math.max(0, frameWidth - 2))}╯`), frameWidth, []),
       ];
 
       if (showCopyButton && Array.isArray(this[codeBlockCollectionKey])) {
@@ -3182,13 +3222,12 @@ export default function prettyTui(pi: ExtensionAPI) {
           if (lines.length === 0) return lines;
           contentLines = lines[0] === "" ? lines.slice(1) : lines;
         }
-        decoratedContent = contentLines.map((line: string, index: number) =>
-          truncateToWidth(
-            (index === 0 ? childPrefix : continuation) + line,
-            Math.max(1, width),
-            "",
-          )
-        );
+        decoratedContent = contentLines.map((line: string, index: number) => {
+          const prefix = index === 0 ? childPrefix : continuation;
+          const rendered = truncateToWidth(prefix + line, Math.max(1, width), "");
+          return selectionMetadataActive()
+            ? selectableRow(rendered, visibleWidth(rendered), [[visibleWidth(prefix), visibleWidth(rendered)]]) : rendered;
+        });
         if (cacheable) {
           this[cleanChildRenderCacheKey] = {
             width,
@@ -4333,21 +4372,31 @@ export default function prettyTui(pi: ExtensionAPI) {
     grep: createGrepToolDefinition(cwd), find: createFindToolDefinition(cwd), ls: createLsToolDefinition(cwd),
   };
   const registerStyledTool = (definition: any) => {
-    const native = nativeDefinitions[definition.name];
-    const select = (kind: "renderCall" | "renderResult", args: any[]) => {
-      const context = args.at(-1);
-      const useNative = renderMode === "full" || renderMode === "compact" && context.expanded;
-      const namespace = useNative ? "nativeFull" : "pretty";
-      const state = context.state[namespace] ??= { state: {} };
-      const scoped = { ...context, state: state.state, lastComponent: state[kind] };
-      const renderer = useNative ? native[kind] : definition[kind];
-      const component = renderer?.(...args.slice(0, -1), scoped);
-      state[kind] = component;
-      return component;
-    };
-    pi.registerTool({ ...definition,
-      renderCall: (...args: any[]) => select("renderCall", args),
-      renderResult: (...args: any[]) => select("renderResult", args),
+    pi.registerToolRenderer((name, next) => {
+      const downstream = next();
+      if (name !== definition.name) return downstream;
+      // A same-named extension/SDK tool owns its own rendering and parameters.
+      // In particular, do not apply built-in summaries to an unrelated schema.
+      const source = pi.getAllTools().find((tool) => tool.name === name)?.sourceInfo;
+      if (source && source.path !== `builtin:${name}`) {
+        return downstream ? { ...downstream, [THIRD_PARTY_TOOL]: true } : downstream;
+      }
+      const native = nativeDefinitions[name];
+      const select = (kind: "renderCall" | "renderResult", args: any[]) => {
+        const context = args.at(-1);
+        const useNative = renderMode === "full" || renderMode === "compact" && context.expanded;
+        const namespace = useNative ? "nativeFull" : "pretty";
+        const state = context.state[namespace] ??= { state: {} };
+        const scoped = { ...context, state: state.state, lastComponent: state[kind] };
+        const renderer = useNative ? downstream?.[kind] ?? native[kind] : definition[kind];
+        const component = renderer?.(...args.slice(0, -1), scoped);
+        state[kind] = component;
+        return component;
+      };
+      return { ...downstream, renderShell: "self",
+        renderCall: (...args: any[]) => select("renderCall", args),
+        renderResult: (...args: any[]) => select("renderResult", args),
+      };
     });
   };
 

package/extensions/selection-ranges.ts

@@ -0,0 +1,245 @@
+import { randomBytes } from "node:crypto";
+import { ProcessTerminal, TuiAltScreen, sliceByColumn, stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
+
+type Span = [number, number];
+// Session-local APC annotations travel through opaque Container wrappers as
+// zero-width text. They are removed before any terminal write or clipboard use.
+const prefix = `\x1b_ppt-select-${randomBytes(6).toString("hex")}:`;
+const suffix = "\x1b\\";
+const marker = new RegExp(prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "([0-9,;]*)\x1b\\\\", "g");
+let enabled = false;
+export const selectionMetadataActive = () => enabled;
+export const removeSelectionMetadata = (text: string): string => text.includes(prefix) ? text.replace(marker, "") : text;
+const subtract = (spans: Span[], start: number, end: number): Span[] => spans.flatMap(([a, b]) => {
+  if (end <= a || start >= b) return [[a, b] as Span];
+  const rest: Span[] = [];
+  if (a < start) rest.push([a, start]);
+  if (end < b) rest.push([end, b]);
+  return rest;
+});
+
+type Annotation = { width: number; excluded: Span[] };
+const decoded = new Map<string, Annotation>();
+const encoded = new Map<string, string>();
+function annotation(payload: string): Annotation | undefined {
+  const cached = decoded.get(payload);
+  if (cached) return cached;
+  const fields = payload.split(";");
+  const width = Number(fields.shift());
+  if (!Number.isSafeInteger(width) || width < 0) return undefined;
+  const excluded: Span[] = [];
+  let cursor = 0;
+  for (const field of fields) {
+    if (!field) continue;
+    const values = field.split(",").map(Number);
+    if (values.length !== 2) return undefined;
+    const [a, b] = values;
+    if (!Number.isSafeInteger(a) || !Number.isSafeInteger(b) || a < cursor || b < a || b > width) return undefined;
+    if (cursor < a) excluded.push([cursor, a]);
+    cursor = b;
+  }
+  if (cursor < width) excluded.push([cursor, width]);
+  const result = { width, excluded };
+  if (decoded.size >= 1024) decoded.delete(decoded.keys().next().value!);
+  decoded.set(payload, result);
+  return result;
+}
+
+/** Mark only known plugin decoration. Inner annotations are composed, never
+ * inferred from glyphs, so actual box art and code strings remain untouched. */
+export function selectableRow(line: string, width: number, keep: Span[]): string {
+  if (!enabled || line.includes("\x1b_G") || line.includes("\x1b]1337;File=")) return line;
+  const payload = width + (keep.length ? ";" + keep.map(([a, b]) => a + "," + b).join(";") : "");
+  let tag = encoded.get(payload);
+  if (!tag) {
+    tag = prefix + payload + suffix;
+    if (encoded.size >= 1024) encoded.delete(encoded.keys().next().value!);
+    encoded.set(payload, tag);
+  }
+  return tag + line;
+}
+
+function scrollBox(root: any, owner: any): any {
+  if (!root) return undefined;
+  if (root.scrollView === owner) return root;
+  for (const child of root.children ?? []) {
+    const found = scrollBox(child, owner);
+    if (found) return found;
+  }
+}
+
+function viewportRows(root: any, first: number, last: number, offsetX = 0, offsetY = 0, offscreen = false): Map<number, Array<{ line: string; x: number; left: number; right: number }>> {
+  const result = new Map<number, Array<{ line: string; x: number; left: number; right: number }>>();
+  const visit = (box: any) => {
+    if (!box?.rect || !box.clip) return;
+    const vertical = offscreen ? box.rect : box.clip;
+    if (vertical.y + offsetY > last || vertical.y + vertical.height + offsetY <= first) return;
+    if (box.children?.length) { for (const child of box.children) visit(child); return; }
+    if (!box.lines) return;
+    const start = Math.max(first - offsetY, box.rect.y, vertical.y);
+    const end = Math.min(last + 1 - offsetY, box.rect.y + box.rect.height, vertical.y + vertical.height);
+    for (let row = start; row < end; row++) {
+      const line = box.lines[row - box.rect.y + (box.lineOffset ?? 0)];
+      if (line === undefined) continue;
+      const records = result.get(row + offsetY) ?? [];
+      records.push({ line, x: box.rect.x + offsetX, left: Math.max(box.rect.x, box.clip.x) + offsetX,
+        right: Math.min(box.rect.x + box.rect.width, box.clip.x + box.clip.width) + offsetX });
+      result.set(row + offsetY, records);
+    }
+  };
+  visit(root);
+  return result;
+}
+
+type Surface = { row: number; col: number; width: number; height: number; lines?: string[] };
+
+/** Capture rows during the native compositor's single render, not by rendering
+ * a component again at copy time. Restore the exact previous own descriptor. */
+function captureRender(target: any, name: string, receive: (rows: string[]) => void): () => void {
+  const method = target?.[name];
+  if (typeof method !== "function") return () => {};
+  const own = Object.getOwnPropertyDescriptor(target, name);
+  const capture = function (this: any, ...args: any[]) {
+    const result = method.apply(this, args);
+    if (Array.isArray(result)) receive(result);
+    return result;
+  };
+  Object.defineProperty(target, name, { configurable: true, writable: true, value: capture });
+  return () => {
+    if (target[name] !== capture) return;
+    if (own) Object.defineProperty(target, name, own);
+    else delete target[name];
+  };
+}
+
+function excludedColumns(line: string): Span[] {
+  if (!line.includes(prefix)) return [];
+  const excluded: Span[] = [];
+  for (const match of line.matchAll(marker)) {
+    const tag = annotation(match[1]);
+    if (!tag) continue;
+    // A start annotation survives native right-edge clipping. Prefixes are
+    // normally only outer annotations and padding, so this stays inexpensive.
+    const origin = visibleWidth(line.slice(0, match.index));
+    for (const [a, b] of tag.excluded) excluded.push([origin + a, origin + b]);
+  }
+  return excluded;
+}
+
+export function installSelectionCopy(): () => void {
+  const screen = TuiAltScreen.prototype as any;
+  const terminal = ProcessTerminal.prototype as any;
+  const key = Symbol.for("pretty-tui.selection-ranges");
+  if (screen[key]) return () => {};
+  const originalCopy = screen.getActiveSelectionText;
+  const originalWrite = terminal.write;
+  const originalOverlays = screen.compositeOverlays;
+  const originalFlashes = screen.compositeFlashes;
+  if (typeof originalCopy !== "function" || typeof originalWrite !== "function" ||
+    typeof originalOverlays !== "function" || typeof originalFlashes !== "function") return () => {};
+  const overlays = new WeakMap<object, Surface[]>();
+  const flashes = new WeakMap<object, Surface[]>();
+  const compositeOverlays = function (this: any, lines: string[], width: number, height: number) {
+    if (!this.overlayStack?.length) {
+      overlays.delete(this);
+      return originalOverlays.call(this, lines, width, height);
+    }
+    const captured: string[][] = [];
+    const restore = captureRender(this, "resolveFakeCursors", rows => captured.push(rows));
+    let result: string[];
+    try { result = originalOverlays.call(this, lines, width, height); }
+    finally { restore(); }
+    overlays.set(this, (this.renderedOverlayLayouts ?? []).map((box: Surface, i: number) => ({
+      row: box.row, col: box.col, width: box.width, height: box.height, lines: captured[i],
+    })));
+    return result;
+  };
+  const compositeFlashes = function (this: any, lines: string[], width: number, height: number) {
+    if (Array.isArray(this.flashes?.entries) && this.flashes.entries.length === 0) {
+      flashes.delete(this);
+      return originalFlashes.call(this, lines, width, height);
+    }
+    let captured: string[] = [];
+    const restore = captureRender(this.flashes, "render", rows => { captured = rows; });
+    let result: string[];
+    try { result = originalFlashes.call(this, lines, width, height); }
+    finally { restore(); }
+    flashes.set(this, captured.slice(-height).map((line, row) => ({
+      row, col: width - visibleWidth(line), width: visibleWidth(line), height: 1, lines: [line],
+    })));
+    return result;
+  };
+  const copy = function (this: any): string | undefined {
+    const selection = this.getSelectionBounds();
+    if (!selection) return undefined;
+    const inScroll = Boolean(selection.start.scrollView);
+    const scroll = inScroll ? scrollBox(this.currentLayout?.root, selection.start.scrollView) : undefined;
+    const lines: string[] | undefined = inScroll ? scroll?.scrollContentLines : this.previousScreen;
+    if (!lines) return originalCopy.call(this);
+    const viewport = inScroll
+      ? viewportRows(scroll?.children?.[0], selection.start.row, selection.end.row,
+        -scroll.rect.x, selection.start.scrollView.scrollTop - scroll.rect.y, true)
+      : viewportRows(this.currentLayout?.root, selection.start.row, selection.end.row);
+    const surfaces: Surface[] = [];
+    if (!inScroll) {
+      const jump = this.scrollToEndIndicatorRect;
+      if (jump) surfaces.push({ row: jump.row, col: jump.column, width: jump.width, height: 1 });
+      surfaces.push(...overlays.get(this) ?? [], ...flashes.get(this) ?? []);
+    }
+    const copied: string[] = [];
+    for (let row = selection.start.row; row <= selection.end.row; row++) {
+      const line = lines[row] ?? "";
+      const columns = this.getSelectionColumns(line, row, selection);
+      // Composited/sliced metadata may no longer describe the full fragment.
+      // Prefer current raw leaves whenever layout information is available.
+      let excluded = this.currentLayout ? [] as Span[] : excludedColumns(line);
+      let annotated = line.includes(prefix);
+      const paint = (source: string | undefined, x: number, left: number, right: number) => {
+        if (right <= left) return;
+        // A later surface replaces lower decoration, including when the later
+        // surface is ordinary text with no private annotation at all.
+        excluded = subtract(excluded, left, right);
+        if (!source?.includes(prefix)) return;
+        annotated = true;
+        for (const [a, b] of excludedColumns(source)) {
+          const start = Math.max(left, x + a), end = Math.min(right, x + b);
+          if (end > start) excluded.push([start, end]);
+        }
+      };
+      for (const record of viewport?.get(row) ?? []) paint(record.line, record.x, record.left, record.right);
+      for (const surface of surfaces) {
+        if (row < surface.row || row >= surface.row + surface.height) continue;
+        paint(surface.lines?.[row - surface.row], surface.col,
+          Math.max(0, surface.col), Math.min(visibleWidth(line), surface.col + surface.width));
+      }
+      let spans: Span[] = columns.end > columns.start ? [[columns.start, columns.end]] : [];
+      for (const [a, b] of excluded) spans = subtract(spans, a, b);
+      if (annotated && !spans.length) continue;
+      copied.push(spans.map(([a, b]) => stripTerminalSequences(sliceByColumn(line, a, Math.max(0, b - a), true))).join("").trimEnd());
+    }
+    const result = copied.join("\n");
+    return result.length ? result : undefined;
+  };
+  const write = function (this: any, data: string) { return originalWrite.call(this, removeSelectionMetadata(data)); };
+  const methods = [
+    [screen, "getActiveSelectionText", originalCopy, copy],
+    [screen, "compositeOverlays", originalOverlays, compositeOverlays],
+    [screen, "compositeFlashes", originalFlashes, compositeFlashes],
+    [terminal, "write", originalWrite, write],
+  ] as const;
+  const originalOwn = methods.map(([target, name]) => Object.getOwnPropertyDescriptor(target, name));
+  screen[key] = { methods };
+  for (const [target, name, , patched] of methods) target[name] = patched;
+  enabled = true;
+  return () => {
+    enabled = false;
+    decoded.clear();
+    encoded.clear();
+    methods.forEach(([target, name, , patched], i) => {
+      if (target[name] !== patched) return;
+      if (originalOwn[i]) Object.defineProperty(target, name, originalOwn[i]!);
+      else delete target[name];
+    });
+    if (screen[key]?.methods === methods) delete screen[key];
+  };
+}

package/extensions/tool-presentation.ts

@@ -7,7 +7,11 @@ import type { NestedTools } from "./nested-tools.js";
 // Tool content and hit regions are independent of activity grouping. The host
 // decides whether to decorate this projection with a clean activity tree.
 export const SPECIALIZED_TOOL_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls"]);
+// A third-party renderer can also use renderShell: "self". The shell style is
+// not proof that it is one of our specialized built-in renderers.
+export const THIRD_PARTY_TOOL = Symbol("pretty-tui.third-party-tool");
 export const isThirdPartyTool = (owner: any): boolean =>
+  Boolean(owner.toolDefinition?.[THIRD_PARTY_TOOL]) ||
   !SPECIALIZED_TOOL_NAMES.has(owner.toolName) || owner.toolDefinition?.renderShell !== "self";
 
 export const toolLabel = (toolName: string, label?: string): string => label || toolName;
@@ -29,7 +33,9 @@ const conciseThirdPartyArgs = (args: any): string => {
       const safeValue = String(value)
         .replace(/(https?:\/\/)[^\s/@:]+:[^\s/@]+@/giu, "$1…:…@")
         .replace(/([?&](?:token|secret|password|api[_-]?key)=)[^&\s]+/giu, "$1…");
-      const rendered = truncateToWidth(safeValue, 36, "…");
+      // Argument previews are plain text. The truncator emits SGR resets even
+      // for unstyled input; remove those before applying the shared muted role.
+      const rendered = stripTerminalSequences(truncateToWidth(stripTerminalSequences(safeValue), 36, "…"));
       return `${key}=${rendered}`;
     });
   return entries.join(" · ");
@@ -45,7 +51,7 @@ const thirdPartyResultSummary = (component: any): string => {
   const newline = boundedText.indexOf("\n");
   const boundedFirstLine = boundedText.slice(0, newline < 0 ? boundedText.length : newline);
   const firstLine = stripTerminalSequences(boundedFirstLine).trim();
-  if (firstLine) return truncateToWidth(firstLine, 72, "…");
+  if (firstLine) return stripTerminalSequences(truncateToWidth(firstLine, 72, "…"));
   if (component.result) return component.result.isError ? "Failed" : "Done";
   return component.executionStarted ? "Running…" : "Pending";
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pretty-tui",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "A beautiful, polished TUI for the Pi coding agent",
   "license": "MIT",
   "author": "Kainan Yang <ykn0309@whu.edu.cn>",
@@ -15,7 +15,13 @@
   },
   "scripts": {
     "typecheck": "tsc -p tsconfig.json",
-    "test": "npm run typecheck && node tests/regression.mjs"
+    "test": "npm run typecheck && node tests/regression.mjs && node tests/coexistence.mjs && node tests/selection-ranges.mjs && node tests/selection-options.mjs",
+    "test:selection-pty": "python3 tests/selection-pty.py",
+    "bench:selection": "node tests/selection-benchmark.mjs",
+    "test:selection-cli": "python3 tests/selection-cli.py",
+    "bench:selection-frame": "node tests/selection-frame-benchmark.mjs",
+    "bench:selection-memory": "node --expose-gc tests/selection-memory-benchmark.mjs",
+    "test:selection-gc": "node --expose-gc tests/selection-gc.mjs && node --expose-gc tests/selection-reload-gc.mjs"
   },
   "keywords": [
     "pi-package",
@@ -39,8 +45,8 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "^24.0.0",
     "jiti": "^2.7.0",
     "typescript": "^5.9.0"