vscode: Codev Reader View — wideview-style horizontal transcript reader for builder terminals (read + reply)

[amrmelsayed]

Goal

Open a side webview alongside any builder terminal that renders the Claude conversation as horizontally-flowing markdown columns — newspaper-style, no vertical scroll. Long Claude responses become readable at-a-glance instead of demanding line-by-line scrolling. The terminal itself is untouched; this is an additive consumption surface that lives next to it.

A compose box at the bottom of the reader lets the user post replies back into the builder's PTY without leaving the reader.

Why not "render the terminal itself in columns"

xterm.js / VS Code's terminal is a 2D character grid where ANSI escapes (\r, cursor-up, cursor-down, clear-line, syntax-color runs) depend on exact (row, col) positioning. CSS multi-column wrapping breaks every TUI primitive — Claude Code's spinners, progress indicators, in-place redraws all corrupt across column breaks. The terminal must stay a single-column grid; the Reader View is a separate rendering of the same byte stream after ANSI stripping and turn segmentation.

Source to port (not depend on)

The user owns the wideview repo at /Users/amrmohamed/repos/insighttrail/wideview. The horizontal-flow implementation is small enough to vendor into Codev rather than add @wideview/core as an npm dependency:

Source	Port to
packages/core/src/components/horizontal-flow-container.tsx	packages/vscode/src/webview/reader/horizontal-flow-container.tsx
packages/core/src/hooks/use-horizontal-scroll.ts (wheel-to-scroll, arrow keys, column metrics)	packages/vscode/src/webview/reader/use-horizontal-scroll.ts
packages/core/src/styles/index.css (.wideview-container, .wideview-content, column-width, column-gap, column-fill: auto)	packages/vscode/src/webview/reader/reader.css
apps/vscode-extension/src/panels/wideview-panel.ts (webview lifecycle reference)	mirror the pattern in packages/vscode/src/panels/reader-panel.ts

License: MIT both ways (same author). No package.json dependency added on @wideview/core.

Proposed behavior

1. New command + entry point

• Command: codev.openBuilderReaderView — takes a builder id (or picks via quick-pick).
• Surfaces: command palette, Builders row context menu (e.g. group 1_primary@4 "Open Reader View"), default keybinding (Cmd+K R).

2. Webview panel

CodevReaderPanel (packages/vscode/src/panels/reader-panel.ts), shaped like wideview's WideviewPanel:

• vscode.window.createWebviewPanel('codev.reader', 'Codev Reader: <builder-name>', ViewColumn.Beside, { enableScripts: true, retainContextWhenHidden: true }).
• Loads a small React app from dist/webview/reader/.
• One reader per builder; createOrShow(builderId) revives the existing panel if open.

3. Live transcript stream

In CodevPseudoterminal (packages/vscode/src/terminal-adapter.ts), add a side channel:

private readonly transcriptEmitter = new vscode.EventEmitter<{ chunk: Uint8Array, t: number }>();
readonly onTranscriptChunk = this.transcriptEmitter.event;

Fire it inside handleData() alongside the existing writeEmitter.fire(chunk). The reader subscribes and appends to its internal buffer.

4. Transcript processing (in the webview side)

• ANSI strip — port or pull in a minimal ANSI-escape regex (a ~20-line utility, no dependency). Strips color codes, cursor-positioning, clear-line. Preserves text content.
• Turn segmentation — split the buffer at Claude Code's turn markers. First option: shell-integration OSC 633 markers (the same prerequisite verified in vscode: smart scrolling shortcuts for Codev terminals — by paragraph, by Claude turn, and by viewport page #806). Fallback: regex on Claude Code's prompt sentinel (e.g. the line that starts each new turn).
• Per-turn markdown render — each turn's body is treated as markdown. Render via a small markdown→HTML utility (vendored, not a full library — Claude Code emits clean markdown; we don't need GitHub-flavored extensions).
• Code blocks — preserve fenced code blocks verbatim with monospace styling and break-inside: avoid in CSS so they don't split across columns.

5. Horizontal-flow rendering

Reuse the ported <HorizontalFlowContainer>:

• columnWidth = 400px, columnGap = 24px (match wideview defaults; expose later if needed).
• CSS column-fill: auto so content flows column-by-column as more turns stream in.
• Arrow keys: ← / → scroll one column at a time. Home/End jump to start/latest.
• Wheel-to-scroll: vertical wheel maps to horizontal scroll inside the panel.

6. Reply compose box

A fixed-height row at the bottom of the panel:

• Textarea + Send button (Cmd+Enter submits).
• On submit, send a postMessage from webview to extension; extension calls into the builder's terminalManager to inject the text into the builder's PTY (same direct-write path used by referenceIssueInArchitect / #789's codelens action). Includes a trailing newline so the builder sees Enter — unlike the #789 inject which doesn't press Enter.
• After submission, clear the textarea; the builder's response streams back into the reader naturally because the transcript subscription is live.

7. Sync semantics

Live stream. Transcript events fire on every chunk; the webview throttles re-renders to ~60fps via requestAnimationFrame. Latest turn auto-scrolls into view (scroll to rightmost column) unless the user has scrolled manually within the last 2s — preserves the "I'm reading the middle" intent.

8. State per VS Code window

One reader per builder, multiple readers can coexist (one per panel). Closing a reader disposes its panel; reopening creates a fresh one with full transcript replay from CodevPseudoterminal's in-memory buffer (so the user doesn't lose history).

Acceptance criteria

• No @wideview/core dependency added. Components / hooks / CSS are vendored under packages/vscode/src/webview/reader/.
• codev.openBuilderReaderView registered; available in palette, Builders row menu, and keybinding.
• CodevReaderPanel opens beside the terminal (ViewColumn.Beside) and revives on re-invoke.
• Transcript live-streams from CodevPseudoterminal; ANSI escapes stripped; content rendered as markdown.
• Multi-column horizontal flow works with arrow-key / wheel scroll, column-by-column.
• Code blocks render verbatim and never split across columns (break-inside: avoid).
• Reply compose box injects into the builder's PTY (with trailing newline) and clears on submit.
• New chunks auto-scroll the latest column into view unless the user has manually scrolled within the last 2s.
• Closing the panel cleans up the transcript subscription; reopening rehydrates from buffer.

Out of scope (v1)

• Editing or annotating turns within the reader.
• Persisting transcripts across VS Code restarts (in-memory only).
• Search / filter within the transcript.
• Exporting the transcript to a file (potentially a follow-up).
• Theming / column-width configuration (use wideview defaults, expose later if requested).

Related

• vscode: inject file/hunk reference into builder PTY from the unified-diff editor (codelens) #789 — diff-codelens injects path to builder PTY; same direct-write API the reply box uses.
• vscode: smart scrolling shortcuts for Codev terminals — by paragraph, by Claude turn, and by viewport page #806 — Claude turn-boundary detection via shell-integration markers; the same prerequisite applies here for segmentation.