markdown-converter/docs/plans/2026-03-24-v4-enhancement-flutter-design.md

V4 Enhancement + Flutter Exploration Design

Date: 2026-03-24 Status: Approved Approach: Incremental V4 Enhancement + Flutter Spike (70/30 split)

---

Executive Summary

This design outlines a two-track approach:

1. V4 Enhancement (70%): Fix critical bugs, optimize performance, add platform adapters, improve UI patterns
2. Flutter Exploration (30%): Build proof-of-concept for cross-platform evaluation (Windows, Mobile, Web)

---

Goals & Scope

Primary Goals

1. Fix critical bug: PDF and markdown multitab functionality
2. Performance improvements: Faster startup, smoother editing, responsive preview
3. Architecture improvements: Platform adapters, cleaner state management
4. Flutter research: Proof-of-concept for cross-platform evaluation

Out of Scope

• Full V5 migration
• Complete UI redesign
• New features (focus on optimization)

Success Criteria

Metric	Current	Target
Startup time	~3-5s	<2s
Editor typing latency	Noticeable lag	<16ms
Preview render (1MB file)	~500ms	<200ms
Memory usage	~300MB	<200MB
Bundle size	~150MB	<100MB

---

Section 1: V4 Critical Fixes & Performance Optimizations

1.1 Fix: PDF/Markdown Multitab Bug

Location: src/renderer.js (TabManager class)

Investigation areas:

• switchToTab() - ensure proper state preservation
• closeTab() - ensure EditorView cleanup
• Add tab type tracking (markdown vs pdf)
• Isolate PDF viewer state from editor state

1.2 Startup Performance Optimizations

Optimization	Implementation	Expected Gain
Defer Mermaid	Load only when diagram detected	~500ms
Defer PDF.js	Load on first PDF open	~800ms
Lazy load themes	Load active theme only	~200ms
Lazy sidebar panels	Load panel code when sidebar opens	~300ms
Preload optimization	Remove unused IPC channels	~100ms

Lazy loading pattern:

// Current (loads everything upfront)
const { dialog } = require('@electron/remote');

// Optimized (load on demand)
let _dialog;
function getDialog() {
  if (!_dialog) _dialog = require('@electron/remote').dialog;
  return _dialog;
}

1.3 Editor Performance

Issue	Solution
Typing lag with large files	Debounce preview updates (300ms)
Syntax highlight overhead	Use highlight.js lazy mode
Memory leaks	Clean up EditorView on tab close
Theme switching lag	Pre-compile theme CSS

1.4 Preview Rendering

Issue	Solution
Mermaid slow	Render on-demand, cache results
Full re-render on keystroke	Debounced incremental updates
Large documents	Viewport rendering (visible portion only)

---

Section 2: Platform Adapter Pattern

2.1 Architecture

src/
├── adapters/
│   ├── index.js              # Auto-detects and exports adapter
│   ├── types.js              # Interface definitions (JSDoc)
│   │
│   ├── electron/             # Current Electron implementation
│   │   ├── index.js          # Exports electronAdapter
│   │   ├── fs.js             # File system operations
│   │   ├── convert.js        # Pandoc, FFmpeg conversions
│   │   ├── pdf.js            # PDF operations
│   │   └── system.js         # System info, dialogs, notifications
│   │
│   └── mock/                 # For testing
│       └── index.js          # Mock adapter for unit tests

2.2 Adapter Interface

/**
 * @typedef {Object} PlatformAdapter
 * @property {'electron'} name
 * @property {FileSystemAdapter} fs
 * @property {ConversionAdapter} convert
 * @property {PdfAdapter} pdf
 * @property {SystemAdapter} system
 */

/**
 * @typedef {Object} FileSystemAdapter
 * @property {(path: string) => Promise<string>} readFile
 * @property {(path: string, content: string) => Promise<void>} writeFile
 * @property {(path: string) => Promise<void>} deleteFile
 * @property {(path: string) => Promise<FileInfo[]>} listDirectory
 * @property {(path: string) => Promise<boolean>} exists
 */

2.3 Migration Strategy

Phase	What	Files Affected
1	Create adapter structure	New files only
2	Migrate file operations	renderer.js, sidebar/*.js
3	Migrate conversions	Export dialogs
4	Migrate PDF operations	PDF viewer
5	Remove old IPC calls	preload.js cleanup

---

Section 3: UI Improvements (Shadcn/ui Patterns)

3.1 Design Token System

/* src/styles/tokens.css */

:root {
  /* Colors - Light mode */
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 227 44% 52%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --destructive: 0 84.2% 60.2%;
  --border: 214.3 31.8% 91.4%;
  --ring: 227 44% 52%;

  /* Spacing & Radii */
  --radius: 0.5rem;
}

3.2 Component Improvements

Component	Current Issue	Fix
Buttons	Inconsistent hover/focus	Use .btn with variants
Dialogs	Missing focus trap	Add focus trap, Escape key, aria-modal
Tabs	No keyboard navigation	Add arrow key nav, aria-selected
Sidebar	No collapse animation	CSS transitions
Dropdowns	Missing click-outside	Add proper event handling

3.3 Accessibility Improvements

• Focus states with :focus-visible
• Skip to content link
• ARIA labels on interactive elements
• Keyboard navigation for all components

---

Section 4: Flutter Exploration (30% Effort)

4.1 Flutter Project Structure

markdown-converter-flutter/
├── lib/
│   ├── main.dart
│   ├── app.dart
│   ├── core/
│   │   ├── theme/
│   │   └── constants.dart
│   ├── features/
│   │   ├── editor/
│   │   ├── preview/
│   │   └── tabs/
│   ├── services/
│   │   ├── file_service.dart
│   │   ├── export_service.dart
│   │   └── platform_service.dart
│   └── adapters/
│       ├── file_adapter.dart
│       ├── file_adapter_mobile.dart
│       ├── file_adapter_web.dart
│       └── file_adapter_desktop.dart
├── pubspec.yaml
├── windows/
├── web/
└── lib/

4.2 Key Dependencies

dependencies:
  flutter_markdown: ^0.7.0
  flutter_code_editor: ^0.3.0
  provider: ^6.1.0
  file_picker: ^8.0.0
  path_provider: ^2.1.0
  pdf: ^3.10.0
  printing: ^5.12.0

4.3 Prototype Features

Feature	Priority
Basic markdown editor	Must have
Live preview	Must have
Light/dark theme	Must have
Tab management	Should have
File open/save	Should have
PDF export	Nice to have
Windows exe build	Must have
Web build	Must have
Mobile build	Should have

4.4 Evaluation Criteria

Metric	Target
Windows exe size	<50MB
Web initial load	<500KB
Cold start time	<2s
Editor typing latency	<16ms

4.5 Flutter vs Tauri Comparison

Aspect	Flutter	Tauri + React
Mobile support	✅ Excellent	❌ Requires separate app
Web performance	⚠️ Good, larger	✅ Excellent, small
Desktop bundle	⚠️ ~30-50MB	✅ ~5-10MB
Native feel	⚠️ Custom rendering	✅ System WebView
Code reuse	✅ 100% shared	⚠️ Some platform-specific

---

Implementation Timeline

Phase 1: V4 Critical Fixes (Week 1)

• Fix PDF/markdown multitab bug
• Implement startup optimizations
• Add debounced preview rendering

Phase 2: Platform Adapters (Week 2)

• Create adapter structure
• Migrate file operations
• Migrate conversions

Phase 3: UI Improvements (Week 3)

• Add design tokens
• Improve component accessibility
• Add keyboard navigation

Phase 4: Flutter Prototype (Weeks 2-4, parallel)

• Set up Flutter project
• Implement basic editor
• Build Windows and Web versions
• Document findings

---

Risk Mitigation

Risk	Mitigation
Multitab fix causes regressions	Comprehensive test suite before changes
Performance optimizations break features	Incremental changes with benchmarks
Flutter proves unsuitable	30% effort limit, V4 remains primary
Platform adapter migration too slow	Phased approach, each phase independent

---

Success Metrics

• Multitab functionality working correctly
• Startup time < 2 seconds
• No perceived editor lag with files < 1MB
• Preview renders in < 200ms
• Bundle size reduced by 30%+
• Platform adapters for fs, convert, pdf implemented
• Design tokens applied to all components
• Flutter prototype running on Windows + Web
• Flutter evaluation documented with recommendation

---

Document generated: 2026-03-24 Next step: Create detailed implementation plan