MAESTRO: Add table of contents jumper for markdown file preview

- Added floating TOC button (List icon) in bottom-left of markdown preview
- TOC overlay shows all H1-H6 headings with proper indentation by level
- Headings are color-coded to match the markdown prose heading colors
- Maximum overlay height is 70% of viewport for readability
- Clicking a heading scrolls to that section and closes the overlay
- Escape key closes the overlay
- Only visible in preview mode when document has headings
- Added 6 unit tests for the TOC feature

Author: pedramamini

src/__tests__/renderer/components/FilePreview.test.tsx

@@ -22,6 +22,7 @@ vi.mock('lucide-react', () => ({
 	AlertTriangle: () => <span data-testid="alert-icon">AlertTriangle</span>,
 	Share2: () => <span data-testid="share-icon">Share2</span>,
 	GitGraph: () => <span data-testid="gitgraph-icon">GitGraph</span>,
+	List: () => <span data-testid="list-icon">List</span>,
 }));
 
 // Mock react-markdown
@@ -386,4 +387,101 @@ describe('FilePreview', () => {
 			expect(screen.queryByText(/tokens/)).not.toBeInTheDocument();
 		});
 	});
+
+	describe('table of contents', () => {
+		it('shows TOC button for markdown files with headings in preview mode', () => {
+			const markdownWithHeadings = '# Heading 1\n## Heading 2\n### Heading 3\nContent here';
+			render(
+				<FilePreview
+					{...defaultProps}
+					file={{ name: 'doc.md', content: markdownWithHeadings, path: '/test/doc.md' }}
+					markdownEditMode={false}
+				/>
+			);
+
+			expect(screen.getByTitle('Table of Contents')).toBeInTheDocument();
+			expect(screen.getByTestId('list-icon')).toBeInTheDocument();
+		});
+
+		it('does not show TOC button for markdown without headings', () => {
+			const markdownNoHeadings = 'This is just plain text.\nNo headings here.';
+			render(
+				<FilePreview
+					{...defaultProps}
+					file={{ name: 'doc.md', content: markdownNoHeadings, path: '/test/doc.md' }}
+					markdownEditMode={false}
+				/>
+			);
+
+			expect(screen.queryByTitle('Table of Contents')).not.toBeInTheDocument();
+		});
+
+		it('does not show TOC button in edit mode', () => {
+			const markdownWithHeadings = '# Heading 1\n## Heading 2';
+			render(
+				<FilePreview
+					{...defaultProps}
+					file={{ name: 'doc.md', content: markdownWithHeadings, path: '/test/doc.md' }}
+					markdownEditMode={true}
+				/>
+			);
+
+			expect(screen.queryByTitle('Table of Contents')).not.toBeInTheDocument();
+		});
+
+		it('does not show TOC button for non-markdown files', () => {
+			const jsonContent = '{"title": "Not markdown"}';
+			render(
+				<FilePreview
+					{...defaultProps}
+					file={{ name: 'config.json', content: jsonContent, path: '/test/config.json' }}
+				/>
+			);
+
+			expect(screen.queryByTitle('Table of Contents')).not.toBeInTheDocument();
+		});
+
+		it('opens TOC overlay when button is clicked', () => {
+			const markdownWithHeadings = '# Heading 1\n## Heading 2\n### Heading 3';
+			render(
+				<FilePreview
+					{...defaultProps}
+					file={{ name: 'doc.md', content: markdownWithHeadings, path: '/test/doc.md' }}
+					markdownEditMode={false}
+				/>
+			);
+
+			const tocButton = screen.getByTitle('Table of Contents');
+			fireEvent.click(tocButton);
+
+			// TOC overlay should be visible with heading entries
+			expect(screen.getByText('Contents')).toBeInTheDocument();
+			expect(screen.getByText('3 headings')).toBeInTheDocument();
+			expect(screen.getByText('Heading 1')).toBeInTheDocument();
+			expect(screen.getByText('Heading 2')).toBeInTheDocument();
+			expect(screen.getByText('Heading 3')).toBeInTheDocument();
+		});
+
+		it('closes TOC overlay when clicking a heading entry', () => {
+			const markdownWithHeadings = '# Heading 1\n## Heading 2';
+			render(
+				<FilePreview
+					{...defaultProps}
+					file={{ name: 'doc.md', content: markdownWithHeadings, path: '/test/doc.md' }}
+					markdownEditMode={false}
+				/>
+			);
+
+			// Open TOC
+			const tocButton = screen.getByTitle('Table of Contents');
+			fireEvent.click(tocButton);
+
+			// Click a heading entry
+			const headingEntry = screen.getByText('Heading 1');
+			fireEvent.click(headingEntry);
+
+			// TOC overlay should close
+			expect(screen.queryByText('Contents')).not.toBeInTheDocument();
+		});
+	});
 });

src/renderer/components/FilePreview.tsx

@@ -31,6 +31,7 @@ import {
 	AlertTriangle,
 	Share2,
 	GitGraph,
+	List,
 } from 'lucide-react';
 import { visit } from 'unist-util-visit';
 import { useLayerStack } from '../contexts/LayerStackContext';
@@ -247,6 +248,37 @@ const countMarkdownTasks = (content: string): { open: number; closed: number } =
 	};
 };
 
+// Interface for table of contents entries
+interface TocEntry {
+	level: number; // 1-6 for h1-h6
+	text: string;
+	slug: string;
+}
+
+// Extract headings from markdown content for table of contents
+const extractHeadings = (content: string): TocEntry[] => {
+	const headings: TocEntry[] = [];
+	const lines = content.split('\n');
+
+	for (const line of lines) {
+		// Match ATX-style headings (# H1, ## H2, etc.)
+		const match = line.match(/^(#{1,6})\s+(.+)$/);
+		if (match) {
+			const level = match[1].length;
+			const text = match[2].trim();
+			// Generate slug same way rehype-slug does (lowercase, replace spaces with hyphens, remove special chars)
+			const slug = text
+				.toLowerCase()
+				.replace(/[^\w\s-]/g, '')
+				.replace(/\s+/g, '-')
+				.replace(/^-+|-+$/g, '');
+			headings.push({ level, text, slug });
+		}
+	}
+
+	return headings;
+};
+
 // Helper to resolve image path relative to markdown file directory
 const resolveImagePath = (src: string, markdownFilePath: string): string => {
 	// If it's already a data URL or http(s) URL, return as-is
@@ -518,6 +550,7 @@ export const FilePreview = forwardRef<FilePreviewHandle, FilePreviewProps>(funct
 	const [showCopyNotification, setShowCopyNotification] = useState(false);
 	const [showBackPopup, setShowBackPopup] = useState(false);
 	const [showForwardPopup, setShowForwardPopup] = useState(false);
+	const [showTocOverlay, setShowTocOverlay] = useState(false);
 	const backPopupTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 	const forwardPopupTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 	const [currentMatchIndex, setCurrentMatchIndex] = useState(0);
@@ -601,6 +634,12 @@ export const FilePreview = forwardRef<FilePreviewHandle, FilePreviewProps>(funct
 		return counts;
 	}, [isMarkdown, file?.content]);
 
+	// Extract table of contents entries for markdown files
+	const tocEntries = useMemo(() => {
+		if (!isMarkdown || !file?.content) return [];
+		return extractHeadings(file.content);
+	}, [isMarkdown, file?.content]);
+
 	// Memoize file tree indices to avoid O(n) traversal on every render
 	const fileTreeIndices = useMemo(() => {
 		if (fileTree && fileTree.length > 0) {
@@ -875,11 +914,16 @@ export const FilePreview = forwardRef<FilePreviewHandle, FilePreviewProps>(funct
 	// Auto-focus on mount and when file changes so keyboard shortcuts work immediately
 	useEffect(() => {
 		containerRef.current?.focus();
+		// Close TOC overlay when file changes
+		setShowTocOverlay(false);
 	}, [file?.path]); // Run on mount and when navigating to a different file
 
 	// Helper to handle escape key - shows confirmation modal if there are unsaved changes
 	const handleEscapeRequest = useCallback(() => {
-		if (searchOpen) {
+		if (showTocOverlay) {
+			setShowTocOverlay(false);
+			containerRef.current?.focus();
+		} else if (searchOpen) {
 			setSearchOpen(false);
 			setSearchQuery('');
 			// Refocus container so keyboard navigation (arrow keys) still works
@@ -890,7 +934,7 @@ export const FilePreview = forwardRef<FilePreviewHandle, FilePreviewProps>(funct
 		} else {
 			onClose();
 		}
-	}, [searchOpen, hasChanges, onClose]);
+	}, [showTocOverlay, searchOpen, hasChanges, onClose]);
 
 	// Register layer on mount - only register once, use updateLayerHandler for handler changes
 	// Note: handleEscapeRequest is intentionally NOT in the dependency array to prevent
@@ -1993,6 +2037,99 @@ export const FilePreview = forwardRef<FilePreviewHandle, FilePreviewProps>(funct
 						</SyntaxHighlighter>
 					</div>
 				)}
+
+				{/* Table of Contents Floating Button and Overlay - Only for markdown in preview mode */}
+				{isMarkdown && !markdownEditMode && tocEntries.length > 0 && (
+					<>
+						{/* Floating TOC Button */}
+						<button
+							onClick={() => setShowTocOverlay(!showTocOverlay)}
+							className="absolute bottom-4 left-4 p-2.5 rounded-full shadow-lg transition-all duration-200 hover:scale-105 z-10"
+							style={{
+								backgroundColor: showTocOverlay ? theme.colors.accent : theme.colors.bgSidebar,
+								color: showTocOverlay ? theme.colors.accentForeground : theme.colors.textMain,
+								border: `1px solid ${theme.colors.border}`,
+							}}
+							title="Table of Contents"
+						>
+							<List className="w-5 h-5" />
+						</button>
+
+						{/* TOC Overlay */}
+						{showTocOverlay && (
+							<div
+								className="absolute bottom-16 left-4 rounded-lg shadow-xl overflow-hidden z-20 animate-in fade-in slide-in-from-bottom-2 duration-200"
+								style={{
+									backgroundColor: theme.colors.bgSidebar,
+									border: `1px solid ${theme.colors.border}`,
+									maxHeight: '70%',
+									minWidth: '200px',
+									maxWidth: '350px',
+								}}
+							>
+								{/* TOC Header */}
+								<div
+									className="px-3 py-2 border-b flex items-center justify-between"
+									style={{ borderColor: theme.colors.border }}
+								>
+									<span
+										className="text-xs font-medium uppercase tracking-wide"
+										style={{ color: theme.colors.textDim }}
+									>
+										Contents
+									</span>
+									<span
+										className="text-[10px]"
+										style={{ color: theme.colors.textDim }}
+									>
+										{tocEntries.length} headings
+									</span>
+								</div>
+								{/* TOC Entries */}
+								<div className="overflow-y-auto p-1" style={{ maxHeight: 'calc(70vh - 40px)' }}>
+									{tocEntries.map((entry, index) => {
+										// Get color based on heading level (match the prose styles)
+										const levelColors: Record<number, string> = {
+											1: theme.colors.accent,
+											2: theme.colors.success,
+											3: theme.colors.warning,
+											4: theme.colors.textMain,
+											5: theme.colors.textMain,
+											6: theme.colors.textDim,
+										};
+										const headingColor = levelColors[entry.level] || theme.colors.textMain;
+
+										return (
+											<button
+												key={`${entry.slug}-${index}`}
+												onClick={() => {
+													// Find and scroll to the heading
+													const targetElement = markdownContainerRef.current?.querySelector(
+														`#${CSS.escape(entry.slug)}`
+													);
+													if (targetElement) {
+														targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
+													}
+													setShowTocOverlay(false);
+												}}
+												className="w-full px-2 py-1.5 text-left text-sm rounded hover:bg-white/10 transition-colors truncate flex items-center gap-1"
+												style={{
+													color: headingColor,
+													paddingLeft: `${(entry.level - 1) * 12 + 8}px`,
+													opacity: entry.level > 3 ? 0.85 : 1,
+													fontSize: entry.level === 1 ? '0.875rem' : entry.level === 2 ? '0.8125rem' : '0.75rem',
+												}}
+												title={entry.text}
+											>
+												<span className="truncate">{entry.text}</span>
+											</button>
+										);
+									})}
+								</div>
+							</div>
+						)}
+					</>
+				)}
 			</div>
 
 			{/* Copy Notification Toast */}