pi-stereo-view 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Separate Conversation and Activity while keeping Pi's native message and tool renderers.
+- Arrange panels in columns or rows, swap them, resize them, and zoom either panel.
+- Search each panel with literal, Boolean and regular-expression queries.
+- Show optional timestamps and save layout preferences between sessions.
+- Keep the input dock full width and fall back to combined history in small terminals.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Shpuntenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/alexshpunt/pi-stereo-view/main/assets/logo-icon.png" alt="pi-stereo-view" width="480"><br>
+  pi-stereo-view
+</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">Keep Pi conversation separate from tool output and agent activity.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/pi-stereo-view"><img src="https://img.shields.io/npm/v/pi-stereo-view" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/pi-stereo-view"><img src="https://img.shields.io/npm/dm/pi-stereo-view" alt="npm downloads"></a>
+  <a href="https://github.com/alexshpunt/pi-stereo-view/actions/workflows/ci.yml"><img src="https://github.com/alexshpunt/pi-stereo-view/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+</p>
+
+You come back to a chat and can't remember what you were talking about?
+
+**Split tool output from the agent's replies with pi-stereo-view.**
+
+The chat becomes two zones: your conversation with the agent, and the agent's work where it calls tools.
+
+| Zone | What's in it |
+| --- | --- |
+| **Conversation** | Your messages, the LLM's replies, compaction summaries and compaction notices. |
+| **Activity** | Tool calls and results, thinking, and other messages generated by Pi. |
+
+Messages and tools keep their familiar appearance. The input stays full width below both panels.
+
+## See it in action
+
+![Switching layouts, swapping panels and resizing history](https://raw.githubusercontent.com/alexshpunt/pi-stereo-view/main/assets/demo.gif)
+
+[Watch the full demo](https://github.com/alexshpunt/pi-stereo-view/releases/download/v0.1.0/demo.mp4).
+
+### Columns
+
+Conversation beside Activity, with a full-width input below both panels.
+
+![Columns layout](https://raw.githubusercontent.com/alexshpunt/pi-stereo-view/main/assets/columns.png)
+
+### Rows
+
+Conversation above Activity. Swap the panels whenever you need a different order.
+
+![Rows layout](https://raw.githubusercontent.com/alexshpunt/pi-stereo-view/main/assets/rows.png)
+
+## Install
+
+```sh
+pi install npm:pi-stereo-view
+```
+
+Split history needs Pi's **fullscreen** mode. Choose it in `/settings`, or start Pi with:
+
+```sh
+pi --tui-mode fullscreen
+```
+
+## Use it
+
+Click the toolbar and the buttons in each panel's header:
+
+| Button | Action |
+| --- | --- |
+| `[ ▣ ]` / `[ ◫ ]` | Turn split history off / on. |
+| `[ ▤ ]` / `[ ▥ ]` | Switch between rows and columns. |
+| `[ ↕ ]` / `[ ↔ ]` | Swap the panels. |
+| `[ ↗ ]` / `[ ↙ ]` | Zoom a panel / restore the split. |
+| `[ ≡ ]` | Open settings to show or hide timestamps. |
+| `[ ⌕ ]` | Search this panel. |
+
+**Resize:** drag the double line between the panels — `═` in rows, `║` in columns.
+
+New installs start in Columns: Conversation gets 20% of the width on the left, and Activity gets 80% on the right. Drag the divider or use the size shortcuts to change this.
+
+In Rows, Conversation grows with its messages up to half the available history area, then scrolls. Dragging the divider or setting a height changes that limit. Choose **Conversation height: auto** in `≡`, or run `/stereo-view height auto`, to restore automatic sizing.
+
+Panels fit short content and scroll when history fills up. Each panel has its own scrolling, text selection and copy.
+
+Swap the panels whenever you want. Zoom a panel to give it the whole history area; the input stays visible. Restore it to return to your split. Turning split off returns to one combined history; the toolbar stays available to turn it back on.
+
+## Search history
+
+Press **Ctrl+F** to search the last clicked or scrolled panel. A dot in the header marks the active panel; Conversation is active initially. The `⌕` button always searches its own panel.
+
+Type a word or phrase to find it without case sensitivity. Combine terms with `AND`, `OR`, `NOT` and parentheses. Put phrases in quotes to keep them together, or start with `regex:` for a regular expression.
+
+| Example | Finds |
+| --- | --- |
+| `worker ready` | The literal phrase “worker ready”. |
+| `worker AND ready NOT failed` | Lines containing both “worker” and “ready”, but not “failed”. |
+| `(worker OR server) AND "ready now"` | Lines containing either term and the phrase “ready now”. |
+| `regex:worker_[0-9]+` | Names such as `worker_12`. |
+
+Press **Enter** or `[↓]` for the next match, and **Shift+Enter** for the previous one. The counter shows your position and the total matches. Ctrl+F returns to the search field without clearing your query.
+
+Search covers the whole current conversation branch, including off-screen messages, hidden thinking and collapsed tool output. It does not search other branches, sessions, attachments or files. Russian and English queries work.
+
+A match is revealed in its own panel without moving the other one. If matching text cannot be shown inside a tool result, a temporary **Search match:** fragment shows it. Copying keeps the original text, without highlight colours.
+
+**Regex search requires ripgrep (`rg`) to be installed.** Invalid queries and search errors appear in the search field instead of showing incomplete results.
+
+Press **Escape** or `[×]` to close search and restore your previous scroll position. Your message draft stays unchanged. Close other dialogs before searching. Search is available in split fullscreen history; combined history and regular mode keep Pi's usual keyboard behaviour.
+
+## Timestamps
+
+Conversation and Activity can show a dim local `HH:mm:ss` clock beside messages and tool calls. New tool calls show their start time.
+
+Older tool calls may show `~HH:mm:ss` for an approximate time. `--:--:--` means the time is unknown.
+
+Use `≡` or `/stereo-view settings` to hide or show clocks. This setting survives restart. Clocks appear in split and zoomed panels, not in combined history. They are display-only and are not added to the conversation sent to the model.
+
+## Commands and shortcuts
+
+The same controls are available without the mouse:
+
+| Action | Command |
+| --- | --- |
+| Split off / on | `/stereo-view` |
+| Swap panels | `/stereo-view swap` |
+| Rows / columns | `/stereo-view layout rows` / `/stereo-view layout columns` |
+| Conversation height / width | `/stereo-view height 12` / `/stereo-view width 40` |
+| Automatic Conversation height | `/stereo-view height auto` |
+| Scroll a panel | `/stereo-view scroll chat -10` / `/stereo-view scroll activity -10` |
+| Zoom / restore Conversation | `/stereo-view zoom chat` |
+| Zoom / restore Activity | `/stereo-view zoom activity` |
+| Timestamp settings | `/stereo-view settings` |
+| Button legend | `/stereo-view help` |
+
+`Ctrl+Alt+T` toggles split, `Ctrl+Alt+S` swaps panels, and `Ctrl+Alt+Left/Right` resizes Conversation along the current split direction.
+
+## Settings and limits
+
+Your layout, panel order, sizes, zoom, split on/off and timestamp settings are saved automatically and restored next time.
+
+- Tested with Pi 1.1.0. Requires Node.js 22.19 or newer.
+- Regular mode shows one combined history.
+- If the terminal is too small, history temporarily combines without forgetting your split.
+- If your Pi version cannot display the split, normal history stays visible and a warning explains the problem.
+
+## License
+
+[MIT](LICENSE) · [Developer guide](https://github.com/alexshpunt/pi-stereo-view/blob/main/development.md)

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "pi-stereo-view",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Keep Pi conversation separate from tool output and agent activity.",
+  "license": "MIT",
+  "author": "Alexander Shpuntenko",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexshpunt/pi-stereo-view.git"
+  },
+  "homepage": "https://github.com/alexshpunt/pi-stereo-view#readme",
+  "bugs": {
+    "url": "https://github.com/alexshpunt/pi-stereo-view/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "transcript",
+    "tui",
+    "split-pane",
+    "pi-extension",
+    "pi-coding-agent",
+    "terminal-ui"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/alexshpunt/pi-stereo-view/main/assets/logo-wordmark.png",
+    "video": "https://github.com/alexshpunt/pi-stereo-view/releases/download/v0.1.0/demo.mp4"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "profile": "vitest run --config vitest.profile.config.ts",
+    "check": "npm run typecheck && npm test",
+    "check:package": "vitest run test/package.integration.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@types/node": "^24.0.4",
+    "pi-coding-agent-test": "0.1.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/index.ts

@@ -0,0 +1,182 @@
+import path from "node:path";
+import { getAgentDir, getSettingsListTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Container, isKeyRelease, matchesKey, SettingsList, Text, type TUI } from "@earendil-works/pi-tui";
+import { TranscriptLayout } from "./layout.js";
+import { TOOL_START_ENTRY, TranscriptTimestamps } from "./timestamps.js";
+import { defaults, loadPreferences, savePreferences, type Preferences } from "./preferences.js";
+
+/** Split native fullscreen history without changing message content or the input dock. */
+export default function transcript(pi: ExtensionAPI): void {
+  let layout: TranscriptLayout | undefined;
+  let host: TUI | undefined;
+  let timestamps: TranscriptTimestamps | undefined;
+  let unsubscribeInput: (() => void) | undefined;
+  let writes = Promise.resolve();
+  let preferences: Preferences = { ...defaults };
+  const file = path.join(getAgentDir(), "transcript.json");
+
+  let settingsOpen = false;
+  const closeSearch = (): void => { layout?.closeSearch(false); };
+
+  const openSettings = async (ctx: ExtensionContext): Promise<void> => {
+    if (settingsOpen) return;
+    settingsOpen = true;
+    closeSearch();
+    try {
+      await ctx.ui.custom<void>((tui, _theme, _keys, done) => {
+        const list = new SettingsList([{
+          id: "timestamps", label: "Show timestamps",
+          description: "Hide clock rows without changing messages or recorded tool starts.",
+          currentValue: preferences.showTimestamps ? "on" : "off", values: ["on", "off"],
+        }, {
+          id: "height", label: "Conversation height",
+          description: "Auto grows to half the history area. Drag sets a manual maximum.",
+          currentValue: preferences.chatHeight === null ? "auto" : "manual", values: ["auto", "manual"],
+        }], 3, getSettingsListTheme(), (id, value) => {
+          if (id === "timestamps") layout?.setTimestamps(value === "on");
+          else if (id === "height") layout?.setAutomaticHeight(value === "auto");
+          tui.requestRender();
+        }, () => done());
+        const content = new Container();
+        content.addChild({
+          render: () => [ctx.ui.theme.fg("accent", ctx.ui.theme.bold("pi-stereo-view settings")), ""],
+          invalidate() {},
+        });
+        content.addChild(list);
+        const box = new Box(1, 1, text => ctx.ui.theme.bg("customMessageBg", text));
+        box.addChild(content);
+        return {
+          render: (width: number) => box.render(width),
+          invalidate: () => box.invalidate(),
+          handleMouse: (event) => box.handleMouse(event),
+          handleInput: (data: string) => {
+            list.handleInput(data);
+            tui.requestRender();
+          },
+        };
+      }, { overlay: true, overlayOptions: { width: 60, margin: 1 } });
+    } finally {
+      settingsOpen = false;
+    }
+    await writes;
+  };
+
+  const ensureLayout = (): void => {
+    if (host) layout?.attach(host);
+  };
+  const persist = (ctx: ExtensionContext): void => {
+    const snapshot = { ...preferences };
+    writes = writes.then(() => savePreferences(file, snapshot)).catch(error => {
+      ctx.ui.notify("Could not save pi-stereo-view preferences: " + String(error), "error");
+    });
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    closeSearch();
+    layout?.dispose();
+    unsubscribeInput?.();
+    timestamps = new TranscriptTimestamps(ctx.sessionManager);
+    try {
+      preferences = await loadPreferences(file);
+    } catch (error) {
+      ctx.ui.notify("Could not read pi-stereo-view preferences; using defaults: " + String(error), "warning");
+      preferences = { ...defaults };
+    }
+    let finish: () => void = () => {};
+    await ctx.ui.custom<void>((tui, _theme, _keys, done) => {
+      host = tui;
+      finish = done;
+      layout = new TranscriptLayout(preferences, () => ctx.ui.theme,
+        message => ctx.ui.notify(message, "warning"), () => persist(ctx), timestamps!,
+        () => { void openSettings(ctx).catch(error => ctx.ui.notify(String(error), "error")); });
+      ensureLayout();
+      return new Text("", 0, 0);
+    }, {
+      overlay: true,
+      overlayOptions: { visible: () => false, nonCapturing: true },
+      onHandle: () => finish(),
+    });
+    unsubscribeInput = ctx.ui.onTerminalInput(data => {
+      ensureLayout();
+      const pane = layout?.searchPane();
+      if (pane && !settingsOpen && matchesKey(data, "ctrl+f")) {
+        if (isKeyRelease(data) || layout?.openSearch(pane)) return { consume: true };
+      }
+      return undefined;
+    });
+  });
+  pi.on("message_start", event => {
+    timestamps?.observe(event.message);
+    layout?.refreshSearch();
+  });
+  pi.on("message_update", event => {
+    timestamps?.observe(event.message);
+    layout?.refreshSearch();
+    ensureLayout();
+  });
+  pi.on("message_end", event => {
+    timestamps?.observe(event.message, true);
+    layout?.refreshSearch();
+  });
+  pi.on("tool_execution_update", () => layout?.refreshSearch());
+  pi.on("tool_execution_end", () => layout?.refreshSearch());
+  pi.on("tool_execution_start", event => {
+    if (!timestamps || event.parentToolCallId) return;
+    pi.appendEntry(TOOL_START_ENTRY, { toolCallId: event.toolCallId, time: Date.now() });
+    host?.requestRender();
+  });
+  pi.on("session_tree", () => { closeSearch(); timestamps?.reset(); });
+  pi.on("session_compact", () => { closeSearch(); timestamps?.reset(); });
+  pi.on("session_shutdown", async () => {
+    closeSearch();
+    unsubscribeInput?.();
+    unsubscribeInput = undefined;
+    layout?.dispose();
+    layout = undefined;
+    timestamps = undefined;
+    host = undefined;
+    await writes;
+  });
+
+  const toggle = (): void => {
+    layout?.toggle();
+    ensureLayout();
+  };
+  pi.registerCommand("stereo-view", {
+    description: "History: settings, toggle, swap, layout <columns|rows>, zoom <chat|activity>, width, height, scroll",
+    handler: async (args, ctx) => {
+      if (ctx.mode !== "tui" || !layout) {
+        ctx.ui.notify("pi-stereo-view layout is available only in interactive Pi.", "warning");
+        return;
+      }
+      const [action = "toggle", target, amount] = args.trim().split(/\s+/);
+      if (action === "toggle" || action === "") toggle();
+      else if (action === "settings") await openSettings(ctx);
+      else if (action === "help") {
+        ctx.ui.notify("pi-stereo-view icons: ▣ combined, ◫ split, ▤ rows, ▥ columns, ↕/↔ swap, ↗ expand, ↙ restore, ⌕ search, ≡ settings. Ctrl+F searches the active panel. Drag the ═ or ║ divider to resize.", "info");
+      } else if (action === "swap") layout.swap();
+      else if (action === "width" && /^\d+$/.test(target ?? "")) layout.setWidth(Number(target));
+      else if (action === "height" && target === "auto") layout.setHeight(null);
+      else if (action === "height" && /^\d+$/.test(target ?? "")) layout.setHeight(Number(target));
+      else if (action === "layout" && (target === "columns" || target === "rows")) layout.setLayout(target);
+      else if (action === "zoom" && (target === "chat" || target === "activity")) layout.maximize(target);
+      else if (action === "scroll" && (target === "chat" || target === "activity") && /^-?\d+$/.test(amount ?? "")) {
+        layout.scroll(target, Number(amount));
+      } else {
+        ctx.ui.notify("Use /stereo-view [help|settings|toggle|swap|layout <columns|rows>|zoom <chat|activity>|width <columns>|height <rows|auto>|scroll <chat|activity> <lines>]", "warning");
+        return;
+      }
+      ensureLayout();
+      await writes;
+    },
+  });
+  pi.registerShortcut("ctrl+alt+t", { description: "Toggle split history", handler: async () => toggle() });
+  pi.registerShortcut("ctrl+alt+s", { description: "Swap stereo-view panels", handler: async () => layout?.swap() });
+  pi.registerShortcut("ctrl+alt+left", { description: "Shrink conversation along the split axis", handler: async () => {
+    layout?.resize(-1);
+  } });
+  pi.registerShortcut("ctrl+alt+right", { description: "Grow conversation along the split axis", handler: async () => {
+    layout?.resize(1);
+  } });
+}