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 presents code blocks with syntax highlighting, boxed borders and an inline copy control, and 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. A separate Pretty Codeblocks installation is not required.

🎯 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

Pi loads the TypeScript entrypoint through its extension loader so it shares the host's TUI component. npm run build remains available for the distributable JavaScript bundle and type declarations.

⌨️ Available Commands

Experimental inline copy

In Pi's fullscreen TUI, completed fenced code blocks display a [ copiar ] control on the right side of compatible boxed borders, or above the block when there is no room. Click it to copy that specific block's original source without terminal borders or syntax colors. A notification confirms success or reports a clipboard error. The regular /rich commands remain available, including in terminals that do not route mouse events.

This experimental integration patches Pi's internal Markdown component because the extension API does not yet expose interactive assistant code blocks. Compatibility with Pi updates is not guaranteed. Restart Pi after changing extensions. Blocks are selectable once their closing Markdown fence has arrived. The control is intended for completed, top-level fenced blocks; nested or transformed Markdown may not display it. Terminal text selection still copies whatever is drawn on screen.

The built-in presentation is adapted from pi-pretty-codeblocks, Copyright (c) 2026 Vlad, MIT License; the full license is retained in src/pretty-codeblocks.ts. The box is enabled by default. Set PI_PRETTY_CODEBLOCKS_BOX=0 for the unboxed style, PI_PRETTY_CODEBLOCKS_COMPACT=1 for compact lines, or PI_PRETTY_CODEBLOCKS_LANG=0 to hide language labels (restart Pi after changing these variables). If the original extension is also loaded, its presentation is used to avoid stacking render patches; remove it once the integrated style has been verified.

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