feat(web): markdown Source | Preview toggle in session file pane

[heavygee]

Summary

The session file preview route (/sessions/:id/file) shows .md files as Shiki-highlighted source only (same as any text file). Operators reading docs in HAPI want a Typora-style toggle between raw markdown and a rendered preview (headings, tables, blockquotes, links) without leaving the PWA.

Chat already renders markdown richly via MarkdownRenderer / markdown-text.tsx (GFM, mermaid, KaTeX, table repair, link guards). The file pane never wires that stack up.

Current behavior

• web/src/routes/sessions/file.tsx — text files (including .md) → <pre><code> + Shiki highlight
• Images get ImagePreview; markdown does not
• Existing tabs: Diff | File when git diff exists; no source/preview toggle

Proposed behavior

For markdown files (at minimum .md; consider .mdx if trivial):

1. Add Source | Preview toggle in the file pane toolbar (alongside existing Diff/File tabs when present)
2. Preview reuses the chat markdown pipeline (MarkdownRenderer or equivalent exports from markdown-text.tsx) so rendering matches chat
3. Default: Preview for .md, Source for other extensions — or remember last choice per session in localStorage (operator preference; pick one and document in PR)
4. Diff tab: preview toggle off or disabled while viewing diff (source-only is fine for v1)
5. Copy/download buttons unchanged

Edge cases / v1 scope

• Relative links/images (./foo.md, screenshot.png) — ideal: resolve against session cwd via existing file-route URLs; acceptable v1: render body, leave relative hrefs as-is or open externally with a known limitation called out in PR
• Large files — cap preview mode or fall back to source if over N bytes (match existing copy limit patterns in file.tsx)
• Binary / empty — unchanged
• No hub/cli/schema changes expected (web-only); if any shared type tweak is needed, keep it minimal

Acceptance criteria

• Opening a .md file in the file pane shows a Source | Preview toggle
• Preview renders headings, lists, tables, blockquotes, code fences, and links using the same pipeline as chat
• Toggle state persists for the session (localStorage) or defaults sensibly
• Non-markdown files unchanged (Shiki source view)
• Typecheck + tests pass; Playwright smoke on a real markdown file in soup

References

• File route: web/src/routes/sessions/file.tsx
• Markdown renderer: web/src/components/MarkdownRenderer.tsx, web/src/components/assistant-ui/markdown-text.tsx
• CSS: .markdown-content rules in web/src/index.css

Non-goals (v1)

• WYSIWYG editing
• Split-pane simultaneous source + preview (toggle is enough)
• Hub-side markdown conversion

[github-actions]

Verified. The current file pane does not have markdown-specific rendering yet: it only switches between Diff and File, and the file view renders non-image, non-binary text through Shiki source highlighting. A markdown Source | Preview toggle looks like a web-only change based on the current API shape: the web client already receives decoded file content from the existing session file endpoint, and the chat markdown renderer is already exported for reuse.

One implementation detail to watch: the shared markdown stack includes chat-oriented file-path link handling. In non-chat surfaces, those generated file-path links do not get session routing because the anchor path uses optional chat context; ordinary relative links are passed through by the URL transform. So relative links/images should be handled deliberately or documented as a v1 limitation.

Relevant code:

• web/src/routes/sessions/file.tsx:249 - current display state is only 'diff' | 'file'.
• web/src/routes/sessions/file.tsx:316 - toolbar renders only Diff and File tabs when diff content exists.
• web/src/routes/sessions/file.tsx:355 - image files use ImagePreview; other text falls through to source rendering.
• web/src/routes/sessions/file.tsx:378 - text file content renders as <pre><code> with Shiki-highlighted content.
• web/src/components/MarkdownRenderer.tsx:44 - reusable MarkdownRenderer component is exported.
• web/src/components/assistant-ui/markdown-text.tsx:55 - markdown pipeline includes GFM/table repair and shared plugins.
• web/src/components/assistant-ui/markdown-text.tsx:70 - KaTeX rehype plugin is part of the shared renderer setup.
• web/src/components/assistant-ui/markdown-text.tsx:189 - URL transform allows relative/no-scheme URLs and strips denied schemes.
• web/src/components/assistant-ui/markdown-text.tsx:486 - chat file-path link routing requires chat context; without it, generated file-path links render as children only.
• web/src/api/client.ts:345 - existing file endpoint already returns file content to the web client.
• web/src/lib/locales/en.ts:316 - current file pane locale strings only define Diff and File tabs.

---

HAPI Bot