@brainfish-ai/components 0.18.4 → 0.18.6

package/markdown-editor.spec.md

@@ -1,915 +0,0 @@
-# Markdown Editor/Viewer Component Specification
-
-## 1. Purpose and Overview
-
-The Markdown Editor/Viewer is a comprehensive reusable component that provides both editing and read-only viewing capabilities for markdown content. It leverages TipTap as the foundation editor and extends the existing multimedia rendering patterns from FormattedMessage.tsx to support embedded content, suggestions, multiplayer collaboration, and streaming content.
-
-### 1.1 Core Objectives
-- Provide a Notion-like editing experience with rich markdown support
-- Seamlessly toggle between edit and read-only modes
-- Support multimedia embedding with consistent patterns from existing codebase
-- Enable collaborative editing with suggestion tracking
-- Handle streaming content for real-time applications
-- Maintain accessibility and performance standards
-
-## 2. Functional Requirements
-
-### 2.1 Mode Management
-- **Toggle Modes**: Switch between `edit` and `readonly` modes
-- **State Preservation**: Maintain content state when switching modes
-- **Mode-specific UI**: Different toolbar and interaction patterns per mode
-- **Keyboard Shortcuts**: Support common shortcuts (Ctrl+E to toggle, etc.)
-
-### 2.2 Edit Mode Features
-- **Rich Text Editing**: Support for all standard markdown elements
-- **Suggestion System**: Display edit suggestions with visual indicators
-- **Multimedia Insertion**: Drag-and-drop and paste support for media
-- **Collaboration**: Real-time multiplayer editing capabilities
-- **Formatting Toolbar**: Context-aware formatting controls
-- **Auto-save**: Periodic content persistence
-
-### 2.3 Read-Only Mode Features
-- **Multimedia Rendering**: Full support for all embed types from existing system
-- **Streaming Content**: Handle real-time content updates
-- **Interactive Elements**: Clickable links, zoomable images
-- **Export Options**: Copy, print, and share functionality
-
-### 2.4 Suggestion System
-- **Visual Indicators**: Strikethrough for deletions, underline for additions
-- **Interactive Controls**: Accept/reject individual or batch suggestions
-- **Keyboard Navigation**: Arrow keys and tab navigation through suggestions
-- **Mouse Interaction**: Click to accept/reject suggestions
-- **Suggestion Metadata**: Track author, timestamp, and reason
-
-### 2.5 Multimedia Support
-- **Image Handling**: Zoomable images using existing ZoomableImage component
-- **Video Support**: Native video player for mp4, mov files
-- **Diagram Rendering**: Mermaid diagrams using existing MermaidDiagram component
-- **Embeds**: YouTube, Vimeo, Wistia, Loom, Supademo, Typeform via existing embed system
-- **iFrame Support**: Generic iframe embedding with security controls
-
-## 3. Technical Requirements
-
-### 3.1 Technology Stack
-- **Core Editor**: TipTap v3+ with React integration and native document model
-- **Content Format**: TipTap JSON format for internal storage and editing
-- **Markdown Translation**: Utility layer using remark-gfm, rehype-raw for import/export + initial loading of existing documents
-- **State Management**: React state with optional external state management
-- **Styling**: Tailwind CSS classes consistent with existing components
-- **TypeScript**: Full type safety with proper interfaces
-
-### 3.2 Performance Requirements
-- **Initial Load**: < 500ms time to interactive
-- **Mode Switching**: < 100ms transition time
-- **Large Documents**: Support documents up to 1MB in size
-- **Memory Usage**: < 50MB for typical documents
-- **Streaming**: Handle 1000+ characters/second streaming rate
-
-### 3.3 Accessibility Requirements
-- **ARIA Labels**: Proper labeling for all interactive elements
-- **Keyboard Navigation**: Full keyboard accessibility
-- **Screen Reader**: Compatible with major screen readers
-- **Color Contrast**: WCAG 2.1 AA compliance
-- **Focus Management**: Proper focus handling in all modes
-
-## 4. API Design
-
-### 4.1 Component Props Interface
-
-```typescript
-interface MarkdownEditorViewerProps {
-  // Core content and mode
-  content: string;
-  mode: 'edit' | 'readonly';
-  onContentChange?: (content: string) => void;
-  onModeChange?: (mode: 'edit' | 'readonly') => void;
-
-  // Streaming support
-  isStreaming?: boolean;
-
-  // Suggestion system
-  suggestions?: EditorSuggestion[];
-  onSuggestionAccept?: (suggestionId: string) => void;
-  onSuggestionReject?: (suggestionId: string) => void;
-  showSuggestions?: boolean;
-
-  // Collaboration
-  collaborators?: Collaborator[];
-  currentUser?: User;
-  onCollaboratorCursor?: (userId: string, position: number) => void;
-
-  // Multimedia and embeds
-  contentTypeEndpoint?: string;
-  redirectRules?: RedirectRule[];
-  allowedEmbeds?: EmbedType[];
-  maxFileSize?: number;
-
-  // Editor configuration
-  placeholder?: string;
-  autoFocus?: boolean;
-  readOnly?: boolean;
-  className?: string;
-
-  // Callbacks
-  onSave?: (content: string) => void;
-  onError?: (error: EditorError) => void;
-  onChange?: (content: string, delta?: any) => void;
-}
-
-interface EditorSuggestion {
-  id: string;
-  type: 'insert' | 'delete' | 'replace';
-  position: { from: number; to: number };
-  oldText?: string;
-  newText?: string;
-  author?: User;
-  timestamp: Date;
-  reason?: string;
-  status: 'pending' | 'accepted' | 'rejected';
-}
-
-interface Collaborator {
-  id: string;
-  name: string;
-  avatar?: string;
-  color: string;
-  cursor?: { position: number; selection?: { from: number; to: number } };
-  isActive: boolean;
-}
-
-interface User {
-  id: string;
-  name: string;
-  email?: string;
-  avatar?: string;
-}
-
-type EmbedType = 'youtube' | 'vimeo' | 'wistia' | 'loom' | 'supademo' | 'typeform' | 'iframe' | 'mermaid' | 'image' | 'video';
-
-interface EditorError {
-  type: 'validation' | 'network' | 'permission' | 'file' | 'embed';
-  message: string;
-  details?: any;
-}
-```
-
-### 4.2 TipTap Extensions Configuration
-
-```typescript
-interface EditorExtensions {
-  // Core extensions
-  document: DocumentExtension;
-  paragraph: ParagraphExtension;
-  text: TextExtension;
-
-  // Formatting extensions
-  bold: BoldExtension;
-  italic: ItalicExtension;
-  code: CodeExtension;
-  codeBlock: CodeBlockExtension;
-  heading: HeadingExtension;
-
-  // Structure extensions
-  bulletList: BulletListExtension;
-  orderedList: OrderedListExtension;
-  listItem: ListItemExtension;
-  blockquote: BlockquoteExtension;
-  horizontalRule: HorizontalRuleExtension;
-
-  // Custom extensions
-  suggestions: SuggestionExtension;
-  multimedia: MultimediaExtension;
-  collaboration: CollaborationExtension;
-  streaming: StreamingExtension;
-
-  // Table support
-  table: TableExtension;
-  tableRow: TableRowExtension;
-  tableCell: TableCellExtension;
-  tableHeader: TableHeaderExtension;
-}
-```
-
-## 5. Architecture Design
-
-### 5.1 Monorepo Architecture
-
-The component will be developed within the **`@brainfish-ai/tiptap`** package. This package will contain the editor component (evolving from `SimpleEditor`), its UI primitives, custom hooks, and the required Tiptap extensions. This co-location simplifies dependencies and aligns the editor's UI with its core logic.
-
-### 5.2 Component Structure
-
-The following structure will be implemented within `packages/tiptap/src/`:
-
-```
-components/
-├── tiptap-templates/
-│   └── simple/
-│       ├── markdown-viewer-editor.tsx     # Editor Viewer component that lazy loads content-viewer or simple-editor based on mode
-│       ├── content-viewer.tsx     # Viewer component
-│       ├── simple-editor.tsx      # Editor component
-│       └── ...
-├── tiptap-ui/
-│   ├── ViewerContent.tsx          # Read-only renderer
-│   └── ...                        # Other UI components (Suggestions, Collaboration, etc.)
-└── tiptap-node/
-    └── ...                        # Custom node components
-lib/
-├── markdownTranslator.ts          # Markdown ↔ TipTap JSON conversion
-└── tiptap-utils.ts                # Generic Tiptap utilities
-extensions/
-├── SuggestionExtension.ts         # TipTap suggestion extension
-├── MultimediaExtension.ts         # Media handling extension
-├── CollaborationExtension.ts      # Multiplayer extension
-└── StreamingExtension.ts          # Streaming content extension
-hooks/
-└── ...                            # Custom hooks for editor functionality
-```
-
-### 5.2 State Management Architecture
-
-```typescript
-interface EditorState {
-  // Content state
-  content: string;
-  mode: 'edit' | 'readonly';
-  isDirty: boolean;
-  lastSaved: Date | null;
-
-  // Suggestion state
-  suggestions: EditorSuggestion[];
-  activeSuggestion: string | null;
-  suggestionMode: boolean;
-
-  // Collaboration state
-  collaborators: Collaborator[];
-  currentUser: User | null;
-  isConnected: boolean;
-
-  // UI state
-  isLoading: boolean;
-  error: EditorError | null;
-  showToolbar: boolean;
-  fullscreen: boolean;
-
-  // Streaming state
-  isStreaming: boolean;
-  streamBuffer: string;
-}
-```
-
-## 6. TipTap Integration Specifications
-
-### 6.1 Core Editor Configuration
-
-```typescript
-const createEditor = (props: MarkdownEditorViewerProps) => {
-  return useEditor({
-    extensions: [
-      Document,
-      Paragraph,
-      Text,
-      Heading.configure({ levels: [1, 2, 3, 4, 5, 6] }),
-      Bold,
-      Italic,
-      Code,
-      CodeBlock.configure({
-        languageClassPrefix: 'language-',
-        HTMLAttributes: { class: 'code-block' },
-      }),
-      BulletList,
-      OrderedList,
-      ListItem,
-      Blockquote,
-      HorizontalRule,
-      Table.configure({ resizable: true }),
-      TableRow,
-      TableHeader,
-      TableCell,
-      // Custom extensions
-      SuggestionExtension.configure({
-        suggestion: {
-          items: props.suggestions || [],
-          render: renderSuggestion,
-        },
-      }),
-      MultimediaExtension.configure({
-        allowedTypes: props.allowedEmbeds || [],
-        maxFileSize: props.maxFileSize || 10 * 1024 * 1024, // 10MB
-      }),
-      StreamingExtension.configure({
-        onStream: handleStreamingContent,
-      }),
-    ],
-    content: props.content,
-    editable: props.mode === 'edit' && !props.readOnly,
-    onUpdate: ({ editor }) => {
-      const content = editor.getHTML();
-      props.onContentChange?.(content);
-      props.onChange?.(content);
-    },
-    parseOptions: {
-      preserveWhitespace: 'full',
-    },
-  });
-};
-```
-
-### 6.2 Custom TipTap Extensions
-
-#### 6.2.1 Suggestion Extension
-
-```typescript
-const SuggestionExtension = Extension.create({
-  name: 'suggestions',
-
-  addGlobalAttributes() {
-    return [
-      {
-        types: ['paragraph', 'heading', 'codeBlock'],
-        attributes: {
-          suggestionId: { default: null },
-          suggestionType: { default: null },
-          suggestionAuthor: { default: null },
-        },
-      },
-    ];
-  },
-
-  addCommands() {
-    return {
-      addSuggestion: (suggestion: EditorSuggestion) => ({ tr, state }) => {
-        // Implementation for adding suggestion marks
-      },
-      acceptSuggestion: (suggestionId: string) => ({ tr, state }) => {
-        // Implementation for accepting suggestions
-      },
-      rejectSuggestion: (suggestionId: string) => ({ tr, state }) => {
-        // Implementation for rejecting suggestions
-      },
-    };
-  },
-
-  addKeyboardShortcuts() {
-    return {
-      'Mod-Shift-a': () => this.editor.commands.acceptSuggestion(),
-      'Mod-Shift-r': () => this.editor.commands.rejectSuggestion(),
-    };
-  },
-});
-```
-
-#### 6.2.2 Multimedia Extension
-
-```typescript
-const MultimediaExtension = Extension.create({
-  name: 'multimedia',
-
-  addCommands() {
-    return {
-      insertMedia: (attrs: { src: string; type: string; alt?: string }) => ({ tr, state }) => {
-        // Implementation for inserting multimedia content
-      },
-      insertEmbed: (url: string) => ({ tr, state }) => {
-        // Implementation for inserting embeds
-      },
-    };
-  },
-
-  addProseMirrorPlugins() {
-    return [
-      new Plugin({
-        key: new PluginKey('multimedia'),
-        props: {
-          handleDOMEvents: {
-            paste: (view, event) => {
-              // Handle paste events for media
-            },
-            drop: (view, event) => {
-              // Handle drag and drop for media
-            },
-          },
-        },
-      }),
-    ];
-  },
-});
-```
-
-#### 6.2.3 Streaming Extension
-
-```typescript
-const StreamingExtension = Extension.create({
-  name: 'streaming',
-
-  addCommands() {
-    return {
-      appendStreamContent: (content: string) => ({ tr, state }) => {
-        // Implementation for appending streaming content
-      },
-      finalizeStream: () => ({ tr, state }) => {
-        // Implementation for finalizing streamed content
-      },
-    };
-  },
-
-  onCreate() {
-    this.options.onStream?.(this.editor);
-  },
-});
-```
-
-## 7. Markdown Translation Layer
-
-### 7.1 Markdown ↔ TipTap Conversion Utility
-
-```typescript
-interface MarkdownTranslator {
-  // Convert markdown string to TipTap JSON format
-  markdownToTipTap(markdown: string): TipTapDocument;
-
-  // Convert TipTap JSON to markdown string
-  tipTapToMarkdown(doc: TipTapDocument): string;
-
-  // Handle existing FormattedMessage content
-  parseExistingContent(content: string, redirectRules?: RedirectRule[]): TipTapDocument;
-}
-
-const markdownTranslator = {
-  markdownToTipTap: (markdown: string) => {
-    // Use remark-gfm and rehype-raw to parse markdown
-    const processor = unified()
-      .use(remarkParse)
-      .use(remarkGfm)
-      .use(remarkRehype, { allowDangerousHtml: true })
-      .use(rehypeRaw);
-
-    const mdast = processor.parse(markdown);
-    const hast = processor.runSync(mdast);
-
-    // Convert HAST to TipTap JSON format
-    return convertHastToTipTap(hast);
-  },
-
-  tipTapToMarkdown: (doc: TipTapDocument) => {
-    // Convert TipTap JSON back to markdown
-    return convertTipTapToMarkdown(doc);
-  },
-
-  parseExistingContent: (content: string, redirectRules = []) => {
-    // Handle FormattedMessage-specific patterns and embeds
-    const processedContent = preprocessEmbeds(content, redirectRules);
-    return markdownTranslator.markdownToTipTap(processedContent);
-  }
-};
-```
-
-### 7.2 Content Flow Architecture
-
-```
-Existing Markdown → markdownTranslator.parseExistingContent() → TipTap JSON
-                                    ↓
-                              TipTap Editor
-                                    ↓
-              TipTap JSON → markdownTranslator.tipTapToMarkdown() → Markdown Export
-```
-
-## 8. Multimedia System Specifications
-
-### 8.1 Integration with Existing Embed System
-
-The component will leverage the existing embed system from `src/components/markdown/embeds/` with the following integration pattern:
-
-```typescript
-const MultimediaRenderer: React.FC<{ url: string; type: string }> = ({ url, type }) => {
-  // Reuse existing EmbedComponent logic
-  const embedComponent = EmbedComponent({
-    attrs: { href: url },
-    isAttachmentVideo: type === 'video',
-  });
-
-  if (React.isValidElement(embedComponent)) {
-    return embedComponent;
-  }
-
-  // Fallback for unsupported types
-  return <div>Unsupported media type: {type}</div>;
-};
-```
-
-### 7.2 Supported Multimedia Types
-
-| Type | Component | Description |
-|------|-----------|-------------|
-| Images | ZoomableImage | PNG, JPG, GIF, WebP with zoom functionality |
-| Videos | NativeVideo | MP4, MOV, WebM with native player |
-| Diagrams | MermaidDiagram | Mermaid syntax diagrams |
-| YouTube | Youtube | YouTube video embeds |
-| Vimeo | Vimeo | Vimeo video embeds |
-| Wistia | Wistia | Wistia video embeds |
-| Loom | Loom | Loom video embeds |
-| Supademo | Supademo | Supademo interactive demos |
-| Typeform | Typeform | Typeform embeds |
-| iFrames | Frame | Generic iframe support with security controls |
-
-### 7.3 Media Upload Workflow
-
-```typescript
-interface MediaUploadFlow {
-  1: 'User initiates upload (drag, paste, or button)';
-  2: 'Validate file type and size';
-  3: 'Show upload progress indicator';
-  4: 'Upload to server or process locally';
-  5: 'Insert media node into editor at cursor position';
-  6: 'Update content and trigger onChange';
-}
-```
-
-## 8. Suggestion System Implementation
-
-### 8.1 Visual Representation
-
-```css
-.suggestion-delete {
-  text-decoration: line-through;
-  background-color: rgba(239, 68, 68, 0.1);
-  color: rgba(239, 68, 68, 0.7);
-}
-
-.suggestion-insert {
-  text-decoration: underline;
-  background-color: rgba(34, 197, 94, 0.1);
-  color: rgba(34, 197, 94, 0.8);
-}
-
-.suggestion-replace .old-text {
-  text-decoration: line-through;
-  background-color: rgba(239, 68, 68, 0.1);
-}
-
-.suggestion-replace .new-text {
-  text-decoration: underline;
-  background-color: rgba(34, 197, 94, 0.1);
-}
-
-.suggestion-active {
-  outline: 2px solid #3b82f6;
-  outline-offset: 2px;
-}
-```
-
-### 8.2 Suggestion Interaction Handlers
-
-```typescript
-const useSuggestionHandlers = (editor: Editor) => {
-  const handleSuggestionAccept = useCallback((suggestionId: string) => {
-    const suggestion = findSuggestion(suggestionId);
-    if (!suggestion) return;
-
-    switch (suggestion.type) {
-      case 'insert':
-        editor.commands.insertContentAt(suggestion.position.from, suggestion.newText);
-        break;
-      case 'delete':
-        editor.commands.deleteRange(suggestion.position);
-        break;
-      case 'replace':
-        editor.commands.deleteRange(suggestion.position);
-        editor.commands.insertContentAt(suggestion.position.from, suggestion.newText);
-        break;
-    }
-
-    // Update suggestion status
-    onSuggestionAccept?.(suggestionId);
-  }, [editor, onSuggestionAccept]);
-
-  const handleSuggestionReject = useCallback((suggestionId: string) => {
-    removeSuggestionMarks(editor, suggestionId);
-    onSuggestionReject?.(suggestionId);
-  }, [editor, onSuggestionReject]);
-
-  return { handleSuggestionAccept, handleSuggestionReject };
-};
-```
-
-### 8.3 Keyboard Navigation
-
-```typescript
-const suggestionKeyboardShortcuts = {
-  'Tab': () => navigateToNextSuggestion(),
-  'Shift-Tab': () => navigateToPreviousSuggestion(),
-  'Enter': () => acceptActiveSuggestion(),
-  'Escape': () => rejectActiveSuggestion(),
-  'Mod-Shift-a': () => acceptAllSuggestions(),
-  'Mod-Shift-r': () => rejectAllSuggestions(),
-};
-```
-
-## 9. Multiplayer Collaboration Approach
-
-### 9.1 Collaboration Architecture
-
-```typescript
-interface CollaborationProvider {
-  // Connection management
-  connect(roomId: string, user: User): Promise<void>;
-  disconnect(): void;
-
-  // Document synchronization
-  sendUpdate(update: any): void;
-  onReceiveUpdate(callback: (update: any) => void): void;
-
-  // Cursor tracking
-  sendCursor(position: number, selection?: { from: number; to: number }): void;
-  onCursorUpdate(callback: (userId: string, cursor: CursorPosition) => void): void;
-
-  // Presence
-  sendPresence(data: any): void;
-  onPresenceUpdate(callback: (users: Collaborator[]) => void): void;
-}
-```
-
-### 9.2 Conflict Resolution
-
-```typescript
-interface ConflictResolution {
-  strategy: 'operational-transform' | 'crdt' | 'last-writer-wins';
-
-  resolveConflict(localUpdate: any, remoteUpdate: any): any;
-
-  transformUpdate(update: any, against: any): any;
-}
-```
-
-### 9.3 Real-time Features
-
-- **Live Cursors**: Show real-time cursor positions of collaborators
-- **Selection Indicators**: Highlight text selections from other users
-- **Typing Indicators**: Show when collaborators are typing
-- **Presence Awareness**: Display active collaborators list
-- **Version History**: Track document versions and changes
-- **Conflict Resolution**: Handle simultaneous edits gracefully
-
-## 10. Streaming Content Handling
-
-### 10.1 Streaming Interface
-
-```typescript
-interface StreamingHandler {
-  // Stream management
-  startStream(): void;
-  appendContent(chunk: string): void;
-  endStream(): void;
-
-  // Stream state
-  isStreaming: boolean;
-  buffer: string;
-
-  // Callbacks
-  onStreamStart?: () => void;
-  onStreamChunk?: (chunk: string) => void;
-  onStreamEnd?: () => void;
-}
-```
-
-### 10.2 Streaming Implementation
-
-```typescript
-const useStreaming = (editor: Editor) => {
-  const [streamBuffer, setStreamBuffer] = useState('');
-  const [isStreaming, setIsStreaming] = useState(false);
-
-  const appendStreamContent = useCallback((chunk: string) => {
-    setStreamBuffer(prev => prev + chunk);
-
-    // Update editor content without losing focus
-    editor.commands.insertContentAt(
-      editor.state.doc.content.size,
-      chunk,
-      false // Don't update selection
-    );
-  }, [editor]);
-
-  const finalizeStream = useCallback(() => {
-    setIsStreaming(false);
-    setStreamBuffer('');
-    // Process any final formatting or cleanup
-  }, []);
-
-  return {
-    isStreaming,
-    streamBuffer,
-    appendStreamContent,
-    finalizeStream,
-  };
-};
-```
-
-### 10.3 Streaming Optimizations
-
-- **Debounced Updates**: Batch rapid content updates
-- **Partial Rendering**: Only render visible content during streaming
-- **Memory Management**: Clean up old stream chunks
-- **Error Recovery**: Handle interrupted streams gracefully
-
-## 11. Performance Considerations
-
-### 11.1 Optimization Strategies
-
-- **Virtualization**: Use virtual scrolling for large documents
-- **Lazy Loading**: Load multimedia content on demand
-- **Code Splitting**: Split editor and viewer into separate bundles
-- **Memoization**: Cache expensive operations and renders
-- **Debouncing**: Debounce onChange events and auto-save
-
-### 11.2 Bundle Size Management
-
-```typescript
-// Dynamic imports for large dependencies
-const TipTapEditor = lazy(() => import('./components/Editor/EditorContent'));
-const MultimediaRenderer = lazy(() => import('./components/Multimedia/MediaRenderer'));
-const CollaborationFeatures = lazy(() => import('./components/Collaboration'));
-```
-
-### 11.3 Memory Management
-
-- **Content Cleanup**: Clear undo/redo history for large documents
-- **Event Listeners**: Properly clean up event listeners on unmount
-- **WebSocket Connections**: Close collaboration connections when not needed
-- **Media Caching**: Implement LRU cache for multimedia content
-
-## 12. Testing Strategy
-
-### 12.1 Unit Testing
-
-```typescript
-describe('MarkdownEditorViewer', () => {
-  describe('Mode Switching', () => {
-    it('should switch from edit to readonly mode', () => {});
-    it('should preserve content when switching modes', () => {});
-    it('should disable editing in readonly mode', () => {});
-  });
-
-  describe('Suggestion System', () => {
-    it('should display suggestions visually', () => {});
-    it('should accept suggestions correctly', () => {});
-    it('should reject suggestions correctly', () => {});
-    it('should handle keyboard navigation', () => {});
-  });
-
-  describe('Multimedia Handling', () => {
-    it('should render images correctly', () => {});
-    it('should embed videos properly', () => {});
-    it('should handle mermaid diagrams', () => {});
-    it('should process file uploads', () => {});
-  });
-
-  describe('Streaming Content', () => {
-    it('should append streaming content', () => {});
-    it('should handle stream interruption', () => {});
-    it('should finalize streams correctly', () => {});
-  });
-});
-```
-
-### 12.2 Integration Testing
-
-- **TipTap Integration**: Test editor initialization and extension loading
-- **Embed System**: Test multimedia rendering with existing embed components
-- **Collaboration**: Test real-time features with mock WebSocket connections
-- **Performance**: Test with large documents and multiple media items
-
-### 12.3 E2E Testing
-
-- **User Workflows**: Test complete editing and viewing workflows
-- **Cross-browser**: Test on major browsers and devices
-- **Accessibility**: Test with screen readers and keyboard navigation
-- **Error Scenarios**: Test error handling and recovery
-
-## 13. Dependencies and Integration Points
-
-### 13.1 Required Dependencies
-
-```json
-{
-  "dependencies": {
-    "@tiptap/react": "^2.1.0",
-    "@tiptap/starter-kit": "^2.1.0",
-    "@tiptap/extension-table": "^2.1.0",
-    "@tiptap/extension-collaboration": "^2.1.0",
-    "@tiptap/extension-collaboration-cursor": "^2.1.0",
-    "y-webrtc": "^10.2.5",
-    "yjs": "^13.6.0"
-  }
-}
-```
-
-### 13.2 Integration Points
-
-- **Existing Embed System**: `src/components/markdown/embeds/`
-- **Multimedia Components**: `ZoomableImage`, `MermaidDiagram`, `NativeVideo`
-- **UI Components**: Reuse existing Radix UI components for modals, dropdowns
-- **Styling System**: Leverage existing Tailwind CSS classes and design tokens
-- **Utils and Hooks**: Extend existing utility functions and custom hooks
-
-### 13.3 Breaking Changes
-
-- **None Expected**: Component designed to extend existing patterns
-- **Optional Integration**: Can be used alongside or instead of FormattedMessage
-- **Backward Compatibility**: Maintains compatibility with existing embed system
-
-## 14. Security Considerations
-
-### 14.1 Content Security
-
-- **XSS Prevention**: Sanitize user input and embedded content
-- **CSP Headers**: Implement Content Security Policy for iframe embeds
-- **URL Validation**: Validate and sanitize embedded URLs
-- **File Upload Security**: Implement file type and size validation
-
-### 14.2 Collaboration Security
-
-- **Authentication**: Verify user identity for collaboration features
-- **Authorization**: Control document access and editing permissions
-- **Data Encryption**: Encrypt collaboration data in transit
-- **Rate Limiting**: Prevent abuse of real-time features
-
-## 15. Accessibility Requirements
-
-### 15.1 ARIA Implementation
-
-```typescript
-const editorARIA = {
-  'aria-label': 'Markdown editor',
-  'aria-multiline': 'true',
-  'role': 'textbox',
-  'aria-describedby': 'editor-help-text',
-};
-
-const toolbarARIA = {
-  'role': 'toolbar',
-  'aria-label': 'Formatting toolbar',
-  'aria-orientation': 'horizontal',
-};
-```
-
-### 15.2 Keyboard Navigation
-
-- **Tab Order**: Logical tab sequence through all interactive elements
-- **Arrow Keys**: Navigate through suggestions and toolbar items
-- **Shortcuts**: Standard keyboard shortcuts for common actions
-- **Focus Management**: Proper focus handling during mode switches
-
-### 15.3 Screen Reader Support
-
-- **Live Regions**: Announce content changes and mode switches
-- **Descriptive Labels**: Clear labels for all interactive elements
-- **Status Updates**: Announce suggestion accept/reject actions
-- **Media Descriptions**: Provide alt text for multimedia content
-
-## 16. Error Handling
-
-### 16.1 Error Types and Handling
-
-```typescript
-enum EditorErrorType {
-  INITIALIZATION_ERROR = 'initialization',
-  CONTENT_PARSE_ERROR = 'content_parse',
-  COLLABORATION_ERROR = 'collaboration',
-  MEDIA_UPLOAD_ERROR = 'media_upload',
-  NETWORK_ERROR = 'network',
-  PERMISSION_ERROR = 'permission',
-}
-
-interface ErrorHandler {
-  type: EditorErrorType;
-  message: string;
-  retry?: () => void;
-  fallback?: () => void;
-}
-```
-
-### 16.2 Error Recovery
-
-- **Graceful Degradation**: Fall back to basic markdown editing if advanced features fail
-- **Retry Mechanisms**: Automatic retry for network-related errors
-- **User Notification**: Clear error messages with actionable solutions
-- **Data Preservation**: Prevent data loss during error scenarios
-
-## 17. Future Enhancements
-
-### 17.1 Planned Features
-
-- **Plugin System**: Allow custom extensions and plugins
-- **Advanced Tables**: Enhanced table editing with spreadsheet-like features
-- **Math Support**: LaTeX math rendering and editing
-- **Comments**: Inline commenting system for collaboration
-- **Version Control**: Git-like version control for documents
-
-### 17.2 Scalability Considerations
-
-- **Cloud Sync**: Integration with cloud storage providers
-- **Offline Support**: Offline editing with sync when reconnected
-- **Mobile Optimization**: Touch-friendly interface for mobile devices
-- **Performance Monitoring**: Built-in performance monitoring and optimization
-
-This specification provides a comprehensive foundation for implementing the Markdown Editor/Viewer component while maintaining consistency with existing codebase patterns and ensuring scalability for future enhancements.