VSCode Extension Performance & Stability Improvements

[rocketstack-matt]

Target Project:

calm-plugins/vscode (CALM Preview & Tools VSCode Extension)

Description of Feature:

Performance improvements for the VSCode CALM Preview extension when handling large architecture files (100+ nodes, 500+ relationships). The current implementation suffers from UI freezing, slow rendering, and occasional hangs when opening complex architecture files.

User Stories:

• As an architect, I want to open large architecture files without VSCode freezing so that I can work with enterprise-scale models
• As a developer, I want rapid selection changes to feel responsive so that I can quickly explore the architecture
• As a user, I want clear error messages when diagrams fail to render so that I understand what went wrong and how to fix it
• As an architect with very large models, I want guidance on how to view focused subsets of my architecture so that I can still use the preview feature

Current Limitations:

1. Synchronous file reading blocks the extension host for large files (500+ nodes can take several seconds)
2. No debouncing on docify causes excessive template processing when rapidly changing selections
3. Silent Mermaid failures leave users with blank previews and no indication of what went wrong
4. Mermaid structuredClone errors in strict security mode prevent any diagram rendering in webview
5. No caching of rendered diagrams causes repeated processing of unchanged content
6. Fixed DOM delays use arbitrary timeouts instead of responsive detection
7. Main thread rendering blocks UI during Mermaid diagram generation

Proposed Implementation:

---

High Impact / Low Effort

1. Async File Reading

Location: src/core/services/model-service.ts

• Add readModelAsync() method using fs.promises.readFile()
• Preserve backward-compatible sync readModel() marked as deprecated
• Update preview-panel.ts to use async version

2. Debounced Docify Requests

Location: src/features/preview/docify-tab/view-model/docify.view-model.ts

• Add 300ms debounce using lodash debounce()
• Add requestDocifyImmediate() for cases requiring immediate response
• Proper cleanup in reset() and dispose() methods

3. Mermaid Configuration Fix

Location: src/features/preview/webview/mermaid-renderer.ts

• Change securityLevel from 'strict' to 'loose' to avoid structuredClone errors
• Remove problematic curve configuration that causes cloning issues

4. Improved Error Handling

Location: src/features/preview/webview/mermaid-renderer.ts

• Add createErrorDisplay() method for user-friendly error messages
• Show diagram size and suggestions for large diagrams
• Log warnings in console for diagrams >50KB

---

Medium Impact / Medium Effort

5. Mermaid SVG Caching

Location: src/features/preview/webview/mermaid-renderer.ts

• Implement content hash-based caching for rendered SVGs
• Cache lookup before rendering to avoid reprocessing unchanged diagrams
• Cache invalidation strategy for content changes

6. Progress Indicators

Location: src/features/preview/docify-tab/view/docify-tab.view.ts

• Add loading spinner/progress bar during long operations
• Show estimated time for large diagram rendering
• Allow cancellation of long-running renders

7. MutationObserver for DOM Detection

Location: src/features/preview/docify-tab/view/docify-tab.view.ts

• Replace fixed 150ms setTimeout with MutationObserver
• More responsive pan/zoom initialization
• Reduced perceived latency

---

High Impact / High Effort

8. Web Worker for Mermaid Rendering

Location: src/features/preview/webview/

• Move Mermaid rendering to dedicated Web Worker
• Keep UI thread responsive during large diagram generation
• Message passing for render results and progress updates

9. Incremental/Lazy Rendering

Location: src/features/preview/webview/mermaid-renderer.ts

• Render only visible portions of large diagrams initially
• Load additional sections on scroll/pan
• Virtual scrolling for extremely large architectures

10. Diagram Simplification Mode

Location: src/features/preview/ (multiple files)

• Auto-detect when full diagram exceeds rendering threshold
• Offer simplified view hiding some relationships/details
• User toggle between full and simplified views

---

Alternatives Considered:

1. Web Workers for all processing - Deferred to high-effort category; significant complexity for initial implementation
2. Pagination of large diagrams - Rejected as it breaks the visual continuity of architecture views
3. Server-side rendering - Rejected as it would require additional infrastructure and network dependencies
4. Reducing Mermaid features - Partially adopted (removed curve config) but avoided disabling useful features

Testing Strategy:

Unit Tests

• model-service.spec.ts: Tests for readModelAsync(), readModel(), and filterBySelection()
• docify.view-model.spec.ts: Tests for debounce coalescing and requestDocifyImmediate()
• Update existing tests to account for debounce timing

Manual Testing:

• Test with large architecture files (500+ nodes)
• Verify no UI freezing during file load
• Confirm rapid selection changes don't trigger excessive docify runs
• Verify error messages display correctly for oversized diagrams

Documentation Requirements:

• Create PERFORMANCE_IMPROVEMENTS.md tracking document
• Update README with performance notes for large files
• Add troubleshooting section for common issues

Implementation Checklist:

• Design reviewed and approved
• Implementation completed
• Tests written and passing
• Documentation updated
• Relevant workflows updated (if needed)
• Performance impact assessed