feat: add Export Chat (Markdown / PDF) to session kebab menu

[jeremyeder]

Summary

• Adds "Export chat" submenu to the session kebab menu (both kebab-only and full render modes) with two options: As Markdown and As PDF
• New utils/export-chat.ts processes AG-UI events client-side into structured markdown with metadata header, User/Assistant sections, and collapsible <details> blocks for tool calls
• PDF export renders styled HTML in a new window and triggers window.print() (browser native "Save as PDF")
• Deduplicates the blob-download pattern: extracts shared triggerDownload() utility, now used by both new export and existing JSON export in session-details-modal.tsx
• Fixes XSS vector in PDF path (HTML-escapes message content before rendering) and double-print bug (guard flag)

Files changed

File	Change
components/frontend/src/utils/export-chat.ts	New — convertEventsToMarkdown, downloadAsMarkdown, exportAsPdf, triggerDownload
components/frontend/src/app/projects/[name]/sessions/[sessionName]/session-header.tsx	Add Export chat DropdownMenuSub with loading states
components/frontend/src/components/session-details-modal.tsx	Replace inline downloadFile with shared triggerDownload import

Test plan

• Open a session with chat history, click kebab menu → verify "Export chat" submenu appears between Clone and Delete
• Click "As Markdown" → verify .md file downloads with readable conversation (metadata table, User/Assistant headings, tool calls as <details>)
• Click "As PDF" → verify print dialog opens with styled conversation in a new tab
• Verify existing "Export Chat" (JSON) button in View Details modal still works after triggerDownload refactor
• Verify npm run build passes with 0 errors, 0 warnings

🤖 Generated with Claude Code

[github-actions]

Claude Code Review

Summary

This PR adds Markdown and PDF export functionality to the session kebab menu, with clean client-side event processing and shared utility extraction. The implementation follows project standards well, with strong type safety, proper React patterns, and security considerations. A few minor improvements could enhance robustness and user experience.

Overall Assessment: ✅ Approved with recommendations

---

Issues by Severity

🚫 Blocker Issues

None identified.

🔴 Critical Issues

1. Error Handling - Print Dialog Blocked

• Location: export-chat.ts:232-235
• Issue: When window.open() returns null (popup blocked), the error is thrown but not caught in session-header.tsx:71-89
• Impact: Unhandled promise rejection, no user feedback on popup blocker
• Fix: Wrap in try-catch in the async handler, or make exportAsPdf return success/failure
• Code:

// Current: throws error
if (\!printWindow) {
  throw new Error('Failed to open print window...');
}

// Better: catch in session-header.tsx handleExport
try {
  exportAsPdf(markdown, filename);
} catch (err) {
  errorToast(err instanceof Error ? err.message : 'Failed to export chat');
}

🟡 Major Issues

1. Race Condition in Print Trigger

• Location: export-chat.ts:276-281
• Issue: Both timeout fallback AND load listener call printWindow.print(), no guard flag prevents double-print
• Code Review:

// Current: can print twice
const timeoutId = setTimeout(() => printWindow.print(), 500);
printWindow.addEventListener('load', () => {
  clearTimeout(timeoutId);  // Clears timeout but still calls print()
  printWindow.print();       // This runs even if timeout already fired
});

• Fix: Add a guard flag or use once listener
• Suggested fix:

let printed = false;
const timeoutId = setTimeout(() => {
  if (\!printed) {
    printed = true;
    printWindow.print();
  }
}, 500);
printWindow.addEventListener('load', () => {
  clearTimeout(timeoutId);
  if (\!printed) {
    printed = true;
    printWindow.print();
  }
}, { once: true });

2. Missing Loading State Reset on Error

• Location: session-header.tsx:71-89
• Issue: If exportAsPdf throws before the try-catch, exportLoading stays locked
• Impact: User cannot retry export after popup blocker error
• Note: PR description claims this is fixed, but the throw in line 234 bypasses the finally block in session-header
• Fix: Ensure exportAsPdf never throws, or add outer try-catch

3. Type Safety - Inline Type vs Import

• Location: export-chat.ts:10-23
• Issue: ExportEvent is defined inline but mirrors AG-UI event structure — should import from @/types/agui if available
• Current:

type ExportEvent = {
  type: string;
  role?: string;
  delta?: string;
  // ... duplicates AGUIEventType structure
};

• Recommendation: Check if @/types/agui exports a compatible type, or add a comment explaining why inline is needed

🔵 Minor Issues

1. Magic Numbers Should Be Constants

• Location: export-chat.ts:25-27, 277
• Issue: Hardcoded 2000, 1000, 500 without explanation
• Fix: Extract to named constants with JSDoc

/** Maximum length for tool arguments before truncation (readability) */
const MAX_TOOL_ARGS_LENGTH = 2000;
/** Print dialog timeout fallback (allows slow browsers to load) */
const PRINT_DIALOG_TIMEOUT_MS = 500;

2. PDF Export User Feedback

• Location: session-header.tsx:82
• Issue: No success toast for PDF export (unlike Markdown on line 80)
• Impact: User doesn't know if export succeeded
• Recommendation: Add toast or update UI to indicate print dialog opened

3. File Download Cleanup Timing

• Location: export-chat.ts:215
• Issue: URL.revokeObjectURL(url) is called immediately after link.click(), may revoke before download starts on slow browsers
• Fix: Add slight delay or onload handler

link.click();
setTimeout(() => URL.revokeObjectURL(url), 100);

4. Empty State Handling

• Location: export-chat.ts:161-163
• Issue: Returns empty markdown if no blocks found, but doesn't prevent download
• Impact: User downloads empty file, confusing UX
• Recommendation: Throw error or return null to prevent download trigger

5. Markdown Table Edge Case

• Location: export-chat.ts:372-380
• Issue: parseTable doesn't validate minimum column count, could produce malformed HTML
• Fix: Add validation:

if (parsed.length === 0 || header.length === 0) return '';

---

Positive Highlights

✅ Excellent Type Safety - Zero any types, proper use of type over interface, strong type guards (isExportEvent)

✅ Security Conscious - escapeHtml() prevents XSS in PDF export, content sanitization before rendering

✅ Clean Architecture - Proper separation: utilities in export-chat.ts, React logic in components, shared triggerDownload extraction

✅ Loading States - Disabled buttons with spinner icons during export (exportLoading state)

✅ Accessibility - Menu uses Shadcn dropdowns with proper ARIA attributes, keyboard navigation

✅ Code Reuse - Refactored duplicate downloadFile pattern into shared triggerDownload utility

✅ Documentation - Clear JSDoc comments explaining function purposes and parameters

---

Recommendations

High Priority

1. Fix print dialog error handling - Catch popup blocker errors gracefully
2. Add guard flag to prevent double-print - Ensure print() is called exactly once
3. Reset loading state on all error paths - Ensure UI doesn't get stuck in loading state

Medium Priority

4. Add success feedback for PDF export - Toast or status message when print dialog opens
5. Import AG-UI event types - Reduce duplication if @/types/agui exports compatible types
6. Validate empty exports - Prevent downloading empty files

Low Priority

7. Extract magic numbers - Named constants for timeouts and truncation limits
8. Add delay to URL.revokeObjectURL - Prevent race on slow browsers
9. Validate table structure - Edge case handling for malformed markdown tables

---

Pre-Merge Checklist

Based on CLAUDE.md standards:

• ✅ Zero any types
• ✅ All UI uses Shadcn components
• ✅ React Query used for data fetching (useSessionExport)
• ✅ Loading states on all buttons
• ✅ Types use type instead of interface
• ⚠️ Error handling needs improvement (popup blocker case)
• ⚠️ npm run build verification needed (GitHub Actions will check)

---

Testing Recommendations

Before merging, verify:

1. Popup blocker scenario - Disable popups, click "As PDF", confirm user gets error toast
2. Empty session export - Session with no messages, confirm graceful handling
3. Large exports - Session with 100+ messages, verify truncation and performance
4. Browser compatibility - Test in Chrome, Firefox, Safari (print dialog behavior varies)
5. Markdown rendering - Special characters in user messages (quotes, HTML entities)

---

Files Review Summary

File	Lines Changed	Quality	Notes
export-chat.ts	+395	⭐⭐⭐⭐☆	Excellent utility, minor improvements needed
session-header.tsx	+70/-9	⭐⭐⭐⭐⭐	Clean integration, proper state management
session-details-modal.tsx	+8/-17	⭐⭐⭐⭐⭐	Perfect refactor, reduced duplication

Overall Code Quality: 4.5/5 ⭐⭐⭐⭐☆

Great work on this feature! The code is well-structured and follows project conventions. Address the critical error handling issues and this will be ready to merge.

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.

[github-actions]

Claude Code Review

Summary

This PR adds export chat functionality (Markdown/PDF/Google Drive) to the session kebab menu. The implementation demonstrates solid code quality with proper XSS prevention, good TypeScript practices, and well-structured utility functions. However, there are several critical issues around error handling, React Query usage, and frontend patterns that must be addressed before merge.

Issues by Severity

🚫 Blocker Issues

1. Missing React Query for Data Fetching

• Location: session-header.tsx:96
• Issue: Direct await getSessionExport() call violates React Query for ALL Data Operations rule
• Required Fix: Create useSessionExport hook in @/services/queries/use-sessions.ts
• Pattern: See .claude/patterns/react-query-usage.md - Pattern 2
• Why Blocker: Zero-tolerance frontend rule that prevents cache inconsistencies

2. Missing Error Handling in MCP Invoke Route

• Location: route.ts:34-38
• Issue: Returns raw errorText without parsing - may not be valid JSON
• Impact: Client-side errors when backend returns non-JSON error text

🔴 Critical Issues

3. Async Handler Without React Query Mutation

• Location: session-header.tsx:82-123
• Issue: handleExport is async but doesn't use React Query mutations
• Impact: Inconsistent with codebase patterns, manual error handling

4. Type Safety: Weak Type Guard

• Location: export-chat.ts:21-23
• Issue: isExportEvent only checks 'type' in raw
• Fix: Add runtime validation for all expected properties

5. Security: Incomplete URL Validation

• Location: export-chat.ts:390-391
• Issue: Link rendering only checks /^https?:///i regex
• Risk: Vulnerable to javascript: URIs if regex fails
• Fix: Use URL() constructor with protocol check

🟡 Major Issues

6. Unnecessary Hook Calls

• Location: session-header.tsx:55-60
• Issue: useMcpStatus and useGoogleStatus called unconditionally
• Impact: Unnecessary API calls when only used for gdrive export

7. Missing Empty State Handling

• Location: export-chat.ts:169-174
• Issue: No check if exportData.aguiEvents exists before assembleBlocks

8. Inconsistent Error Messages

• Location: session-header.tsx:85-91
• Issue: Error messages lack consistent capitalization/punctuation

🔵 Minor Issues

9. Magic Numbers: Truncation limits hardcoded (export-chat.ts:25-27)
10. Complex Timing Logic: Print dialog could use Promise.race
11. Missing JSDoc: Public functions lack parameter documentation
12. Unexplained Tailwind Change: Removes tw-animate-css plugin

Positive Highlights

✅ Excellent XSS Prevention with escapeHtml
✅ Good HTML Sanitization in inlineFormat
✅ Well-Structured Code with clean separation
✅ Comprehensive Markdown Conversion
✅ Type Safety - no any types
✅ Accessibility - print styles include break-inside
✅ Code Reuse - extracted triggerDownload utility
✅ Visual Polish with emoji icons

Recommendations

Priority 1 (Must Fix Before Merge):

1. Convert handleExport to use React Query mutation
2. Fix error handling in MCP route
3. Strengthen type guard validation
4. Fix URL validation security issue

Priority 2 (Should Fix Before Merge):
5. Add null check for exportData.aguiEvents
6. Optimize conditional hook calls
7. Standardize error messages

Priority 3 (Nice to Have):
8. Extract magic numbers to constants
9. Add JSDoc to public functions
10. Clarify tailwind config change

Pre-Commit Checklist

• ✅ Zero any types
• ✅ All UI uses Shadcn components
• ❌ FAILED: All data operations use React Query (Blocker)
• ✅ Components under 200 lines
• ✅ All buttons have loading states
• ⚠️ Error handling needs improvement

---

Overall Assessment: Good implementation with solid security practices, but requires critical fixes to React Query usage and error handling before merge.

🤖 Reviewed with Claude Code

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.

[github-actions]

Claude Code Review

Summary

This PR adds chat export functionality (Markdown/PDF) to the session kebab menu with Google Drive integration. The implementation is generally solid with good security practices (XSS prevention via HTML escaping). However, there are several issues that need attention ranging from critical type safety violations to architectural concerns.

Issues by Severity

Critical Issues

1. Missing Error Handling in MCP Invoke Route (route.ts:24-42)

   • No validation of request body before forwarding to backend
   • Should validate required fields (server, tool, args) to prevent malformed requests
   • Missing type safety for request/response bodies

2. Potential XSS in URL Rendering (export-chat.ts:396-406)

   • While escapeHtml() is called first (good!), the URL itself in href attribute should also be escaped
   • Line 400 needs URL escaping in href attribute

3. Type Safety Violation - Async Error Handling (session-header.tsx:56, 66, 77)

   • void handleExport in onClick handlers masks async errors
   • Violates Zero any Types rule

Major Issues

4. Missing React Query Integration (session-header.tsx:82-90)

   • saveToGoogleDrive called directly instead of using mutation hook
   • Violates React Query for ALL Data Operations pattern

5. Inconsistent Loading State Management (session-header.tsx:44)

   • Uses local state exportLoading instead of React Query isPending

6. Missing Error Boundary for PDF Export (export-chat.ts:240-298)

   • window.open() can fail but error handling is generic

7. Hardcoded Timeout (export-chat.ts:294)

   • 500ms timeout may be too short for slow browsers

Minor Issues

8-13. Documentation, constants, type guards, JSDoc improvements

Positive Highlights

• Excellent XSS Prevention with proper escapeHtml usage
• Good Code Reuse with extracted triggerDownload utility
• Comprehensive Markdown Conversion for all AG-UI events
• Strong UX with loading states and notifications
• Security-First URL Validation (http/https only)
• Print-Friendly CSS with media queries
• Guard Against Double-Print Bug

Recommendations

Priority 1 (Before Merge):

1. Fix XSS vulnerability in URL href attribute
2. Add request validation to MCP invoke route
3. Create React Query mutation hook for Google Drive save
4. Handle async errors properly

Recommendation: Fix Critical and Major issues before merge. Minor issues can be addressed in follow-up PRs.

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.

[github-actions]

Claude Code Review

Summary

This PR adds a comprehensive chat export feature with Markdown, PDF, and Google Drive export options. The implementation demonstrates strong attention to security (XSS prevention), code organization (extraction of shared utilities), and user experience (loading states, proper error handling). The code follows frontend development patterns well and includes thoughtful defensive programming practices.

Overall Assessment: Strong implementation with a few minor improvements needed before merge.

Issues by Severity

🟡 Major Issues

1. Type Safety Violation - any type usage

• Location: export-chat.ts:398-408
• Issue: The regex replace callback uses implicit any types for _match, text, and url parameters
• Pattern Violation: Frontend Critical Rule Outcome: Reduce Refinement Time with agent System #1 - Zero any Types
• Fix: Explicitly type the parameters:

result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match: string, text: string, url: string) => {

• Reference: .claude/context/frontend-development.md:15-34

2. Missing Error Handling in Google Drive Export

• Location: session-header.tsx:111-127 (handleExport function)
• Issue: The Google Drive save operation could fail silently if the MCP tool invocation fails but doesn't throw an error
• Pattern: Error handling patterns require comprehensive error coverage
• Recommendation: Add validation of the MCP response to ensure the file was actually created
• Reference: .claude/patterns/error-handling.md:199-220

3. Inconsistent Loading State Management

• Location: session-header.tsx:44 and session-header.tsx:84-128
• Issue: The exportLoading state uses union type 'markdown' | 'pdf' | 'gdrive' | null, but there's no centralized reset mechanism if multiple operations are triggered
• Pattern: React state should handle edge cases (rapid clicks, concurrent operations)
• Recommendation: Add debouncing or disable all export options when any export is in progress

🔵 Minor Issues

1. Hardcoded Magic Numbers

• Location: export-chat.ts:27-29
• Issue: Truncation limits (2000, 1000, 2000) are magic numbers
• Recommendation: Extract to named constants with descriptive comments explaining why these limits

// Prevents excessively large markdown files that may crash browsers
const MAX_TOOL_ARGS_LENGTH = 2000;
const MAX_ERROR_LENGTH = 1000;
const MAX_RESULT_LENGTH = 2000;

2. Window.open Popup Blocker Handling

• Location: export-chat.ts:245-248
• Issue: Error message could be more helpful - should explain HOW to allow popups
• Recommendation: Improve error message:

throw new Error('Failed to open print window. Please allow popups for this site in your browser settings and try again.');

3. Missing Component Size Check

• Location: session-header.tsx
• Issue: File is 402 lines (after changes), approaching the 200-line guideline from frontend standards
• Pattern Violation: Frontend checklist suggests components under 200 lines
• Recommendation: Consider extracting export submenu to separate component file: _components/export-submenu.tsx
• Reference: components/frontend/DESIGN_GUIDELINES.md

4. Toast Duration Configuration Change

• Location: toaster.tsx:17
• Issue: Changed toast duration from default to 5000ms without PR description explaining why
• Recommendation: Document this change in commit message or PR description - is this intentional for export feedback?

5. Tailwind Plugin Removal

• Location: tailwind.config.js:96-98
• Issue: Removed tw-animate-css plugin without explanation
• Concern: Could break existing animations elsewhere in the app
• Recommendation: Verify no other components depend on this plugin, or document the removal reason

6. URL Validation in Markdown Conversion

• Location: export-chat.ts:398-408
• Issue: URL validation only allows http/https, but GitHub URLs in session data might use git:// or ssh://
• Recommendation: Consider supporting additional protocols or document the limitation

7. Missing Test Coverage Mention

• Issue: PR includes comprehensive manual test plan, but no mention of automated tests
• Recommendation: Add Cypress test for export functionality to e2e/cypress/e2e/sessions.cy.ts

Positive Highlights

✅ Excellent Security Practices

• HTML escaping (escapeHtml) applied before markdown formatting to prevent XSS (export-chat.ts:395-396)
• URL protocol validation restricts to http/https only (export-chat.ts:400-402)
• Proper handling of user-generated content throughout

✅ Code Reuse & Refactoring

• Extracted shared triggerDownload utility from duplicated blob-download pattern
• DRY principle applied between new export and existing JSON export
• Clean separation of concerns (markdown generation, HTML conversion, download triggering)

✅ Robust Error Handling

• Try-catch blocks around all async operations
• User-friendly error messages via toast notifications
• Graceful fallbacks (e.g., timestamp parsing, JSON parsing)

✅ Comprehensive Loading States

• Per-format loading indicators (markdown/pdf/gdrive) with spinner icons
• Disabled state during export operations prevents double-clicks
• isPending pattern follows React Query best practices

✅ Accessibility & UX

• Visual feedback with loading spinners (Loader2 component)
• Clear error messages for missing prerequisites (Google Drive connection check)
• Proper cleanup (URL.revokeObjectURL after download)

✅ TypeScript Type Safety (mostly)

• Proper type guards (isExportEvent)
• Discriminated unions for ConversationBlock
• Type-safe API integration with SessionExportResponse

✅ React Query Integration

• Proper use of useQuery with refetch for on-demand data loading
• Follows established patterns from .claude/patterns/react-query-usage.md
• Correct query key structure for useGoogleStatus and useMcpStatus

✅ PDF Export Implementation

• Double-print guard flag prevents duplicate print dialogs (export-chat.ts:290-300)
• Print-specific CSS with @media print rules
• Styled output improves readability

Recommendations

Priority 1 (Before Merge)

1. Fix any type violation in export-chat.ts:398 - explicitly type regex callback parameters
2. Verify tailwind plugin removal doesn't break existing animations
3. Add validation for Google Drive MCP response

Priority 2 (Follow-up)

1. Add Cypress test for export functionality
2. Extract export submenu to separate component if file size continues to grow
3. Document toast duration change or revert if unintentional

Priority 3 (Nice-to-Have)

1. Consider adding file size warnings for very large conversations
2. Add export progress indication for large session histories
3. Support additional URL protocols (git://, ssh://) in markdown conversion

Code Quality Checklist

• All UI uses Shadcn components
• All data operations use React Query
• All buttons have loading states
• Zero any types (one violation found)
• Components under 200 lines (session-header.tsx is 402 lines - approaching limit)
• Single-use components colocated
• All nested pages have breadcrumbs (N/A - utility file)
• Proper error handling
• Security practices followed (XSS prevention, input validation)

Final Verdict

Recommend: Merge after addressing Priority 1 items

This is a well-crafted feature with excellent attention to security and user experience. The one critical type safety violation should be fixed before merge, and the tailwind plugin removal should be verified. Everything else can be addressed in follow-up work.

Great job on the security-conscious implementation (HTML escaping, URL validation) and the thoughtful refactoring to extract shared utilities! 🎉

---

🤖 Reviewed by Claude Code using repository standards from CLAUDE.md and .claude/context/**

---

🔍 View AI decision process (logs available for 90 days)

📋 View memory system files loaded (click to expand)

What Amber Loaded for Code Review

Amber automatically loaded these repository standards from the memory system:

1. CLAUDE.md - Master project instructions, development standards
2. backend-development.md - Go backend, K8s integration patterns
3. frontend-development.md - NextJS, Shadcn UI, React Query patterns
4. security-standards.md - Auth, RBAC, token handling
5. k8s-client-usage.md - User token vs service account patterns
6. error-handling.md - Consistent error patterns
7. react-query-usage.md - Data fetching patterns

Impact: This review used your repository's specific code quality standards, security patterns, and best practices from the memory system (PRs #359, #360) - not just generic code review guidelines.