zui/PERFORMANCE_IMPROVEMENTS.md

Performance Improvements Plan

1. Executive Summary

This document outlines identified performance bottlenecks in the ZUI application and proposes concrete actions to improve render efficiency, state management, and code splitting. The plan is targeted at enabling junior developers to contribute measurable performance gains while maintaining code quality.

2. Current Performance Issues

Issue	Location	Impact	Root Cause
Large Component Renders	frontend/src/app/canvas/CanvasPage.tsx, frontend/src/app/recollections/RecollectionPage.tsx	High CPU usage, frame drops	These components render thousands of nodes without memoization; state updates trigger full re-renders.
Unmemoized Expensive Calculations	Various utility functions in src/lib/* (e.g., graph layout calculations)	Delayed response to user interactions	Calculations recomputed on every render cycle.
Frequent State Updates	canvasStore mutations in response to mouse/touch events	Unnecessary re-renders of unrelated nodes	State updates not granular; multiple mutations in quick succession.
Lack of Code Splitting	Heavy modules imported globally (e.g., rendering views, graph utilities)	Initial bundle size > 2MB, slow load	All modules loaded upfront even if not used.
Inefficient List Rendering	Lists of nodes in sidebar components	Scrolling lag	No virtualization; all items rendered simultaneously.
Repeated API Calls	Agent service calls without proper caching	Latency spikes	Calls bypass cacheRepository in some paths.

3. Recommended Improvements

3.1 Component Refactoring

• Split CanvasPage and RecollectionPage into smaller, feature‑specific sub‑components.
• Extract pure logic (e.g., node layout calculations) into standalone utility functions with useMemo.
• Apply React.memo to pure presentational components that receive static props.

3.2 State Management Optimization

• Granular State Updates: Use canvasStore selectors to update only the affected node slices.
• Batch Updates: Wrap multiple mutations in runWithTiming or unstable_batchedUpdates to reduce render cycles.

3.3 Memoization & Lazy Loading

• Memoize Callbacks: Replace inline event handlers with useCallback references stored in context or hooks.
• Dynamic Imports: Use import() for heavy modules (e.g., RenderingNode, AnimatedEdge) to split the bundle.
• Virtualized Lists: Integrate react-window or react-virtualized for large node lists in sidebars.

3.4 Code Splitting & Bundle Optimization

• Remove Unused Dependencies: Audit package.json for deprecated libraries.
• Enable vite-plugin-dynamic-import for on‑demand loading of route‑specific components.
• Compress Assets: Configure gzip/brotli in nginx.conf for large SVG and texture assets.

3.5 Caching Strategy Enhancements

• Centralize Caching: Ensure all external API calls route through cacheRepository.
• Add TTL to cached responses to avoid stale data while still reducing repeat calls.

3.6 Testing & Verification

• Performance Tests: Add Vitest benchmarks for render times using performance.now().
• Profile with React DevTools: Capture flame graphs before and after each optimization.
• CI Gate: Enforce that PRs must include a performance regression test if changes affect rendering.

4. Contribution Path for Junior Developers

1. Familiarize with the canvasStore architecture and the CanvasPage component structure.
2. Pick a low‑risk optimization (e.g., memoizing a utility function).
3. Implement the change, add JSDoc comments, and write a simple benchmark.
4. Submit a PR with:
   • Description of the performance gain.
   • Updated tests/benchmarks.
   • Documentation in PERFORMANCE_IMPROVEMENTS.md.

5. Success Metrics

• Target: Reduce average frame time from ~16 ms to < 10 ms for CanvasPage.
• Bundle Size: Decrease initial load by ≥ 15 %.
• API Latency: Cut repeated call overhead by ≥ 30 %.

This plan is living; subsequent sections will track progress and update targets.