Update README.md of UI/common

Author: woshimajintao

annotation_tool/ui/common/README.md

@@ -1,28 +1,103 @@
 # 🛠️ Common UI Components
 
-This directory contains **shared interface widgets** that are used across multiple modes of the application (both Classification and Localization). 
+This directory contains **shared interface widgets** that are used across all four modes of the application (**Classification, Localization, Description, and Dense Description**).
 
-The goal of this module is to adhere to the **DRY (Don't Repeat Yourself)** principle and ensure a consistent user experience regardless of the active task.
+The goal of this module is to adhere to the **DRY (Don't Repeat Yourself)** principle, ensuring a consistent layout and user experience regardless of the active task.
 
-## 📂 Files
+## 📂 Files & Components
 
-### `project_controls.py`
+### 1. `workspace.py`
+
+* **Class:** `UnifiedTaskPanel`
+* **Purpose:** The fundamental **Skeleton Layout** used by every operating mode.
+* **Structure:** A horizontal layout composed of three distinct sections:
+1. **Left Panel:** Contains the `CommonProjectTreePanel` (Clip Explorer).
+2. **Center Panel:** A stretchable area for the Media Player and Timelines.
+3. **Right Panel:** A task-specific area for Event Editors, Text Inputs, or Class Selectors.
+
+
+* **Usage:** This widget instantiates the Left Panel automatically, while the Center and Right widgets are injected via the constructor.
+
+### 2. `main_window.py`
+
+* **Class:** `MainWindowUI`
+* **Purpose:** The top-level container that orchestrates the **Screen Stack**.
+* **Architecture:** Uses a `QStackedLayout` to switch between views without destroying them.
+* **View Indices:**
+* **Index 0:** Welcome Screen (`WelcomeWidget`)
+* **Index 1:** Classification Workspace
+* **Index 2:** Localization Workspace
+* **Index 3:** Description Workspace (Global Captioning)
+* **Index 4:** **[NEW]** Dense Description Workspace (Timestamped Captioning)
+
+
+
+### 3. `clip_explorer.py`
+
+* **Class:** `CommonProjectTreePanel`
+* **Purpose:** The standardized **Left Sidebar** for file navigation.
+* **Key Features:**
+* **Architecture:** Refactored to use **Qt Model/View** (`QTreeView`) instead of `QTreeWidget` for better performance and separation of data.
+* **Integrated Controls:** Embeds `UnifiedProjectControls` at the top.
+* **Filtering:** Provides a "Show All / Labelled / Unlabelled" filter combo box.
+* **Context Menu:** Supports right-click actions (e.g., "Remove Item").
+
+
+
+### 4. `video_surface.py`
+
+* **Class:** `VideoSurface`
+* **Purpose:** A lightweight, logic-free wrapper for video rendering.
+* **Components:** Encapsulates `QMediaPlayer`, `QAudioOutput` (with volume preset to 100%), and `QVideoWidget`.
+* **Role:** Acts strictly as the **View** layer for media. Playback logic (Play/Pause/Seek) is handled externally by the `MediaController` to prevent audio/visual desync.
+
+### 5. `project_controls.py`
 
 * **Class:** `UnifiedProjectControls`
-* **Purpose:** Provides a standardized **Project Management Panel** to handle the application lifecycle.
-* **Layout:** A 3x2 Grid Layout containing the following essential buttons:
-    * **Row 1:** `New Project`, `Load Project`
-    * **Row 2:** `Add Data`, `Close Project`
-    * **Row 3:** `Save`, `Export`
-
-#### 📡 Signal Interface
-This widget contains **no business logic**. It strictly forwards user interactions to the Controllers via Qt Signals:
-
-| Signal | Description |
-| :--- | :--- |
-| `createRequested` | Triggered when "New Project" is clicked. |
-| `loadRequested` | Triggered when "Load Project" is clicked. |
-| `addVideoRequested`| Triggered when "Add Data" is clicked. |
-| `closeRequested` | Triggered when "Close Project" is clicked. |
-| `saveRequested` | Triggered when "Save" is clicked. |
-| `exportRequested` | Triggered when "Export" is clicked. |
+* **Purpose:** A standardized 3x2 **Project Management Grid**.
+* **Layout:**
+* **Row 1:** `New Project`, `Load Project`
+* **Row 2:** `Add Data`, `Close Project`
+* **Row 3:** `Save JSON`, `Export JSON`
+
+
+* **Signals:** Emits signals (`createRequested`, `saveRequested`, etc.) to be caught by the main Controller, keeping this widget purely presentational.
+
+### 6. `dialogs.py`
+
+* **Classes:**
+* `ProjectTypeDialog`: The "New Project" wizard. Now updated to support **4 Modes**: Classification, Localization, Description, and **Dense Description**.
+* `FolderPickerDialog`: A custom file dialog allowing **Multi-Folder Selection** via a `QTreeView` with checkboxes/click-toggle.
+
+
+
+### 7. `welcome_widget.py`
+
+* **Class:** `WelcomeWidget`
+* **Purpose:** The landing screen displayed on application startup.
+* **Actions:** Provides large, accessible entry points to "Create New Project" or "Import Project JSON".
+
+---
+
+## 🧩 Architectural Diagram (UI Composition)
+
+The `MainWindowUI` builds the application by injecting specific widgets into the `UnifiedTaskPanel` skeleton:
+
+```mermaid
+graph TD
+    MW[MainWindowUI] --> Stack[QStackedLayout]
+    
+    Stack --> View1[Classification Mode]
+    Stack --> View2[Localization Mode]
+    Stack --> View3[Description Mode]
+    Stack --> View4[Dense Description Mode]
+    
+    subgraph "UnifiedTaskPanel (Shared Skeleton)"
+        Left[CommonProjectTreePanel]
+        Center[Media Player / Timeline]
+        Right[Task Specific Editor]
+    end
+    
+    View4 --> Left
+    View4 --> Center
+    View4 --> Right