type: spec
date: 2026-08-11
status: draft
priority: p2
platform: opencode
tags: [spec, ui, markdown, side-panel, preview, authoring]
linked_plan: null

Preview Tab — Document Viewer/Editor in the Side Panel

Acceptance Criteria

Preview tab

• A new "Preview" tab appears in the side panel alongside Modified Files and Context
• The tab lists all .md files the AI modified in the current session
• Each file in the list shows an A (added) or M (modified) badge
• Clicking a file replaces the list with the rendered content (back button returns to list)
• .md files render through the existing Markdown component (full GFM: headings, bold/italic, code blocks with syntax highlighting, tables, links, images, LaTeX math, task lists)
• A per-file toggle switches between Preview (rendered) and Raw (editable textarea) modes
• Raw mode shows a monospace textarea with the file source
• Edits in raw mode auto-save with ~1s debounce
• Cmd+S (Ctrl+S on Linux) triggers an immediate save in raw mode
• Saves write to disk via the existing file-write mechanism
• The tab only appears when at least one .md file has been AI-modified in the session (no empty state)
• Non-.md files never appear in this tab
• The Modified Files tab and Context tab are completely unaffected

Panel menu (replaces the "+" button)

• The existing "+" button in the tab bar is replaced with a "+" button that opens a dropdown menu
• The menu lists available panel types: "Context", "Preview"
• Clicking a menu item opens that tab (same as if it were already open and you clicked its trigger)
• The SESSION_OPEN_FILE_TAB ("open-file") tab is removed — no more inline file browser
• The old-layout dialog-based file open behavior is also removed
• The menu is the single extensible seam for adding future panel types
• Menu items that are already open could be visually indicated (dimmed or checkmarked)

Key Decisions

Tab registration pattern

Follow the Context tab precedent:

1. Add "preview" constant to layout-tabs.ts
2. Filter from sortable file-tabs in createSessionTabs (helpers.ts)
3. Add to the active-tab priority chain
4. Add trigger + content in session-side-panel.tsx (both v1 and v2 code paths)

Panel menu replaces "+" button

The current "+" button has two implementations:

• Old layout: lazy-imports DialogSelectFile and shows a modal file picker
• V2 layout: calls openFileBrowser() which opens SESSION_OPEN_FILE_TAB inline

Both are replaced with a single dropdown menu (a Popover or DropdownMenu from the UI kit). The menu is a static list of panel types — initially "Context" and "Preview". Each item calls the same tabs().open("context") / tabs().open("preview") + tabs().setActive(...) pattern. This becomes the canonical extensibility point for future panels (e.g., "Outline", "References", "Terminal").

The SESSION_OPEN_FILE_TAB constant and all code paths that reference it are removed.

File list — flat, with change badges

A flat file list (not a tree) showing basename + relative directory, with A/M badges sourced from the session file-change set. Same visual density as the Modified Files list. Click navigates to the content view; a back/breadcrumb button returns to the list.

Content view — two modes

The toggle is per-file — each file remembers its mode independently within the session.

Save mechanism

Raw-mode edits auto-save via a debounced (~1s) write to disk using the same file-write channel the agent uses. Cmd+S bypasses the debounce for an immediate write. The file remains in the Preview tab list (it was AI-modified; user edits don't remove it).

Data contract

// File entry in the Preview tab list
interface PreviewFileEntry {
  path: string           // absolute file path
  relativePath: string   // relative to workspace root
  basename: string       // file name
  extension: ".md"
  changeType: "added" | "modified"
}

// Per-file view state
interface PreviewFileState {
  mode: "preview" | "raw"
  scrollPosition?: number  // restore scroll on mode toggle
  unsavedContent?: string  // buffer for debounced save
}

// Panel menu item (extensible registry)
interface PanelMenuItem {
  id: string             // tab value, e.g. "context", "preview"
  label: string          // display name
  icon: string           // icon name from the icon set
  available: () => boolean  // whether to show (e.g. preview only when .md files exist)
}

Constraints & Invariants

• The existing Markdown component must not be forked — extend via props/composition only
• No changes to the Modified Files tab behavior or the Context tab
• No new panel layout types — the Preview tab lives inside the existing side panel tab system
• CSS custom properties from the existing theme — no hardcoded colors
• The tab is hidden when no .md files have been AI-modified in the session (no empty state)
• File writes from raw mode use the same permissions/mechanism as agent file writes
• The panel menu is the ONLY way to open non-file tabs going forward (replaces all "+" button behaviors)

File Changes

New files

Modified files

Removed

Prior Art

• Context tab (session-context-tab.tsx) — the pattern for registering a non-file tab in the side panel
• Modified Files / Review tab — the UX precedent for listing session-changed files with badges
• Markdown component (packages/session-ui/src/components/markdown.tsx) — full GFM + LaTeX math + streaming + syntax highlighting via shiki
• Obsidian / Notion — the reading-mode vs editing-mode toggle UX precedent
• VS Code "..." menu in panel headers — precedent for a menu that opens different panel types

Follow-up: LaTeX (.tex) support

Full-document LaTeX rendering in the browser is hard. The options:

The most pragmatic future path: detect .tex files, show syntax-highlighted source with inline math blocks rendered via KaTeX (i.e., "raw mode with math sprinkled in"). Not a full Overleaf-style preview, but useful. Separate issue when the need is clear.

Source

Revised from the original #162 spec (2026-08-10). Pivoted from "rendered markdown diffs in the Review tab" to a standalone Preview tab. Scoped to .md only after honest assessment of LaTeX rendering feasibility. Panel menu added to replace the single-purpose "+" button with an extensible launcher.