Notes for Reviewers

This PR addresses a significant documentation gap by adding comprehensive, user-facing performance guidance to help Kanvas users understand performance limits, what affects performance, and how to control performance through functionality tradeoffs.

Description

Added seven major sections to /content/en/kanvas/advanced/performance/index.md with user-centric content:

User-Facing Performance Guidance

• What Affects Performance: Explains how grouped components impact responsiveness, symptoms users experience (lag, slow loading, choppy interactions), and automatic optimizations Kanvas provides. Includes user experience improvement table showing 90% performance gains.

• Managing Design Complexity: Describes interactive features (alignment guides, relationship management, tooltips, resize handles) and their performance impact. Provides practical tips for handling slowness through the Layers panel, design organization, and workflow strategies.

• How Kanvas Keeps Things Fast: Explains automatic performance optimizations using relatable analogies (word processor example). Focuses on benefits users experience: quick responses, smooth interactions, and consistent performance.

• Working with Different Zoom Levels: Describes three zoom modes (Overview, Working, Detail) and how Kanvas progressively shows more or less detail based on zoom level. Provides strategic guidance on using zoom for better performance.

Testing & Optimization

• Testing Your Design's Performance: Practical test scenarios (small/medium/large designs, complex nesting) with simple responsiveness checks. Replaces technical metrics with user-relatable questions like "does dragging feel smooth?"

• Future Improvements: Brief description of ongoing performance optimization work without technical implementation details.

• Special URL Options for Performance: Documents render=full parameter with clear "When to Use / When NOT to Use" guidance and practical microservices example showing the performance/features tradeoff.

All sections use conversational language, practical examples, and actionable advice. Technical jargon, plugin names, internal metrics, and PR references have been removed to focus on what users can understand and control.

Signed commits

• Yes, I signed my commits.

This pull request was created as a result of the following prompt from Copilot chat.

Overview

The Kanvas performance documentation at content/en/kanvas/advanced/performance/index.md needs to be significantly expanded to include detailed performance analysis, optimization techniques, and best practices gathered from extensive development work documented in the layer5labs/meshery-extensions repository.

Context

The layer5labs/meshery-extensions repository contains detailed performance analysis and optimizations in issues and pull requests that have not been publicly documented. This information is valuable for users and developers working with Kanvas.

Current Documentation Gap

The existing performance documentation covers:

• Maximum component limits (1,000 per design)
• Layers panel optimization
• Basic image optimization guidance

Content to Add

1. Compound Node Rendering Performance

Source: PR #3917, Issue #3916

Add a new section documenting:

Root Cause Analysis:

• The @layer5/cytoscape-node-html-label plugin is a primary performance bottleneck for compound nodes with many children
• Badge selector node[?label] matches virtually every node
• No viewport culling (rendered off-screen badges)
• With 100 child nodes: 303 badge re-renders per update
• During drag operations: 18,000-36,000 function calls per second

Performance Metrics:

Scenario	Before Optimization	After Optimization
Badge re-renders per update (100 children)	303	~30
Function calls/sec during drag	18,000-36,000	500-3,000
Overall improvement	Baseline	90-95% reduction

Optimizations Implemented:

1. Viewport Culling (50-80% reduction): Only render badges for visible nodes
2. Increased Memoization TTL (70% reduction): Error badges: 300ms→1000ms, Compound badges: 200ms→1000ms
3. Combined Impact: 90-95% reduction in badge re-renders

2. Cytoscape Plugin Performance Considerations

Sources: Multiple PRs including #3885, #3887, #3500

Document the following plugin performance considerations:

• Compound drag-and-drop plugin: Performance may degrade for large graphs (from plugin's own README)
• Event cascade: Multiple plugins (Grid Guide, Automove, Popper) listening to same events creates multiplication effect
• HTML plugin overhead: Migrate to 2D canvas renderer for better performance (resize handles, overlays)
• Bubblesets optimization: Improved performance in complex designs

3. State Management and Rendering Optimizations

Sources: PR #3448, PR #3595, PR #3121, PR #3114

Add guidance on:

• Fine-grained reactivity: Use fine-grained state updates instead of JSON snapshots (expensive to compute)
• Render throttling: Lockdown re-renders to max 10 per second during continuous operations
• Selector optimization: Optimize selectors for sharedState snapshots
• Evaluation deferral: Skip feasibility evaluation on tap, double-click events

4. Zoom and Viewport Performance

Sources: PR #3528, PR #3711, PR #2292

Document:

• Minimum zoom viewport: Consistent minimum zoom for detailed rendering across layers, badges, textboxes, interactions, and devices
• View filtering based on zoom: Progressive detail rendering at different zoom levels
• Zoom rendering consistency: Fix zoom rendering discrepancies

5. Performance Testing Guidelines

Add a section on testing performance with:

Test Scenarios:

• 1 parent + 10 children (baseline)
• 1 parent + 50 children (medium)
• 1 parent + 100 children (large)
• 3 levels nested (stress test)

Target Metrics:

• FPS during drag: 60 FPS (acceptable: 30 FPS)
• Time to first badge render: < 100ms
• Badge re-renders per drag operation: < 1,000

6. Long-term Architecture Recommendations

Document future optimization paths:

• Canvas-based badges: 10-100x performance improvement over DOM-based
• Virtual badge manager: Only render visible badges
• Web Worker rendering: Offload badge generation to background thread
• Progressive rendering: Render critical badges first, defer others

7. URL Parameters for Performance

Link to the existing URL parameters documentation and add performance-related parameters:

• render_full_design=true: Force complete design render including advanced relationships like tagsets
• Reference viewport parameters for sharing designs with specific zoom/pan states

File Changes Required

1. Update content/en/kanvas/advanced/performance/index.md with all the above content
2. Add any necessary images/diagrams to illustrate performance concepts
3. Cross-reference to URL parameters documentation at /kanvas/advanced/url-parameters/

Acceptance Criteria

• Document compound node performance analysis with root causes and solutions
• Include performance metrics tables showing before/after optimization results
• Document Cytoscape plugin performance considerations
• Add state management and rendering optimization guidance
• Include performance testing guidelines with test scenarios and target metrics
• Document long-term architecture recommendations
• Ensure proper cross-linking to related documentation
• Follow existing documentation style and Hugo/Docsy conventions
• Include appropriate alerts/callouts for important information

References

• Issue #3916: Compound Node Rendering Performance Analysis
• PR #3917: Compound Node Rendering Performance Analysis and Optimization
• PR #3885: Optimize resize handles and migrate to 2dcanvas renderer
• PR #3887: Optimize overlay image rendering
• PR #3595: Performance optimizations and bug fixes
• PR #3497: Performance optimizations
• PR #3486: Optimize Component Editing Tooltip Performance
• PR #3448: Store/Statemanagement performance optimizations
• PR #3434: Performance Optimizations
• PR #3431: Performance optimizations
• PR #3114: Performance Optimizations
• PR #3121: Optimize rendering - lockdown rerenders to 10 per sec
• PR #3500: Optimize bubblesets
• PR #3528: Make min zoom viewport for detailed rendering consistent

See full list at: https://github.com/layer5labs/meshery-extensions/issues?q=is%3Apr+performance+OR+optimization+OR+rendering

Note: The search returned 268 total results related to performance. This documentation update captures the most significant findings.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.