pi-stereo-view 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.4 - 2026-10-20
+
+### Fixed
+
+- Keep the split layout active while Pi-Bolt streams thinking or text. Later replies no longer require a restart to restore the panels; saved panel sizes and layout settings stay intact.
+- Hide empty self-rendered tool blocks without leaving blank spacing or timestamps, even when the tool returns images to the model. Normal tool output and visibly rendered images remain visible.
+
+### Changed
+
+- Show late output linked to a tool call directly below that call in Activity, even when other work has happened since. Activity search follows the same grouping; combined history keeps its original order.
+
+## 0.1.3 - 2026-10-19
+
+- Show the saved split layout from the first visible frame, without briefly displaying the normal layout first.
+- Keep dialogue and system information, including startup and runtime warnings, errors and status notices, in Conversation. Activity contains thinking, tools and shell execution.
+- Use the same content classification for display and search. Related tool output stays with its tool; unrecognized content stays in Conversation.
+
 ## 0.1.2
 
 - PgUp/PgDn and Pi's other keyboard scroll keys now move the active panel (marked with `●`) instead of always Activity. Pi's built-in history search follows the active panel too.

package/README.md

@@ -20,8 +20,12 @@ The chat becomes two zones: your conversation with the agent, and the agent's wo
 
 | 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. |
+| **Conversation** | Your messages, the LLM's replies, summaries and system information, including welcome, loaded resources, warnings, errors and status notices at any time. |
+| **Activity** | Thinking, tool calls and results, related tool output, and shell execution. |
+
+Unrecognized content stays in Conversation unless its metadata links it to a known tool call.
+
+Late output linked to a tool call appears directly below that call in Activity, even if other work has happened since. Combined history keeps its original order.
 
 Messages and tools keep their familiar appearance. The input stays full width below both panels.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-stereo-view",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Keep Pi conversation separate from tool output and agent activity.",
   "license": "MIT",

package/src/content.ts

@@ -0,0 +1,239 @@
+import { Container, type Component } from "@earendil-works/pi-tui";
+import { searchText, type SearchEntry } from "./search.js";
+
+export type Pane = "activity" | "chat";
+export type ContentKind = "dialogue" | "system" | "thinking" | "tool" | "shell";
+
+const panes: Record<ContentKind, Pane> = {
+  dialogue: "chat", system: "chat", thinking: "activity", tool: "activity", shell: "activity",
+};
+
+interface NativeContent extends Component {
+  text?: string;
+  message?: { content?: unknown; summary?: string; details?: { parentToolCallId?: unknown } };
+  entry?: { data?: { parentToolCallId?: unknown } };
+  toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  result?: { content?: unknown };
+  command?: string;
+  outputLines?: string[];
+  setExpanded?: (expanded: boolean) => void;
+}
+interface NativeAssistant extends Container {
+  contentContainer: Container;
+  hasToolCalls: boolean;
+  lastMessage?: { content: { type: string; text?: string; thinking?: string }[] };
+  contentIsStale?: boolean;
+  buildContent?(message: NonNullable<NativeAssistant["lastMessage"]>): void;
+  setHideThinkingBlock(hidden: boolean): void;
+}
+
+/** One native owner and its pane projection; spacing and search retain that same owner. */
+export interface ContentEntry {
+  source: Component;
+  owner: Component;
+  component: Component;
+  kind: ContentKind;
+  spacing: Component[];
+  compact: boolean;
+  search(width: number): Omit<SearchEntry, "source">;
+}
+
+const nameOf = (component: Component): string => component.constructor.name;
+const contentText = (content: unknown): string => typeof content === "string" ? content :
+  Array.isArray(content) ? content.filter(block => block?.type === "text" && typeof block.text === "string")
+    .map(block => block.text).join("\n") : "";
+
+function assistant(component: Component): NativeAssistant | undefined {
+  if (nameOf(component) !== "AssistantMessageComponent") return undefined;
+  const native = component as NativeAssistant;
+  if (!Array.isArray(native.contentContainer?.children) || typeof native.hasToolCalls !== "boolean" ||
+    (native.lastMessage !== undefined && !Array.isArray(native.lastMessage.content))) {
+    throw new Error("Pi's assistant content metadata is not supported");
+  }
+  // Pi-Bolt builds streamed children lazily. Synchronize the real owner before
+  // indexing or cloning it, so a pane cannot rebuild both content kinds itself.
+  if (native.contentIsStale === true) {
+    if (!native.lastMessage || typeof native.buildContent !== "function") {
+      throw new Error("Pi's deferred assistant content is not supported");
+    }
+    native.buildContent(native.lastMessage);
+  }
+  return native;
+}
+
+/** Read supported native execution identities; unrecognized content is system information. */
+const nativeKinds: Record<string, { kind: ContentKind; accepts(content: NativeContent): boolean }> = {
+  UserMessageComponent: { kind: "dialogue", accepts: content => typeof content.text === "string" },
+  ToolExecutionComponent: { kind: "tool", accepts: content => typeof content.toolName === "string" },
+  BashExecutionComponent: {
+    kind: "shell", accepts: content => typeof content.command === "string" && Array.isArray(content.outputLines),
+  },
+};
+
+/** Shared semantic index for painting and search, independent of wording, severity and lifecycle. */
+export class NativeContentIndex {
+  private signature: unknown[] = [];
+  private content: ContentEntry[] = [];
+  private readonly views = new WeakMap<NativeAssistant, Partial<Record<Pane, Container>>>();
+
+  constructor(private readonly source: Container) {}
+
+  /** Return the same classification until native ownership or assistant content changes. */
+  entries(pane: Pane): ContentEntry[] {
+    this.refresh();
+    return this.content.filter(entry => panes[entry.kind] === pane);
+  }
+
+  /** A rebuilt history cannot retain search hits belonging to removed native owners. */
+  contains(source: Component, pane?: Pane): boolean {
+    this.refresh();
+    return this.content.some(entry => entry.source === source && (pane === undefined || panes[entry.kind] === pane));
+  }
+
+  private refresh(): void {
+    const history = this.source.children[2] as Container;
+    if (!Array.isArray(history?.children)) throw new Error("Pi's history document is not supported");
+    const signature: unknown[] = [...this.source.children, ...history.children];
+    for (const component of history.children) {
+      const metadata = component as NativeContent;
+      signature.push(metadata.toolCallId, metadata.entry?.data?.parentToolCallId, metadata.message?.details?.parentToolCallId);
+      const native = assistant(component);
+      if (native) signature.push(native.lastMessage, ...native.contentContainer.children);
+    }
+    if (signature.length === this.signature.length && signature.every((value, index) => value === this.signature[index])) return;
+    const owners = new Map<string, NativeContent>();
+    for (const component of history.children) {
+      const adapter = nativeKinds[nameOf(component)];
+      const native = component as NativeContent;
+      if (adapter?.kind === "tool" && adapter.accepts(native) && typeof native.toolCallId === "string") {
+        owners.set(native.toolCallId, native);
+      }
+    }
+    const entries = this.source.children.slice(0, 2).map(component => this.entry(component, "system", [], false));
+    let spacing: Component[] = [];
+    for (const component of history.children) {
+      if (nameOf(component) === "Spacer") {
+        spacing.push(component);
+        continue;
+      }
+      const native = assistant(component);
+      if (native) entries.push(...this.assistantEntries(native, spacing));
+      else {
+        const adapter = nativeKinds[nameOf(component)];
+        const native = component as NativeContent;
+        const kind = adapter?.accepts(native) ? adapter.kind : "system";
+        const parentId = native.entry?.data?.parentToolCallId ?? native.message?.details?.parentToolCallId;
+        const owner = kind === "system" && typeof parentId === "string" ? owners.get(parentId) : undefined;
+        entries.push(this.entry(component, kind, spacing, true, owner));
+      }
+      spacing = [];
+    }
+    // Project late execution output beside its owner, never reorder native history.
+    const linked = new Map<Component, ContentEntry[]>();
+    for (const entry of entries) {
+      if (entry.owner === entry.source) continue;
+      const group = linked.get(entry.owner) ?? [];
+      group.push(entry);
+      linked.set(entry.owner, group);
+    }
+    this.content = entries.flatMap(entry => entry.owner === entry.source
+      ? [entry, ...(linked.get(entry.source) ?? [])] : []);
+    this.signature = signature;
+  }
+
+  private entry(source: Component, kind: ContentKind, spacing: Component[], compact: boolean, owner?: NativeContent): ContentEntry {
+    return { source, owner: owner ?? source, component: source, kind: owner ? "tool" : kind, spacing, compact, search: width => {
+      const native = source as NativeContent;
+      if (kind === "tool") {
+        if (typeof native.toolName !== "string") throw new Error("Pi's tool metadata is not supported");
+        return {
+          label: native.toolName,
+          text: [native.toolName, JSON.stringify(native.args, null, 2), contentText(native.result?.content)].filter(Boolean).join("\n"),
+          reveal: () => {
+            if (typeof native.setExpanded !== "function") throw new Error("Pi's tool reveal is not supported");
+            native.setExpanded(true);
+          },
+        };
+      }
+      if (kind === "shell") {
+        if (typeof native.command !== "string" || !Array.isArray(native.outputLines)) throw new Error("Pi's shell metadata is not supported");
+        return { label: "Shell", text: [native.command, ...native.outputLines].join("\n"), reveal: () => native.setExpanded?.(true) };
+      }
+      if (kind === "dialogue") {
+        if (typeof native.text !== "string") throw new Error("Pi's user text metadata is not supported");
+        return { label: "User", text: native.text };
+      }
+      return {
+        label: owner?.toolName ?? (native.message?.summary !== undefined ? "Summary" : "System"),
+        text: contentText(native.message?.content) || native.message?.summary || searchText(source.render(width).join("\n")),
+        reveal: typeof native.setExpanded === "function" ? () => native.setExpanded!(true) : undefined,
+      };
+    } };
+  }
+
+  private assistantEntries(source: NativeAssistant, spacing: Component[]): ContentEntry[] {
+    // Native rendering creates one child per visible text block or consecutive thinking run.
+    // Match those children to semantic content before projecting; a Text diagnostic is not thinking.
+    const runs: ContentKind[] = [];
+    let thinking = false;
+    for (const block of source.lastMessage?.content ?? []) {
+      if (block.type === "thinking") {
+        if (block.thinking?.trim() && !thinking) { runs.push("thinking"); thinking = true; }
+      } else {
+        thinking = false;
+        if (block.type === "text" && block.text?.trim()) runs.push("dialogue");
+      }
+    }
+    const groups: Record<Pane, Component[]> = { chat: [], activity: [] };
+    const diagnostics: Component[] = [];
+    let slot = 0;
+    let padding: Component[] = [];
+    for (const child of source.contentContainer.children) {
+      if (nameOf(child) === "Spacer") { padding.push(child); continue; }
+      const kind = runs[slot++] ?? "system";
+      if ((kind === "thinking" && nameOf(child) !== "MouseRegion") || (kind === "dialogue" && nameOf(child) !== "Markdown")) {
+        throw new Error("Pi's assistant rendering does not match its content metadata");
+      }
+      groups[panes[kind]].push(...padding, child);
+      if (kind === "system") diagnostics.push(child);
+      padding = [];
+    }
+    if (slot < runs.length) throw new Error("Pi's assistant content layout is not supported");
+    const views = this.views.get(source) ?? {};
+    this.views.set(source, views);
+    const result: ContentEntry[] = [];
+    for (const pane of ["chat", "activity"] as const) {
+      const parts = groups[pane];
+      if (!parts.length) continue;
+      let view = views[pane];
+      if (!view) {
+        view = Object.create(source) as Container;
+        const content = new Container();
+        Object.assign(view, {
+          children: [content], contentContainer: content,
+          // This is a partial view: rebuilding the assistant would restore both panes.
+          invalidate: () => content.invalidate(),
+        });
+        views[pane] = view;
+      }
+      const content = view.children[0] as Container;
+      content.children = parts;
+      result.push({
+        source, owner: source, component: view, kind: pane === "activity" ? "thinking" : runs.includes("dialogue") ? "dialogue" : "system", spacing, compact: true,
+        search: width => {
+          const kind = pane === "activity" ? "thinking" : "text";
+          const saved = (source.lastMessage?.content ?? []).filter(block => block.type === kind)
+            .map(block => kind === "text" ? block.text ?? "" : block.thinking ?? "").join("\n\n");
+          return {
+            label: pane === "activity" ? "Thinking" : "Assistant",
+            text: [saved, ...(pane === "chat" ? diagnostics.map(child => searchText(child.render(width).join("\n"))) : [])].filter(Boolean).join("\n\n"),
+            reveal: pane === "activity" ? () => source.setHideThinkingBlock(false) : undefined,
+          };
+        },
+      });
+    }
+    return result;
+  }
+}

package/src/index.ts

@@ -4,9 +4,10 @@ import { Box, Container, isKeyRelease, matchesKey, SettingsList, Text, type TUI
 import { TranscriptLayout } from "./layout.js";
 import { TOOL_START_ENTRY, TranscriptTimestamps } from "./timestamps.js";
 import { defaults, loadPreferences, savePreferences, type Preferences } from "./preferences.js";
+import { beforeFirstFrame } from "./startup.js";
 
 /** Split native fullscreen history without changing message content or the input dock. */
-export default function transcript(pi: ExtensionAPI): void {
+export default async function transcript(pi: ExtensionAPI): Promise<void> {
   let layout: TranscriptLayout | undefined;
   let host: TUI | undefined;
   let timestamps: TranscriptTimestamps | undefined;
@@ -14,16 +15,25 @@ export default function transcript(pi: ExtensionAPI): void {
   let writes = Promise.resolve();
   let preferences: Preferences = { ...defaults };
   const file = path.join(getAgentDir(), "transcript.json");
+  let preferenceWarning: string | undefined;
+  const readPreferences = async (): Promise<void> => {
+    try { preferences = await loadPreferences(file); }
+    catch (error) {
+      preferences = { ...defaults };
+      preferenceWarning = "Could not read pi-stereo-view preferences; using defaults: " + String(error);
+    }
+  };
+  await readPreferences();
 
   let settingsOpen = false;
   const closeSearch = (): void => { layout?.closeSearch(false); };
 
-  const openSettings = async (ctx: ExtensionContext): Promise<void> => {
+  const openSettings = async (ui: ExtensionContext["ui"]): Promise<void> => {
     if (settingsOpen) return;
     settingsOpen = true;
     closeSearch();
     try {
-      await ctx.ui.custom<void>((tui, _theme, _keys, done) => {
+      await 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.",
@@ -39,11 +49,11 @@ export default function transcript(pi: ExtensionAPI): void {
         }, () => done());
         const content = new Container();
         content.addChild({
-          render: () => [ctx.ui.theme.fg("accent", ctx.ui.theme.bold("pi-stereo-view settings")), ""],
+          render: () => [ui.theme.fg("accent", ui.theme.bold("pi-stereo-view settings")), ""],
           invalidate() {},
         });
         content.addChild(list);
-        const box = new Box(1, 1, text => ctx.ui.theme.bg("customMessageBg", text));
+        const box = new Box(1, 1, text => ui.theme.bg("customMessageBg", text));
         box.addChild(content);
         return {
           render: (width: number) => box.render(width),
@@ -64,32 +74,56 @@ export default function transcript(pi: ExtensionAPI): void {
   const ensureLayout = (): void => {
     if (host) layout?.attach(host);
   };
-  const persist = (ctx: ExtensionContext): void => {
+  const persist = (ui: ExtensionContext["ui"]): 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");
+      ui.notify("Could not save pi-stereo-view preferences: " + String(error), "error");
     });
   };
 
-  pi.on("session_start", async (_event, ctx) => {
+  const createLayout = (tui: TUI, ui: ExtensionContext["ui"], session: ExtensionContext["sessionManager"]): void => {
+    host = tui;
+    timestamps = new TranscriptTimestamps(session);
+    layout = new TranscriptLayout(preferences, () => ui.theme,
+      message => ui.notify(message, "warning"), () => persist(ui), timestamps,
+      () => { void openSettings(ui).catch(error => ui.notify(String(error), "error")); });
+    try { ensureLayout(); }
+    catch (error) {
+      layout.dispose();
+      layout = undefined;
+      host = undefined;
+      timestamps = undefined;
+      throw error;
+    }
+  };
+  let earlySession: string | undefined;
+  const releaseStartup = beforeFirstFrame((tui, ui, session) => {
+    earlySession = session.getSessionId();
+    createLayout(tui, ui, session);
+    const mounted = layout;
+    return () => { mounted?.dispose(); };
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    releaseStartup();
     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 };
+    const early = event.reason === "startup" && earlySession === ctx.sessionManager.getSessionId() && layout !== undefined;
+    earlySession = undefined;
+    if (!early) {
+      closeSearch();
+      layout?.dispose();
+      unsubscribeInput?.();
+      await readPreferences();
+    }
+    if (preferenceWarning) {
+      ctx.ui.notify(preferenceWarning, "warning");
+      preferenceWarning = undefined;
     }
     let finish: () => void = () => {};
     await ctx.ui.custom<void>((tui, _theme, _keys, done) => {
-      host = tui;
+      if (early) host = tui;
+      else createLayout(tui, ctx.ui, ctx.sessionManager);
       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);
     }, {
@@ -129,6 +163,7 @@ export default function transcript(pi: ExtensionAPI): void {
   pi.on("session_tree", () => { closeSearch(); timestamps?.reset(); });
   pi.on("session_compact", () => { closeSearch(); timestamps?.reset(); });
   pi.on("session_shutdown", async () => {
+    releaseStartup();
     closeSearch();
     unsubscribeInput?.();
     unsubscribeInput = undefined;
@@ -152,7 +187,7 @@ export default function transcript(pi: ExtensionAPI): void {
       }
       const [action = "toggle", target, amount] = args.trim().split(/\s+/);
       if (action === "toggle" || action === "") toggle();
-      else if (action === "settings") await openSettings(ctx);
+      else if (action === "settings") await openSettings(ctx.ui);
       else if (action === "help") {
         ctx.ui.notify("pi-stereo-view icons: ▣ combined, ◫ split, ▤ rows, ▥ columns, ↕/↔ swap, ↗ expand, ↙ restore, ⌕ search, ≡ settings. Ctrl+F searches and PgUp/PgDn scroll the active panel; Ctrl+Alt+Up/Down switches it. Drag the ═ or ║ divider to resize.", "info");
       } else if (action === "swap") layout.swap();

package/src/layout.ts

@@ -5,6 +5,7 @@ import {
   type Color, type Component, type ScrollViewOptions, type StackChild, type TUI, type TuiMouseEvent,
 } from "@earendil-works/pi-tui";
 import { NativeDocument, type Pane } from "./native.js";
+import { NativeContentIndex } from "./content.js";
 import type { Preferences } from "./preferences.js";
 import type { TranscriptTimestamps } from "./timestamps.js";
 import { PANEL_SEARCH_ROWS, PanelSearch, PanelSearchShortcut, type SearchHit } from "./search.js";
@@ -53,6 +54,25 @@ class TranscriptRows extends VStack {
   }
 }
 
+class TranscriptRoot extends VStack {
+  private readonly owned: Component[];
+
+  constructor(children: StackChild[]) {
+    super(children);
+    this.owned = [...this.children];
+  }
+
+  unchanged(): boolean {
+    return this.children.length === this.owned.length && this.children.every((child, index) => child === this.owned[index]);
+  }
+
+  preserveForeignChildren(native: VStack): void {
+    for (const entry of this.entries) {
+      if (!this.owned.includes(entry.component)) native.addChild(entry.component, entry);
+    }
+  }
+}
+
 class TranscriptPane extends VStack {
   constructor(private readonly header: Component, private readonly view: ScrollView, private readonly height: () => number) {
     super([
@@ -144,7 +164,16 @@ export class TranscriptLayout {
       this.warn("pi-stereo-view split is unavailable: Pi's focus API is not supported.");
       return;
     }
-    if (host.layoutRoot === this.mounted && this.host) return;
+    if (host.layoutRoot === this.mounted && this.host) {
+      const mounted = this.mounted as TranscriptRoot;
+      if (mounted.unchanged()) return;
+      const original = this.original!;
+      mounted.preserveForeignChildren(original as VStack);
+      this.dispose();
+      this.rejectedRoots.add(original);
+      this.warn("pi-stereo-view split is unavailable: Pi's fullscreen layout is not supported.");
+      return;
+    }
     const root = host.layoutRoot;
     if (this.host) this.dispose();
     if (root && this.rejectedRoots.has(root)) return;
@@ -170,10 +199,11 @@ export class TranscriptLayout {
     // Auto scrollbars overlay one native content column; keep clocks outside it.
     const timestampGutter = (): number => scroll.scrollbar === "auto" ? 1 : 0;
     const showTimestamps = (): boolean => this.preferences.showTimestamps;
+    const index = new NativeContentIndex(document);
     const activityDocument = new NativeDocument(document, "activity", this.timestamps, this.theme, timestampGutter, showTimestamps,
-      () => this.activate("activity"), false);
+      () => this.activate("activity"), false, index);
     const chatDocument = new NativeDocument(document, "chat", this.timestamps, this.theme, timestampGutter, showTimestamps,
-      () => this.activate("chat"), false);
+      () => this.activate("chat"), false, index);
     this.documents = { activity: activityDocument, chat: chatDocument };
     this.disposeDocuments = () => {
       activityDocument.dispose();
@@ -350,7 +380,7 @@ export class TranscriptLayout {
       }
     };
     this.rebuild();
-    const mounted = new VStack([
+    const mounted = new TranscriptRoot([
       { component: toolbar, basis: 1, shrink: 0, visible: () => {
         // Root visibility is evaluated once at the start of each native layout pass.
         this.timestamps.beginFrame();

package/src/native.ts

@@ -1,10 +1,10 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Container, Spacer, Text, stripTerminalSequences, type Component, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { Container, Spacer, Text, type Component, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { searchText, type SearchEntry, type SearchHit } from "./search.js";
 import { highlightSearchRows, searchHitRow, type SearchClock } from "./search-highlight.js";
 import { CompactMessage, type TranscriptTimestamps } from "./timestamps.js";
-
-export type Pane = "activity" | "chat";
+import { NativeContentIndex, type Pane } from "./content.js";
+export type { Pane } from "./content.js";
 
 /** Decorate one selected block without changing native text or mouse coordinates. */
 class SearchHighlight implements Component {
@@ -37,56 +37,6 @@ class SearchHighlight implements Component {
     return this.component.handleMouse?.(event);
   }
 }
-interface NativeAssistant extends Container {
-  contentContainer: Container;
-  hasToolCalls: boolean;
-}
-const nameOf = (component: Component): string => component.constructor.name;
-const noticeKinds = new WeakMap<Component, { text: string; compaction?: string }>();
-
-/** Classify only Pi's compaction status; refresh lazy native text only after invalidation. */
-function compactionNotice(component: Component, name: string, width: number): string | undefined {
-  if (name !== "ThemedText") return undefined;
-  const native = component as Component & { stale?: boolean; text?: string };
-  if (native.stale) component.render(width);
-  if (typeof native.text !== "string") throw new Error("Pi's status text metadata is not supported");
-  const cached = noticeKinds.get(component);
-  if (cached?.text === native.text) return cached.compaction;
-  const text = stripTerminalSequences(native.text).trim();
-  const compaction = /^Session compacted \d+ times?$/.test(text) ? text : undefined;
-  noticeKinds.set(component, { text: native.text, compaction });
-  return compaction;
-}
-const messagePane = (name: string, compaction?: string): Pane =>
-  name === "UserMessageComponent" || name === "Image" || name === "CompactionSummaryMessageComponent" ||
-    compaction !== undefined ? "chat" : "activity";
-
-function assistant(component: Component): NativeAssistant | undefined {
-  if (nameOf(component) !== "AssistantMessageComponent") return undefined;
-  const source = component as NativeAssistant;
-  if (!Array.isArray(source.contentContainer?.children) || typeof source.hasToolCalls !== "boolean") {
-    throw new Error("Pi's assistant component is not supported");
-  }
-  return source;
-}
-
-function assistantParts(source: NativeAssistant, pane: Pane): Component[] {
-  const result: Component[] = [];
-  let spacing: Component[] = [];
-  for (const component of source.contentContainer.children) {
-    const name = nameOf(component);
-    if (name === "Spacer") {
-      spacing.push(component);
-      continue;
-    }
-    const target = name === "Markdown" ? "chat" :
-      name === "MouseRegion" || name === "Text" ? "activity" : undefined;
-    if (!target) throw new Error("Pi's assistant content layout is not supported");
-    if (target === pane) result.push(...(pane === "chat" ? [] : spacing), component);
-    spacing = [];
-  }
-  return result;
-}
 
 /**
  * Project the live native component tree, not messages or renderer strings.
@@ -95,8 +45,8 @@ function assistantParts(source: NativeAssistant, pane: Pane): Component[] {
  * Set invalidatesSource to false only when a shared root owns source invalidation.
  */
 export class NativeDocument extends Container {
-  private readonly views = new WeakMap<NativeAssistant, Container>();
   private readonly stamped = new WeakMap<Component, CompactMessage>();
+  private readonly clockOwners = new WeakMap<Component, Component>();
   private readonly compactBlocks = new Map<Component, CompactMessage>();
   private readonly positions = new Map<Component, { row: number; lines: string[]; clock?: SearchClock; excerptRow?: number }>();
   private excerpt?: SearchHit;
@@ -119,6 +69,7 @@ export class NativeDocument extends Container {
     private readonly showTimestamps: () => boolean,
     private readonly interact: () => void = () => {},
     private readonly invalidatesSource = true,
+    private readonly index = new NativeContentIndex(source),
   ) {
     super();
   }
@@ -142,69 +93,22 @@ export class NativeDocument extends Container {
     if (!Array.isArray(chat?.children)) throw new Error("Pi's history document is not supported");
     for (const component of chat.children) {
       this.timestamps.check(component);
-      const native = assistant(component);
-      if (native) assistantParts(native, this.pane);
     }
+    this.index.entries(this.pane);
     this.checked = true;
   }
 
   /** Read full saved text from the current native branch, including collapsed blocks. */
   searchEntries(): SearchEntry[] {
-    const entries: SearchEntry[] = [];
-    const add = (source: Component, label: string, text: string, reveal?: () => void): void => {
-      if (text.trim()) entries.push({ source, label, text, reveal });
-    };
-    const contentText = (content: unknown): string => typeof content === "string" ? content :
-      Array.isArray(content) ? content.filter(block => block?.type === "text" && typeof block.text === "string")
-        .map(block => block.text).join("\n") : "";
-    for (const component of (this.source.children[2] as Container).children) {
-      const name = nameOf(component);
-      const notice = compactionNotice(component, name, this.lastWidth);
-      const native = component as Component & {
-        text?: string; lastMessage?: { content: { type: string; text?: string; thinking?: string }[] };
-        toolName?: string; args?: unknown; result?: { content?: unknown };
-        command?: string; outputLines?: string[]; message?: { content?: unknown; summary?: string };
-        setExpanded?: (expanded: boolean) => void; setHideThinkingBlock?: (hide: boolean) => void;
-      };
-      if (name === "UserMessageComponent" && this.pane === "chat") {
-        if (typeof native.text !== "string") throw new Error("Pi's user search text is not supported");
-        add(component, "User", native.text);
-      } else if (name === "AssistantMessageComponent") {
-        if (!Array.isArray(native.lastMessage?.content)) throw new Error("Pi's assistant search text is not supported");
-        const kind = this.pane === "chat" ? "text" : "thinking";
-        const text = native.lastMessage?.content.filter(block => block.type === kind)
-          .map(block => kind === "text" ? block.text ?? "" : block.thinking ?? "").join("\n\n") ?? "";
-        add(component, kind === "text" ? "Assistant" : "Thinking", text, kind === "thinking" ? () => {
-          if (typeof native.setHideThinkingBlock !== "function") throw new Error("Pi's thinking reveal is not supported");
-          native.setHideThinkingBlock(false);
-        } : undefined);
-      } else if (this.pane === "activity" && name === "ToolExecutionComponent") {
-        if (typeof native.toolName !== "string") throw new Error("Pi's tool search text is not supported");
-        add(component, native.toolName, [native.toolName, JSON.stringify(native.args, null, 2), contentText(native.result?.content)]
-          .filter(Boolean).join("\n"), () => {
-            if (typeof native.setExpanded !== "function") throw new Error("Pi's tool reveal is not supported");
-            native.setExpanded(true);
-          });
-      } else if (this.pane === "activity" && name === "BashExecutionComponent") {
-        if (typeof native.command !== "string" || !Array.isArray(native.outputLines)) {
-          throw new Error("Pi's shell search text is not supported");
-        }
-        add(component, "Shell", [native.command, ...native.outputLines].join("\n"), () => native.setExpanded?.(true));
-      } else if (name === "CompactionSummaryMessageComponent" && this.pane === "chat") {
-        add(component, "Compaction", native.message?.summary ?? "", () => native.setExpanded?.(true));
-      } else if (notice !== undefined && this.pane === "chat") {
-        add(component, "Compaction", notice);
-      } else if (this.pane === "activity" && messagePane(name, notice) === "activity" && name !== "Spacer") {
-        add(component, name.replace(/(?:Message)?Component$/, ""),
-          contentText(native.message?.content) || native.message?.summary || searchText(component.render(this.lastWidth).join("\n")));
-      }
-    }
-    return entries;
+    return this.index.entries(this.pane).flatMap(entry => {
+      const saved = entry.search(this.lastWidth);
+      return saved.text.trim() ? [{ source: entry.source, ...saved }] : [];
+    });
   }
 
   /** Reject hits whose native owner was removed by a branch change or history rebuild. */
   containsSearchHit(hit: SearchHit): boolean {
-    return (this.source.children[2] as Container).children.includes(hit.entry.source);
+    return this.index.contains(hit.entry.source, this.pane);
   }
   /** Reveal one selected block without replacing its native renderer. */
   reveal(hit: SearchHit, query = ""): boolean {
@@ -274,79 +178,52 @@ export class NativeDocument extends Container {
     this.timestamps.prepare(chat.children);
     this.lastWidth = width;
     this.positions.clear();
-    if (this.excerpt && !chat.children.includes(this.excerpt.entry.source)) this.excerpt = undefined;
-    if (this.searchAnchor && !chat.children.includes(this.searchAnchor.entry.source)) this.searchAnchor = undefined;
-    const result: Component[] = this.pane !== "chat" ? this.source.children.slice(0, 2) : [];
+    if (this.excerpt && !this.index.contains(this.excerpt.entry.source, this.pane)) this.excerpt = undefined;
+    if (this.searchAnchor && !this.index.contains(this.searchAnchor.entry.source, this.pane)) this.searchAnchor = undefined;
+    const result: Component[] = [];
     const locateMatch = this.searchAnchor !== undefined || this.excerpt !== undefined;
-    let row = locateMatch ? result.reduce((count, child) => count + child.render(width).length, 0) : 0;
-    let spacing: Component[] = [];
+    let row = 0;
     let visibleBlock = false;
-    for (const component of chat.children) {
-      const name = nameOf(component);
-      if (name === "Spacer") {
-        spacing.push(component);
-        continue;
-      }
-      const native = assistant(component);
-      let routed: Component | undefined;
-      if (native) {
-        const parts = assistantParts(native, this.pane);
-        if (parts.length) {
-          let view = this.views.get(native);
-          if (!view) {
-            view = Object.create(native) as Container;
-            const content = new Container();
-            Object.assign(view, { children: [content], contentContainer: content });
-            this.views.set(native, view);
-          }
-          const content = view.children[0] as Container;
-          if (content.children.length !== parts.length || parts.some((part, index) => part !== content.children[index])) {
-            content.children = parts;
-          }
-          routed = view;
+    for (const entry of this.index.entries(this.pane)) {
+      const component = entry.source;
+      const routed = entry.component;
+      this.clockOwners.set(component, entry.owner);
+      const start = result.length;
+      const wasVisible = visibleBlock;
+      // Orientation keeps native padding; message projections share compact presentation.
+      if (!entry.compact) result.push(...entry.spacing, routed);
+      else {
+        let stamped = this.stamped.get(routed);
+        if (!stamped) {
+          stamped = new CompactMessage(routed, () => this.timestamps.label(this.clockOwners.get(component) ?? component), this.theme, this.timestampGutter, this.showTimestamps);
+          this.stamped.set(routed, stamped);
         }
-      } else {
-        if (messagePane(name, compactionNotice(component, name, width)) === this.pane) routed = component;
+        this.compactBlocks.set(component, stamped);
+        visibleBlock = stamped.prepare(width, visibleBlock) || visibleBlock;
+        result.push(stamped);
       }
-      if (routed) {
-        const start = result.length;
-        const wasVisible = visibleBlock;
-        // Empty native assistant shells do not need a detached timestamp row.
-        if (native && native.contentContainer.children.length === 0) result.push(...spacing, routed);
-        else {
-          let stamped = this.stamped.get(routed);
-          if (!stamped) {
-            stamped = new CompactMessage(routed, () => this.timestamps.label(component), this.theme, this.timestampGutter, this.showTimestamps);
-            this.stamped.set(routed, stamped);
-          }
-          this.compactBlocks.set(component, stamped);
-          visibleBlock = stamped.prepare(width, visibleBlock) || visibleBlock;
-          result.push(stamped);
-        }
-        if (this.searchAnchor?.entry.source === component && !this.excerpt) {
-          const last = result.length - 1;
-          result[last] = this.highlighted(result[last]);
-        }
-        if (locateMatch) {
-          const lines = result.slice(start).flatMap(child => child.render(width));
-          let excerptRow: number | undefined;
-          if (this.excerpt?.entry.source === component) {
-            const fragment = new Text(this.theme().fg("accent", "Search match: ") + searchText(this.excerpt.text), 1, 0);
-            if (!lines.length && wasVisible) {
-              result.push(new Spacer(1));
-              lines.push("");
-            }
-            excerptRow = row + lines.length;
-            const decorated = this.highlighted(fragment, true);
-            result.push(decorated);
-            lines.push(...decorated.render(width));
-            visibleBlock = true;
+      if (this.searchAnchor?.entry.source === component && !this.excerpt) {
+        const last = result.length - 1;
+        result[last] = this.highlighted(result[last]);
+      }
+      if (locateMatch) {
+        const lines = result.slice(start).flatMap(child => child.render(width));
+        let excerptRow: number | undefined;
+        if (this.excerpt?.entry.source === component) {
+          const fragment = new Text(this.theme().fg("accent", "Search match: ") + searchText(this.excerpt.text), 1, 0);
+          if (!lines.length && wasVisible) {
+            result.push(new Spacer(1));
+            lines.push("");
           }
-          this.positions.set(component, { row, lines, clock: this.compactBlocks.get(component)?.searchClock(), excerptRow });
-          row += lines.length;
+          excerptRow = row + lines.length;
+          const decorated = this.highlighted(fragment, true);
+          result.push(decorated);
+          lines.push(...decorated.render(width));
+          visibleBlock = true;
         }
+        this.positions.set(component, { row, lines, clock: this.compactBlocks.get(component)?.searchClock(), excerptRow });
+        row += lines.length;
       }
-      spacing = [];
     }
     // Native follow-end guidance overlays the bottom row. Keep the selected last line above it.
     if (this.searchAnchor) result.push(new Spacer(1));

package/src/render-cache.ts

@@ -1,4 +1,23 @@
-import type { Component } from "@earendil-works/pi-tui";
+import { stripTerminalSequences, type Component } from "@earendil-works/pi-tui";
+
+const imagePlacement = (line: string): boolean => line.includes("\x1b_G") || line.includes("\x1b]1337;File=");
+
+function nativeLines(component: Component, width: number): string[] {
+  const lines = component.render(width);
+  const tool = component as Component & {
+    toolDefinition?: { renderShell?: string; renderCall?: unknown; renderResult?: unknown };
+    selfRenderHeight?: number;
+  };
+  const definition = tool.toolDefinition;
+  const height = tool.selfRenderHeight;
+  if (component.constructor.name !== "ToolExecutionComponent" || definition?.renderShell !== "self" ||
+    typeof definition.renderCall !== "function" || typeof definition.renderResult !== "function" ||
+    typeof height !== "number" || !Number.isInteger(height) || height < 0) return lines;
+  // Native self shells prepend one row, then append result images outside the custom UI.
+  // An intentionally empty custom UI must not be made visible by those automatic images.
+  const content = height ? lines.slice(1, height + 1) : [];
+  return content.some(line => imagePlacement(line) || stripTerminalSequences(line).trim().length > 0) ? lines : [];
+}
 
 interface Subscription {
   original: Component["invalidate"];
@@ -180,9 +199,9 @@ export class NativeRenderCache {
     const initial = components(this.component);
     const observed = this.watch(initial);
     const before = this.revision;
-    const lines = this.component.render(width);
+    const lines = nativeLines(this.component, width);
     this.outputVersion++;
-    this.imagePlacement = lines.some(line => line.includes("\x1b_G") || line.includes("\x1b]1337;File="));
+    this.imagePlacement = lines.some(imagePlacement);
     const links: NodeLinks[] = [];
     const after = components(this.component, links);
     const stableGraph = initial.length === after.length &&

package/src/startup.ts

@@ -0,0 +1,71 @@
+import { InteractiveMode, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isViewportTUI, type TUI } from "@earendil-works/pi-tui";
+
+type Ui = ExtensionContext["ui"];
+type Session = ExtensionContext["sessionManager"];
+type StartupHost = {
+  isInitialized?: boolean;
+  renderer?: TUI;
+  sessionManager?: Session;
+  createExtensionUIContext?: () => Ui;
+};
+
+/** Mount once before the first native frame; restore only hooks still owned by this extension. */
+export function beforeFirstFrame(mount: (tui: TUI, ui: Ui, session: Session) => () => void): () => void {
+  const prototype = InteractiveMode.prototype;
+  const original = prototype.init;
+  const initDescriptor = Object.getOwnPropertyDescriptor(prototype, "init");
+  if (typeof original !== "function" || !initDescriptor?.writable) return () => {};
+  let pending: typeof mount | undefined = mount;
+  let restoreStart = (): void => {};
+  const release = (): void => {
+    pending = undefined;
+    if (prototype.init === initialize) prototype.init = original;
+    restoreStart();
+  };
+  async function initialize(this: InteractiveMode): Promise<void> {
+    const mountLayout = pending;
+    release();
+    // A later wrapper may retain this trampoline. Cancellation makes it inert without clobbering that wrapper.
+    if (!mountLayout) return original.call(this);
+    const owner = this as unknown as StartupHost;
+    const tui = owner.renderer;
+    const session = owner.sessionManager;
+    // Unsupported hosts keep native startup. Never patch a regular renderer or invent a context.
+    if (owner.isInitialized !== false || !tui || !isViewportTUI(tui) ||
+        typeof owner.createExtensionUIContext !== "function" ||
+        typeof session?.buildContextEntries !== "function" || typeof session.getBranch !== "function") {
+      return original.call(this);
+    }
+    const ui = owner.createExtensionUIContext();
+    if (typeof ui?.theme?.style !== "function" || typeof ui.notify !== "function") return original.call(this);
+    const start = tui.start;
+    const descriptor = Object.getOwnPropertyDescriptor(tui, "start");
+    if (typeof start !== "function" || (descriptor ? !("value" in descriptor) || !descriptor.writable : !Object.isExtensible(tui))) {
+      return original.call(this);
+    }
+    let dispose: (() => void) | undefined;
+    restoreStart = (): void => {
+      if (tui.start !== startWithLayout) return;
+      if (descriptor) Object.defineProperty(tui, "start", descriptor);
+      else delete (tui as Partial<TUI>).start;
+    };
+    function startWithLayout(this: TUI): void {
+      restoreStart();
+      try { dispose = mountLayout!(tui!, ui, session!); }
+      catch (error) { ui.notify("pi-stereo-view early layout is unavailable: " + String(error), "warning"); }
+      start.call(this);
+    }
+    tui.start = startWithLayout;
+    try {
+      await original.call(this);
+    } catch (error) {
+      dispose?.();
+      throw error;
+    } finally {
+      restoreStart();
+    }
+  }
+  prototype.init = initialize;
+  return release;
+}