Add VSCode webview state persistence research report

Documents that retainContextWhenHidden is unavailable for WebviewViews
and provides implementation patterns for state management using
getState/setState API.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: nikomatsakis

md/references/vscode-webview-state-persistence.md

@@ -0,0 +1,186 @@
+# VSCode WebviewView State Persistence Research Report
+
+## Executive Summary
+
+This report investigates the challenges and solutions for maintaining state in VSCode sidebar webview panels (WebviewViews) when they are collapsed and recreated. The research reveals that **webview destruction on sidebar collapse is the expected and required behavior**, and that the popular `retainContextWhenHidden` option is **not available for sidebar WebviewViews**, only for editor WebviewPanels. However, several viable state persistence strategies exist to create seamless user experiences.
+
+## Key Findings
+
+### 1. Webview Destruction Behavior Analysis
+
+**Expected Behavior Confirmed**: Webview destruction on sidebar collapse is the intended VSCode architecture, not a bug. When users collapse a sidebar view or switch to another top-level activity, the WebviewView container remains alive, but the underlying webview document is deallocated and recreated upon restoration.
+
+**Architectural Limitation**: This behavior cannot be prevented or modified for WebviewViews, unlike WebviewPanels which support `retainContextWhenHidden`.
+
+### 2. Critical API Limitations Discovered
+
+**retainContextWhenHidden Unavailability**: The most significant finding is that `retainContextWhenHidden` is **exclusively available for WebviewPanel** (editor webviews) and **not supported for WebviewView** (sidebar/panel webviews). Multiple GitHub issues confirm this limitation affects many extension developers.
+
+**Community Impact**: GitHub issues #152110, #149041, and #127006 demonstrate ongoing developer frustration with this limitation, with requests for WebviewView support dating back to 2021.
+
+### 3. Available State Persistence Solutions
+
+#### Primary Recommendation: getState/setState Pattern
+- **Performance**: Significantly lower memory overhead compared to `retainContextWhenHidden`
+- **Reliability**: Officially supported VSCode API with guaranteed persistence
+- **Scope**: Handles JSON-serializable state effectively
+- **Implementation**: Built into webview context via `acquireVsCodeApi()`
+
+#### Secondary Approach: Extension-Side State Management
+- **Use Case**: Complex objects that can't be JSON-serialized
+- **Method**: Message passing between webview and extension
+- **Storage**: ExtensionContext.globalState or in-memory caching
+- **Advantage**: Handles complex UI state and computed data
+
+### 4. Production Extension Analysis
+
+**GitLens Case Study**: Analysis of GitLens extension reveals sophisticated sidebar state management using:
+- Multiple coordinated webview views
+- Drag-and-drop functionality between sidebars
+- Persistent view states across VSCode sessions
+- Integration with external services (GitHub, GitLab, etc.)
+
+**Common Patterns Identified**:
+- Lazy loading strategies to minimize initial render time
+- Progressive enhancement from basic to rich content
+- State partitioning (critical vs. nice-to-have state)
+- Fallback mechanisms for failed state restoration
+
+## Technical Implementation Strategies
+
+### Recommended State Management Architecture
+
+**Layer 1: Basic State (getState/setState)**
+- Scroll positions
+- Active tab/section
+- Search queries
+- Simple form data
+- User preferences
+
+**Layer 2: Complex State (Extension-Side)**
+- Computed data and caches
+- Large datasets
+- External API responses
+- Complex UI component state
+
+**Layer 3: Performance Optimizations**
+- Throttled state saving (scroll events)
+- Debounced state saving (input events)
+- Lazy restoration with loading indicators
+- Virtual scrolling for large datasets
+
+### Best Practices Framework
+
+**State Serialization Strategy**:
+1. **Minimize State Size**: Only persist essential data
+2. **Optimize Frequency**: Balance between responsiveness and performance
+3. **Handle Failures Gracefully**: Always provide fallbacks
+4. **Version State Schema**: Handle backwards compatibility
+
+**Performance Optimization**:
+- Use `requestAnimationFrame` for smooth state restoration
+- Implement content caching to reduce re-rendering time
+- Provide visual feedback during state restoration
+- Optimize for the 80/20 rule (most common use cases)
+
+## Comparative Analysis: WebviewPanel vs WebviewView
+
+| Feature | WebviewPanel (Editor) | WebviewView (Sidebar) |
+|---------|----------------------|----------------------|
+| `retainContextWhenHidden` | ✅ Supported | ❌ Not Supported |
+| `getState/setState` | ✅ Supported | ✅ Supported |
+| Memory Usage | High (when retained) | Low (destroyed/recreated) |
+| Use Case | Rich editors, previews | Navigation, tools, utilities |
+| State Persistence | Optional destruction | Mandatory destruction |
+
+## Challenges and Limitations
+
+### Technical Constraints
+- No access to browser storage APIs (localStorage, sessionStorage)
+- Limited to JSON-serializable data in built-in state management
+- Performance impact of frequent destruction/recreation cycles
+- Complex timing issues during state restoration
+
+### UX Considerations
+- User expectations of persistent state in sidebar panels
+- Brief loading delays during state restoration
+- Potential data loss if state saving fails
+- Balancing performance with state fidelity
+
+## Production Examples and Case Studies
+
+### Successful Implementations
+**GitLens Extension**:
+- Manages multiple sidebar views simultaneously
+- Handles complex Git repository state
+- Integrates with external services
+- Maintains performance with large codebases
+
+**GitHub PR Extensions**:
+- Persists PR review state across sessions
+- Handles authentication tokens securely
+- Manages complex nested UI state
+- Provides offline capability
+
+### Common Anti-Patterns Observed
+- Over-reliance on `retainContextWhenHidden` (when available)
+- Blocking UI during long state restoration
+- Storing non-essential data in persistent state
+- Ignoring state versioning and migration
+
+## Recommendations
+
+### For Extension Developers
+
+**Immediate Actions**:
+1. **Accept the destruction pattern** - Design webviews assuming frequent recreation
+2. **Implement robust getState/setState** - Use for all critical UI state
+3. **Create extension-side state management** - For complex data structures
+4. **Optimize re-rendering performance** - Minimize initial load time
+
+**Long-term Strategy**:
+1. **Design for statelessness** - Minimize persistent state requirements
+2. **Implement progressive enhancement** - Start basic, enhance gradually
+3. **Plan for scale** - Consider performance with large datasets
+4. **Monitor user feedback** - Track state restoration success rates
+
+### For VSCode Team
+
+**Feature Requests** (based on community feedback):
+1. Consider adding `retainContextWhenHidden` support for WebviewView
+2. Provide better state management utilities for complex extensions
+3. Improve documentation around WebviewView limitations
+4. Consider performance optimizations for rapid destruction/recreation cycles
+
+## Conclusion
+
+While the lack of `retainContextWhenHidden` for WebviewViews presents challenges, it's not an insurmountable limitation. The combination of VSCode's built-in state persistence (`getState`/`setState`) and extension-side state management provides powerful tools for creating seamless user experiences.
+
+**Success requires**:
+- Accepting the architectural constraints
+- Implementing comprehensive state serialization
+- Optimizing for performance and user experience
+- Learning from successful production extensions
+
+The most successful extensions treat state persistence as a core architectural concern from the beginning, rather than an afterthought. By following the patterns established by extensions like GitLens and implementing the strategies outlined in this report, developers can create sidebar webviews that feel persistent and responsive despite the underlying destruction/recreation cycle.
+
+## Appendix: Technical Resources
+
+### Key VSCode API Documentation
+- [Webview API Guide](https://code.visualstudio.com/api/extension-guides/webview)
+- [WebviewView Provider](https://code.visualstudio.com/api/references/vscode-api#WebviewViewProvider)
+- [Extension Context](https://code.visualstudio.com/api/references/vscode-api#ExtensionContext)
+
+### Community Resources
+- [VSCode Extension Samples](https://github.com/microsoft/vscode-extension-samples)
+- [WebviewView Sample](https://github.com/microsoft/vscode-extension-samples/tree/main/webview-view-sample)
+- [GitLens Source Code](https://github.com/gitkraken/vscode-gitlens)
+
+### Relevant GitHub Issues
+- [#152110 - WebviewView retainContextWhenHidden](https://github.com/microsoft/vscode/issues/152110)
+- [#149041 - retainContextWhenHidden with when clauses](https://github.com/microsoft/vscode/issues/149041)
+- [#127006 - getState/setState persistence behavior](https://github.com/microsoft/vscode/issues/127006)
+
+---
+
+*Report compiled from analysis of VSCode documentation, GitHub issues, community discussions, and production extension source code. Research conducted August 2025.*