Mountain/Environment/

WebviewProvider.rs

//! # WebviewProvider (Environment)
//!
//! Implements the `WebviewProvider` trait for `MountainEnvironment`, providing
//! the core logic for creating, managing, and securing Webview panels - the
//! embedded browser-based UI components that power many extension features.
//!
//! ## RESPONSIBILITIES
//!
//! ### 1. Webview Panel Creation
//! - Create webview windows with proper configuration
//! - Set up webview content (HTML, CSS, JavaScript)
//! - Configure webview security (CSP, sandbox, permissions)
//! - Initialize webview lifecycle and event handlers
//!
//! ### 2. Webview Management
//! - Track active webview instances in `ApplicationState.Feature.Webviews`
//! - Handle webview focus and visibility changes
//! - Support webview window positioning and sizing
//! - Manage webview disposal and cleanup
//!
//! ### 3. Secure Message Passing
//! - Establish bidirectional IPC between host and webview
//! - Validate and route messages between webview and extension sidecar
//! - Implement message authentication and authorization
//! - Prevent cross-origin security vulnerabilities
//!
//! ### 4. State Persistence
//! - Save webview state (position, size, content) to `ApplicationState`
//! - Restore webview state when reopening
//! - Persist webview settings across sessions
//! - Handle webview state serialization/deserialization
//!
//! ### 5. Content Security
//! - Enforce content security policy (CSP)
//! - Sandbox webview content to prevent escape
//! - Validate webview URLs and origins
//! - Protect against XSS and injection attacks
//!
//! ## ARCHITECTURAL ROLE
//!
//! WebviewProvider is the **webview lifecycle manager**:
//!
//! ```text
//! Extension ──► CreateWebview ──► WebviewProvider ──► Tauri WebviewWindow
//!                     │                              │
//!                     └─► IPC ──► Cocoon ◄───────────┘
//! ```
//!
//! ### Position in Mountain
//! - `Environment` module: Web content capability provider
//! - Implements `CommonLibrary::Webview::WebviewProvider` trait
//! - Accessible via `Environment.Require<dyn WebviewProvider>()`
//!
//! ### Webview Types
//! - **Panel**: Sidebar or panel webview (non-floating)
//! - **Editor**: Webview as custom editor (full editor area)
//! - **Modal**: Modal dialog webview (centered, blocks interaction)
//! - **Widget**: Small embedded webview (e.g., diff viewer)
//!
//! ### Webview Lifecycle
//! 1. **Create**: Extension calls `CreateWebview` with options
//! 2. **Initialize**: Provider builds webview window, sets up event handlers
//! 3. **Load Content**: HTML loaded, scripts execute
//! 4. **Ready**: `onDidBecomeVisible` / `onDidBecomeHidden` events
//! 5. **Dispose**: When closed, cleanup state and resources
//!
//! ### Dependencies
//! - `Tauri`: `WebviewWindowBuilder` for webview creation
//! - `ApplicationState`: Webview state tracking
//! - `IPCProvider`: For extension-side communication
//! - `Log`: Webview lifecycle logging
//!
//! ### Dependents
//! - Extensions: Create webviews via `registerWebviewPanelProvider`
//! - `Binary::Main`: Webview window creation during startup
//! - `DispatchLogic::MountainWebviewPostMessageFromGuest`: Webview → host
//!   messages
//! - UI components: Webview panel management
//!
//! ## WEBVIEW OPTIONS
//!
//! `WebviewContentOptionsDTO` controls webview behavior:
//! - `Handle`: Unique UUID for this webview
//! - `ViewType`: Extension-defined type identifier
//! - `Title`: Panel title
//! - `ContentOptions`: HTML, base URL, scripts, styles
//! - `PanelOptions`: Size, position, enable/disable features
//! - `SideCarIdentifier`: Host extension sidecar
//! - `ExtensionIdentifier`: Owning extension ID
//! - `IsActive`, `IsVisible`: State flags
//!
//! ## SECURITY CONSIDERATIONS
//!
//! - **Content Security Policy**: Default CSP restricts external resources
//! - **Sandbox**: Webview runs in sandboxed process (no Node.js)
//! - **Message Validation**: All postMessage() calls validated
//! - **Origin Checking**: Verify message source matches expected webview
//! - **Permission Management**: Granular permissions for APIs (geolocation,
//!   etc.)
//!
//! ## MESSAGE FLOW
//!
//! 1. Extension → Host: `webview.postMessage({ command: "..." })`
//! 2. Provider receives via `MountainWebviewPostMessageFromGuest` command
//! 3. Provider forwards to extension via IPC (`SendNotificationToSideCar`)
//! 4. Extension processes and responds
//! 5. Host → Extension: `ipc.postMessage({ command: "..." })`
//! 6. Extension receives via `onDidReceiveMessage` event
//!
//! ## PERFORMANCE
//!
//! - Webview creation is relatively expensive (new browser context)
//! - Reuse webviews when possible instead of creating new ones
//! - Consider lazy loading for rarely used webviews
//! - Memory usage: ~50-100MB per webview (depending on content)
//! - Use `Dispose` promptly when webview no longer needed
//!
//! ## ERROR HANDLING
//!
//! - Webview creation failure: `CommonError::WebviewCreationFailed`
//! - IPC communication failure: `CommonError::IPCError`
//! - Invalid webview options: `CommonError::InvalidArgument`
//! - Webview already exists: `CommonError::DuplicateWebview`
//!
//! ## VS CODE REFERENCE
//!
//! Patterns from VS Code:
//! - `vs/workbench/contrib/webview/browser/webviewService.ts` - Webview service
//! - `vs/workbench/contrib/webview/common/webview.ts` - Webview data model
//! - `vs/workbench/api/browser/mainThreadWebview.ts` - Extension API
//!
//! ## TODO
//!
//! - [ ] Implement webview content caching for faster reloads
//! - [ ] Add webview theming support (dark/light mode auto)
//! - [ ] Support webview extensions/plugins (custom protocols)
//! - [ ] Implement webview screenshot and thumbnail generation
//! - [ ] Add webview performance monitoring (CPU, memory)
//! - [ ] Support webview clustering for related views
//! - [ ] Implement webview state snapshots for debugging
//! - [ ] Add webview accessibility audit and reporting
//! - [ ] Support webview pausing (suspend when not visible)
//! - [ ] Implement webview resource preloading strategies
//! - [ ] Add webview telemetry for usage and performance
//! - [ ] Support webview offline mode with service workers
//! - [ ] Implement webview migration across sessions
//! - [ ] Add webview debugging tools integration
//!
//! ## MODULE STRUCTURE
//!
//! - [`lifecycle.rs`](lifecycle.rs) - Webview creation, disposal, reveal
//! - [`configuration.rs`](configuration.rs) - Options and HTML setting
//! - [`messaging.rs`](messaging.rs) - Message passing and listeners

#![allow(non_snake_case)]

use std::collections::HashMap;

use CommonLibrary::{Error::CommonError::CommonError, Webview::WebviewProvider::WebviewProvider};
use async_trait::async_trait;
use serde_json::Value;

use super::MountainEnvironment::MountainEnvironment;

// Atomic public DTOs (one export per file).
pub mod WebviewLifecycleState;
pub mod WebviewMessage;

// Private submodules - implementation only, accessed through the
// trait impl below.
#[path = "WebviewProvider/Configuration.rs"]
mod Configuration;
#[path = "WebviewProvider/Lifecycle.rs"]
mod Lifecycle;
#[path = "WebviewProvider/Messaging.rs"]
mod Messaging;

/// Webview message handler context. Private - only the dispatch
/// machinery in `Messaging.rs` consumes it.
#[allow(dead_code)]
struct WebviewMessageContext {
	Handle:String,
	SideCarIdentifier:Option<String>,
	PendingResponses:HashMap<String, tokio::sync::oneshot::Sender<Value>>,
}

#[async_trait]
impl WebviewProvider for MountainEnvironment {
	/// Creates a new Webview panel with proper security isolation.
	async fn CreateWebviewPanel(
		&self,
		extension_data_value:Value,
		view_type:String,
		title:String,
		_show_options_value:Value,
		panel_options_value:Value,
		content_options_value:Value,
	) -> Result<String, CommonError> {
		Lifecycle::create_webview_panel_impl(
			self,
			extension_data_value,
			view_type,
			title,
			_show_options_value,
			panel_options_value,
			content_options_value,
		)
		.await
	}

	/// Disposes a Webview panel and cleans up all associated resources.
	async fn DisposeWebviewPanel(&self, handle:String) -> Result<(), CommonError> {
		Lifecycle::dispose_webview_panel_impl(self, handle).await
	}

	/// Reveals (shows and focuses) a Webview panel.
	async fn RevealWebviewPanel(&self, handle:String, _show_options_value:Value) -> Result<(), CommonError> {
		Lifecycle::reveal_webview_panel_impl(self, handle, _show_options_value).await
	}

	/// Sets Webview options (title, icon, etc.).
	async fn SetWebviewOptions(&self, handle:String, options_value:Value) -> Result<(), CommonError> {
		Configuration::set_webview_options_impl(self, handle, options_value).await
	}

	/// Sets the HTML content of a Webview.
	async fn SetWebviewHTML(&self, handle:String, html:String) -> Result<(), CommonError> {
		Configuration::set_webview_html_impl(self, handle, html).await
	}

	/// Posts a message to a Webview with proper error handling.
	async fn PostMessageToWebview(&self, handle:String, message:Value) -> Result<bool, CommonError> {
		Messaging::post_message_to_webview_impl(self, handle, message).await
	}
}