pi-rich-render

Pi Rich Renderer is a modular TypeScript extension for Pi Coding Agent 1.0 (used inside Gentle Shell 4.0.0 on Windows). It lets you read, select, copy, and export structured code blocks, tables, diffs, JSON/YAML/XML, lists, Mermaid diagrams, and LaTeX formulas inside the TUI, without polluting the clipboard with terminal decorations or borders.

🎯 Guiding Principle

The original source is always kept separate from its presentation. Text drawn on screen is never copied. Markdown delimiters (fences), line numbers, ANSI colors, and terminal borders are excluded from the copy, preserving exact indentation, blank lines, and Unicode characters.

🚀 Installation

Install the published package with Pi:

pi install npm:pi-rich-render

To run directly from source with Pi's native jiti:

pi --extension ./src/extension-entrypoint.ts

This command from the source code still works without compiling. When installing from a clone, run npm run build once before the compiled entrypoint that Pi loads exists.

⌨️ Available Commands

Block picker

The picker shows newest blocks first while preserving each block's original #N index (#1 is oldest). Use a type prefix such as sql, table, or json to filter. The picker supports wrapping arrow navigation, paging, and direct copy/view shortcuts:

↑↓/j k navigate · PgUp/PgDn page · / filter by type · c copy · v view · Enter menu · Esc/q cancel

In filter mode, Escape keeps the applied filter; press Escape again to clear it. /rich copy n and /rich view n bypass the picker for a valid block index.

Clipboard

Windows uses PowerShell Set-Clipboard and falls back to clip if unavailable; macOS uses pbcopy; Linux uses wl-copy or xclip. If no tool is found, copying fails with a clear error. As an alternative when no local tool is found, OSC 52 is used if PI_CLIPBOARD_OSC52=1 or if the session is running over SSH. OSC 52 depends on terminal support; some terminals disable it. Copied text remains plain text: no fences, ANSI, or borders.

📊 Block-Type Capabilities

• Source code (SQL, TypeScript, Python, Bash, C#, etc.):
  • Copies without fences or borders and preserves indentation.
  • Preview with line numbering and scrolling (↑/↓ or j/k).
• Markdown tables:
  • Precise detection of headers and alignments (left, center, right).
  • TSV export: Tab-delimited format ideal for pasting into Excel or Google Sheets.
  • JSON export: Safely converts to an array of objects (blocked if headers are duplicated or empty to avoid inventing properties).
  • CSV export: Spreadsheet-compatible format, with quoting according to RFC 4180.
  • Normalized Markdown: Preserves alignments, escapes pipes, and replaces line breaks within cells.
  • Interactive preview with clean borders and horizontal/vertical scrolling (h/j/k/l).
• Diffs:
  • Highlights additions (+) and deletions (-) in the viewer.
  • Copy preserves the original pure diff without ANSI escape codes.
• JSON / YAML / XML:
  • Press f in the viewer to toggle between raw source and readable indented formatting.
  • Copy preserves the original source intact by default.
• Mermaid and LaTeX:
  • Text viewer with a fidelity warning.
  • Direct copy of the complete source syntax without requiring an external visual preview.

🧪 Automated Tests

The project has a complete unit test suite with Vitest:

npm test

Covers: fences with and without a language, ~~~ delimiters, Unicode and emoji, multiple blocks, tables with escaped pipes \|, conditional TSV/JSON exports, and clipboard command selection by operating system (Windows, macOS, and Linux), as well as OSC 52 encoding and fallback.

📋 Manual TUI Testing Guide

1. Load verification:
   • Run pi --extension ./src/extension-entrypoint.ts.
   • Verify that the notification appears: pi-rich-render ready (... history entries).
2. Clean code copy:
   • Ask the agent: "Write a TypeScript function with comments and indentation".
   • Run /rich copy or /rich last.
   • Paste into an external editor (VS Code or Notepad) and confirm there are no fences ```, line numbers, or borders.
3. Table export:
   • Ask the agent: "Show a table with ID, Name, and Role columns".
   • Run /rich copy or /rich last and select 2. TSV (Spreadsheets / Excel) or 4. CSV (Spreadsheets / Excel).
   • Paste into Excel and verify that each value is in its corresponding cell. Option 5. Markdown (normalized) preserves alignments and escapes pipes.
4. Interactive overlay view:
   • Open a code block with 100 or more lines using /rich view (you can also open the preview from /rich list). Confirm that the overlay does not exceed the terminal, that PgDn reaches the end, g goes to the beginning and G to the end, and that the last line is reachable and fully visible without losing content.
   • Test vertical scrolling with ↑/↓ and j/k, and page scrolling with PgUp/PgDn; Home/g should go to the beginning and End/G to the end. Press Esc or q to close.
   • In a block with a line wider than the terminal, use → or l until you can read it completely; confirm that line numbers remain fixed while the text scrolls horizontally.
   • Inside the overlay, press c: confirm that the help line says Copied to clipboard or Copy failed: <message>, then paste into an external editor. The pasted text must be the raw source, without fences or line numbers.
   • In fullscreen mode, check that the wheel scrolls the view and that clicking the [ copy ] label copies the block. In regular mode, check that the wheel does not scroll the overlay; navigate there with the keyboard.
5. Context list:
   • Run /rich list.
   • Confirm that it lists the detected blocks with their metadata and lets you copy them or open them.

⚠️ Known Limitations

1. Graphical diagram previews (Mermaid/LaTeX): The standard interactive terminal (TUI) does not render raster/SVG graphics for diagrams. The extension displays the structured source syntax and lets you copy it unchanged for use in dedicated viewers.
2. Context scope: The extension uses only documented public APIs (ctx.sessionManager.getBranch()). It analyzes only messages belonging to the current active conversation branch, respecting the privacy and isolation of the Pi core.

License

MIT

Issue tracker: GitHub Issues