add blueprints

2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
--- a/docs/blueprints/06-ui/44_SS_UIManager.md
+++ b/docs/blueprints/06-ui/44_SS_UIManager.md
@@ -0,0 +1,116 @@
+# SS_UIManager — Game Instance Subsystem
+
+**Parent Class:** `UGameInstanceSubsystem`
+**Dependencies:** [`GI_GameFramework`](../01-core/04_GI_GameFramework.md)
+**File:** `SS_UIManager`
+
+---
+
+## Purpose
+
+The central UI orchestration subsystem. Owns all full-screen menu widgets (MainMenu, PauseMenu, Settings, Inventory, Journal) and manages their visibility, stacking, and transitions. In-world HUD widgets are owned by [`WBP_HUD`](33_WBP_HUD.md) directly.
+
+---
+
+## Responsibilities
+
+- Create and cache all full-screen menu widget instances on subsystem Init
+- Manage a navigation stack (MenuStack) for push/pop/replace menu transitions
+- React to `E_GamePhase` changes from [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) to auto-show/hide menus
+- Provide a static-style accessor pattern via [`FL_GameUtilities`](../01-core/02_FL_GameUtilities.md)`::GetUIManager`
+- Route input mode changes (GameOnly → UIOnly → GameAndUI) when menus open/close
+- Broadcast menu open/close events for other systems to react
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `MenuWidgets` | Map (`E_MenuType` → Widget) | Cached instances of all menu widgets |
+| `MenuStack` | Array of `E_MenuType` | Navigation history for back-stack |
+| `ActiveMenu` | `E_MenuType` | Currently visible full-screen menu (None = HUD only) |
+| `bInputModeUI` | Bool | Are we in UI-only input mode |
+| `HUDWidget` | `WBP_HUD` | Reference to root HUD (created separately) |
+
+---
+
+## Enums
+
+### `E_MenuType`
+
+| Value | Description |
+|-------|-------------|
+| `None` | No menu active (game view) |
+| `MainMenu` | Title screen |
+| `PauseMenu` | In-game pause |
+| `SettingsMenu` | Audio/Graphics/Controls/Accessibility |
+| `InventoryMenu` | Full inventory screen |
+| `JournalMenu` | Journal and documents viewer |
+| `SaveLoadMenu` | Save/load slot selection |
+| `LoadGameMenu` | Load from title screen |
+| `DialogueMenu` | Dialogue choice UI |
+| `ContainerMenu` | Container search/loot UI |
+| `DeathScreen` | Game over / death screen |
+
+---
+
+## Functions / Events
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Initialize` | — | — | On subsystem init; creates all cached menu widgets (not visible) |
+| `ShowMenu` | MenuType: `E_MenuType` | — | Shows a menu, pushes previous menu to stack, updates input mode |
+| `HideMenu` | — | — | Hides current menu, pops stack, restores input mode |
+| `PushMenu` | MenuType: `E_MenuType` | — | Pushes menu, stores current on stack (for sub-menus) |
+| `PopMenu` | — | — | Returns to previous menu from stack |
+| `ReplaceMenu` | MenuType: `E_MenuType` | — | Replaces current menu without stack history |
+| `ClearToHUD` | — | — | Empties stack, hides all menus, shows HUD only |
+| `IsMenuOpen` | MenuType | Bool | Checks if a specific menu is currently shown |
+| `GetTopMenu` | — | `E_MenuType` | Returns current top of stack |
+| `SetInputModeUI` | bUIOnly: Bool | — | Switches between GameOnly and GameAndUI input modes |
+| `GetHUD` | — | `WBP_HUD` | Returns root HUD reference |
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnMenuOpened` | MenuType: `E_MenuType` | Any menu becomes visible |
+| `OnMenuClosed` | MenuType: `E_MenuType` | Any menu is hidden |
+| `OnInputModeChanged` | bUIOnly: Bool | Input mode switches |
+
+---
+
+## Blueprint Flow — ShowMenu Logic
+
+```mermaid
+flowchart TD
+    A[ShowMenu Called] --> B{Menu already visible?}
+    B -->|Yes| C[Do nothing / return]
+    B -->|No| D[Push current ActiveMenu to MenuStack]
+    D --> E[Set ActiveMenu = NewMenuType]
+    E --> F[Create widget if not cached]
+    F --> G[Add to viewport]
+    G --> H[Set input mode to UIOnly]
+    H --> I[Broadcast OnMenuOpened]
+    I --> J[Pause game if MenuType is pause-capable?]
+```
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | Dispatcher (`OnGamePhaseChanged`) | Auto-hide menus during cutscenes/loading |
+| [`WBP_HUD`](33_WBP_HUD.md) | Direct reference | Controlled hide/show alongside menus |
+| [`PC_CoreController`](../02-player/) | Direct | Input mode changes routed through controller |
+| All menu widgets | Direct (cached references) | Show/hide/set data |
+
+---
+
+## Reuse Notes
+
+This subsystem is project-agnostic. Add new `E_MenuType` values per project. The widget caching pattern prevents repeated construction. The stack-based navigation handles any menu depth.
--- a/docs/blueprints/06-ui/45_WBP_AccessibilityUI.md
+++ b/docs/blueprints/06-ui/45_WBP_AccessibilityUI.md
@@ -0,0 +1,141 @@
+# WBP_AccessibilityUI — Widget (Subtitle Display, Accessibility Overlays)
+
+**Parent Class:** `UUserWidget` (created via Widget Blueprint)
+**Dependencies:** `BPC_DialoguePlaybackSystem`, `BPC_NarrativeStateSystem`, `SS_SettingsSystem`
+**File:** `WBP_AccessibilityUI`
+
+---
+
+## Purpose
+
+Provides subtitle rendering, speaking-name display, subtitle background styling, and accessibility-focused UI overlays (high-contrast mode, colorblind filters, font scaling). Listens to dialogue events from `BPC_DialoguePlaybackSystem` and settings changes from `SS_SettingsSystem`.
+
+---
+
+## Responsibilities
+
+- Display subtitles at the bottom-center of the screen with speaker name, dialogue text, and optional background
+- Support multi-line subtitle display with timed progression
+- Display speaker name above the subtitle text (optional per settings)
+- React to accessibility settings: font size scaling, background opacity, colorblind mode, high-contrast mode
+- Fade subtitles in/out on line start/end
+- Queue subtitle lines if multiple fire rapidly
+- Handle subtitle grouping: one line at a time per speaker, multi-speaker stacking
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `SubtitleContainer` | `VerticalBox` | Vertical stack for active subtitle lines |
+| `SpeakerNameText` | `TextBlock` | Current speaker's display name |
+| `SubtitleText` | `TextBlock` | Current subtitle line text |
+| `SubtitleBackground` | `Image` or `Border` | Background behind subtitle text |
+| `AnimSubtitleIn` | `WidgetAnimation` | Fade in subtitle |
+| `AnimSubtitleOut` | `WidgetAnimation` | Fade out subtitle |
+| `ActiveSubtitles` | Array of `FSubtitleLine` | Currently displayed subtitle lines |
+| `SubtitleQueue` | Array of `FSubtitleLine` | Queue if multiple lines arrive simultaneously |
+| `bSubtitlesEnabled` | Bool | From settings |
+| `SubtitleFontScale` | Float | 0.8, 1.0, 1.2, 1.5 from settings |
+| `SubtitleBackgroundOpacity` | Float | 0.0 to 1.0 from settings |
+| `bHighContrastMode` | Bool | From settings |
+| `bIsCurrentlySpeaking` | Bool | Prevents flicker between rapid lines |
+
+---
+
+## Structs
+
+```cpp
+FSubtitleLine
+{
+    FText SpeakerName;      // "Dr. Hartmann"
+    FText LineText;         // "The tumor is benign..."
+    float Duration;          // seconds, from dialogue data
+    float StartTime;         // world time when line started
+    bool bIsFinalLine;       // if true, marks end of dialogue sequence
+    FColor SpeakerColor;     // optional per-speaker color
+}
+```
+
+---
+
+## Functions / Events
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Construct` | — | — | Bind to dialogue dispatchers, load accessibility settings |
+| `OnDialogueLineStarted` | Data: `FSubtitleLine` | — | Add subtitle to display, start fade-in timer |
+| `OnDialogueLineComplete` | Data: `FSubtitleLine` | — | Start fade-out, remove from active list after animation |
+| `OnDialogueSequenceEnded` | — | — | Clear all subtitles, fade out |
+| `DisplaySubtitle` | Line: `FSubtitleLine` | — | Set speaker name, text, background; play AnimSubtitleIn |
+| `HideSubtitle` | Line: `FSubtitleLine` | — | Play AnimSubtitleOut, remove from container |
+| `SetSubtitlesEnabled` | bEnabled: Bool | — | Show/hide subtitle container |
+| `ApplyFontScale` | Scale: Float | — | Set subtitle text font size (scalar) |
+| `SetBackgroundOpacity` | Opacity: Float | — | Set subtitle background render opacity |
+| `ApplyHighContrastMode` | bEnabled: Bool | — | Toggle high-contrast subtitle background/text colors |
+| `OnAccessibilitySettingsChanged` | Settings: `S_AccessibilitySettings` | — | Apply all accessibility settings at once |
+| `ClearAllSubtitles` | — | — | Remove all active subtitles immediately |
+
+---
+
+## Blueprint Flow — Subtitle Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Dialogue as BPC_DialoguePlaybackSystem
+    participant Sub as WBP_AccessibilityUI
+    participant Timer as Internal Timer
+
+    Dialogue->>Sub: OnDialogueLineStarted LineData
+    Sub->>Sub: DisplaySubtitle LineData
+    Sub->>Sub: Set SpeakerNameText, SubtitleText
+    Sub->>Sub: PlayAnimation FadeIn
+    Sub->>Timer: SetTimer by LineData.Duration
+    Timer-->>Sub: Timer expired
+    Sub->>Sub: PlayAnimation FadeOut
+    Sub->>Sub: OnDialogueLineComplete LineData
+    Dialogue->>Sub: OnDialogueSequenceEnded
+    Sub->>Sub: ClearAllSubtitles
+```
+
+---
+
+## Accessibility Settings Consumption
+
+```mermaid
+flowchart LR
+    A[SS_SettingsSystem] -->|Read on Construct| B[Cache settings]
+    B --> C[SetSubtitlesEnabled]
+    B --> D[ApplyFontScale]
+    B --> E[SetBackgroundOpacity]
+    B --> F[ApplyHighContrastMode]
+    A -->|OnAccessibilitySettingsChanged dispatcher| G[Re-apply all]
+```
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnSubtitleStarted` | Line: `FSubtitleLine` | A new subtitle line appears |
+| `OnSubtitleEnded` | Line: `FSubtitleLine` | A subtitle line ends |
+| `OnAllSubtitlesCleared` | — | All subtitles removed |
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`BPC_DialoguePlaybackSystem`](../07-narrative/) | Dispatchers (`OnLineStarted`, `OnLineComplete`, `OnSequenceEnded`) | Receive subtitle data |
+| [`SS_SettingsSystem`] | Direct reads, dispatcher on settings changed | Apply accessibility preferences |
+| [`WBP_HUD`](33_WBP_HUD.md) | Parent reference | Positioning within HUD canvas |
+| [`BPC_NarrativeStateSystem`] | Query | Speaker display name overrides |
+
+---
+
+## Reuse Notes
+
+The subtitle display widget is purely reactive — it never fetches or filters dialogue data. It can be embedded in any HUD canvas (first-person, third-person, diegetic screen overlay). The `FSubtitleLine` struct is intentionally compatible with the `DA_DialogueSequence` line format. If no speaker name is provided, the `SpeakerNameText` collapses and the subtitle text fills the full width. High-contrast mode inverts colors for readability against any background.
--- a/docs/blueprints/06-ui/46_WBP_DiegeticHUDFrame.md
+++ b/docs/blueprints/06-ui/46_WBP_DiegeticHUDFrame.md
@@ -0,0 +1,89 @@
+# WBP_DiegeticHUDFrame — Widget (Diegetic HUD Skin Container)
+
+**File:** [`Content/Framework/UI/WBP_DiegeticHUDFrame`](Content/Framework/UI/WBP_DiegeticHUDFrame.uasset)
+**Parent Class:** `UUserWidget`
+**Dependencies:** [`I_DiegeticDisplay`](../01-core/03_I_InterfaceLibrary.md), [`WBP_HUDController`](WBP_HUDController.md), all player state component dispatchers
+
+**Purpose:** The swappable container for the game's diegetic HUD presentation. This is the "skin" that changes per project — wristwatch, visor, bracelet, handheld device, etc. All data displayed here comes from system dispatchers; it contains zero game logic.
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `HealthIndicator` | Widget | Child widget showing health (bar, number, pulse) |
+| `StressIndicator` | Widget | Child widget showing stress tier |
+| `StaminaBar` | Widget | Optional stamina display |
+| `CompassWidget` | Widget | Optional directional compass |
+| `ActiveItemWidget` | Widget | Currently held item icon and name |
+| `TimeDisplay` | TextBlock | In-game world time or session timer |
+| `ObjectivePreview` | TextBlock | Single-line current objective snippet |
+| `bAnimatedEntries` | Bool | Whether values animate in/out with lerp |
+| `PresentationSkin` | E_DiegeticSkin | Current visual skin (watch, visor, handheld) |
+
+## Enums
+
+```cpp
+E_DiegeticSkin
+{
+    Wristwatch,
+    VisorHUDSuit,
+    HandheldDevice,
+    BraceletCharm,
+    DiegeticSignage,
+    CustomProjectSkin
+}
+```
+
+## Functions / Events
+
+| Name | Inputs | Outputs | What it does |
+|------|--------|---------|--------------|
+| `SetDiegeticValue` | Tag: GameplayTag, Value: Float/Text | — | Implements `I_DiegeticDisplay`. Routes to correct child widget |
+| `RefreshDisplay` | — | — | Implements `I_DiegeticDisplay`. Force-refreshes all children |
+| `SetSkin` | Skin: E_DiegeticSkin | — | Swaps visual presentation without changing data bindings |
+| `SetAnimatedEntries` | bAnimated: Bool | — | Toggle value animation lerp |
+| `UpdateHealth` | NormalisedValue: Float | — | Bound to BPC_HealthSystem dispatcher |
+| `UpdateStress` | Tier: E_StressTier, Value: Float | — | Bound to BPC_StressSystem dispatcher |
+| `UpdateStamina` | NormalisedValue: Float | — | Bound to BPC_StaminaSystem dispatcher |
+| `UpdateActiveItem` | ItemTag: GameplayTag, DisplayName: FText | — | Bound to BPC_ActiveItemSystem dispatcher |
+| `UpdateObjective` | ObjectiveText: FText | — | Bound to BPC_ObjectiveSystem dispatcher |
+| `ShowHUD` | — | — | Animate all elements in |
+| `HideHUD` | — | — | Animate all elements out |
+
+## Blueprint Flow Diagram
+
+```mermaid
+flowchart TD
+    A[WBP_HUDController creates WBP_DiegeticHUDFrame] --> B[bAnimatedEntries = Settings value]
+    B --> C[Bind to player component dispatchers]
+    C --> D[Wait for game phase = InGame]
+    D --> E[ShowHUD - animate all elements in]
+
+    F[Health changed] --> G[UpdateHealth - lerp HealthIndicator]
+    H[Stress changed] --> I[UpdateStress - update StressIndicator]
+    J[Item equipped] --> K[UpdateActiveItem - show icon + name]
+
+    L[Game phase changes to Cutscene] --> M[HideHUD]
+    N[Game phase returns to InGame] --> E
+```
+
+## Communications With
+
+| Target System | Method | Why |
+|---------------|--------|-----|
+| `WBP_HUDController` | Parent reference | Visibility control via game phase |
+| `BPC_HealthSystem` | Dispatcher `OnHealthChanged` | Health display |
+| `BPC_StressSystem` | Dispatcher `OnStressTierChanged` | Stress display |
+| `BPC_StaminaSystem` | Dispatcher `OnStaminaChanged` | Stamina display |
+| `BPC_ActiveItemSystem` | Dispatcher | Active hand item display |
+| `BPC_ObjectiveSystem` | Dispatcher `OnObjectiveActivated` | Objective preview |
+| `SS_SettingsSystem` | Direct read | Animated entries preference |
+
+## Reuse Notes
+
+- For a sci-fi game, create `WBP_DiegeticHUD_VisorSkin`. For period horror, create `WBP_DiegeticHUD_WatchSkin`. Only the art/layout changes — all data bindings use the same `I_DiegeticDisplay` interface.
+- The `E_DiegeticSkin` enum can be extended per project without modifying this widget's logic.
+- This widget implements `I_DiegeticDisplay` so external systems can push data without knowing which skin is active.
+- All child widgets are created in `NativeConstruct` and bound to dispatchers there.
--- a/docs/blueprints/06-ui/47_WBP_HUDController.md
+++ b/docs/blueprints/06-ui/47_WBP_HUDController.md
@@ -0,0 +1,114 @@
+# WBP_HUDController — Widget (Root HUD)
+
+**Parent Class:** `UUserWidget` (created via HUD Blueprint)
+**Dependencies:** `SS_UIManager`, `BPC_InteractionDetector`, `BPC_HealthSystem`, `BPC_StressSystem`, `BPC_StaminaSystem`, `BPC_NarrativeStateSystem`, `BPC_ObjectiveSystem`, `BPC_DialoguePlaybackSystem`
+**File:** `WBP_HUDController`
+
+---
+
+## Purpose
+
+The master HUD container. Owns all in-world HUD sub-widgets and manages their visibility based on game phase and player state. Does NOT own full-screen menus — those are managed by `SS_UIManager`.
+
+---
+
+## Responsibilities
+
+- Create and manage all HUD sub-widgets (diegetic display, interaction prompt, subtitles, notifications, objective overlay, screen effects)
+- React to `E_GamePhase` changes (hide HUD during cutscenes, show during play)
+- Route visibility of individual HUD elements via gameplay tags
+- Never display raw data — always delegates to child widgets
+- Handle fade-to-black transitions for death/loading
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `DiegeticHUDWidget` | `WBP_DiegeticHUDFrame` | The diegetic UI element (watch/visor/etc) |
+| `InteractionPromptWidget` | `WBP_InteractionPromptDisplay` | Interaction cues |
+| `SubtitleWidget` | `WBP_SubtitleDisplay` | Dialogue/event subtitles |
+| `NotificationWidget` | `WBP_NotificationToast` | Toast messages |
+| `ObjectiveWidget` | `WBP_ObjectiveDisplay` | Objective overlay |
+| `ScreenEffectWidget` | `WBP_ScreenEffectController` | Full-screen effects |
+| `MinimapWidget` | Widget | Optional minimap/compass |
+| `bHUDVisible` | Bool | Master visibility flag |
+| `FadeWidget` | Image | Black full-screen image for fades |
+
+---
+
+## Sub-Widget Class References
+
+| Variable Name | Default Class |
+|--------------|---------------|
+| `DiegeticHUDClass` | `WBP_DiegeticHUDFrame` (subclass per project) |
+| `InteractionPromptClass` | `WBP_InteractionPromptDisplay` |
+| `SubtitleClass` | `WBP_SubtitleDisplay` |
+| `NotificationClass` | `WBP_NotificationToast` |
+| `ObjectiveClass` | `WBP_ObjectiveDisplay` |
+| `ScreenEffectClass` | `WBP_ScreenEffectController` |
+
+---
+
+## Functions / Events
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `ConstructChildren` | — | — | Spawns all sub-widgets, adds as children |
+| `SetHUDVisibility` | bVisible: Bool | — | Master show/hide (for cutscenes) |
+| `FadeToBlack` | Duration: Float | — | Lerps FadeWidget opacity to 1 |
+| `FadeFromBlack` | Duration: Float | — | Lerps FadeWidget opacity to 0 |
+| `TriggerDamageVignette` | Intensity: Float | — | Calls ScreenEffectWidget.TriggerDamageFlash |
+| `TriggerJumpScareFlash` | — | — | Calls ScreenEffectWidget.TriggerJumpScareFlash |
+| `SetStressDistortion` | Amount: Float | — | Routes to ScreenEffectWidget |
+| `OnPhaseChanged` | NewPhase: `E_GamePhase` | — | Listen from GI_GameFramework; hide/show HUD |
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnHUDHidden` | — | HUD hidden (cutscene/loading) |
+| `OnHUDShown` | — | HUD restored |
+| `OnFadeComplete` | bFadedIn: Bool | Fade animation completes |
+
+---
+
+## Blueprint Flow — Phase Change Reaction
+
+```mermaid
+flowchart TD
+    A[OnPhaseChanged received] --> B{NewPhase}
+    B -->|InGame| C[SetHUDVisibility true]
+    B -->|Cutscene| D[SetHUDVisibility false]
+    B -->|Loading| E[FadeToBlack 0.5s]
+    B -->|DeathLoop| F[FadeToBlack 1.0s]
+    B -->|AltDeathSpace| G[Hide interaction prompt only]
+    B -->|Paused| H[Keep HUD but hide diegetic]
+    B -->|MainMenu / Credits| I[Destroy HUD entirely]
+```
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`SS_UIManager`](44_SS_UIManager.md) | Direct reference | Coordination with menus |
+| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | Dispatcher (`OnGamePhaseChanged`) | Phase-based visibility |
+| [`BPC_InteractionDetector`](../03-interaction/16_BPC_InteractionDetector.md) | Dispatcher (`OnFocusGained`, `OnFocusLost`) | Show/hide interaction prompt |
+| [`BPC_DialoguePlaybackSystem`](../07-narrative/) | Dispatcher (`OnLineStarted`, `OnLineComplete`) | Subtitle routing |
+| [`BPC_ObjectiveSystem`](../07-narrative/) | Dispatcher (`OnObjectiveActivated`, `OnObjectiveCompleted`) | Objective overlay updates |
+| [`BPC_HealthSystem`](../02-player/08_BPC_HealthSystem.md) | Dispatcher (`OnHealthChanged`, `OnHealthCritical`) | Damage vignette |
+| [`BPC_StressSystem`](../02-player/10_BPC_StressSystem.md) | Dispatcher (`OnStressTierChanged`) | Stress distortion |
+| [`BPC_NotificationSystem`] | Dispatcher | Toast messages |
+
+---
+
+## Reuse Notes
+
+The HUD class references are configurable so each project can override `DiegeticHUDClass` with a themed skin (watch, visor, bracelet, etc.) without modifying any logic. The fade system is used by death handling, chapter transitions, and loading screens interchangeably.
+
+- Renamed from `WBP_HUD` to `WBP_HUDController` per Master naming convention.
--- a/docs/blueprints/06-ui/48_WBP_InteractionPromptDisplay.md
+++ b/docs/blueprints/06-ui/48_WBP_InteractionPromptDisplay.md
@@ -0,0 +1,135 @@
+# WBP_InteractionPromptDisplay — Widget (Interaction Prompt Display)
+
+**Parent Class:** `UUserWidget` (created via Widget Blueprint)
+**Dependencies:** `BPC_InteractionDetector`, `I_Interactable`
+**File:** `WBP_InteractionPromptDisplay`
+
+---
+
+## Purpose
+
+Displays a context-sensitive interaction prompt at the center of the screen (or offset near the interactable world-location). Shows the interaction action name, hold-to-interact progress bar, and platform-specific input key icon.
+
+---
+
+## Responsibilities
+
+- Listen to `BPC_InteractionDetector.OnFocusGained` and `OnFocusLost` dispatchers
+- When focus gained: fade in prompt text ("Press E to Open", "Hold F to Pull Lever")
+- When hold interaction required: display a circular progress fill ring around the prompt
+- When focus lost: fade out prompt immediately or animate out
+- Display _context tags_ from the interactable (e.g. [Safe], [Dangerous], [Locked])
+- Avoid overlapping with other HUD elements — offset from world-location if `bUseWorldOffset` is true
+- Support a "look-at" mode (interaction prompt tracks the world location of the interactable)
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `OwningDetector` | `BPC_InteractionDetector` | Cached reference (set on Construct) |
+| `CurrentInteractable` | `I_Interactable` | Object currently in focus |
+| `PromptText` | `TextBlock` | "Open Door", "Pick Up Note", etc. |
+| `ActionKeyIcon` | `Image` | Platform-specific key icon |
+| `HoldProgressRing` | `Image` | Circular fill ring for hold interactions |
+| `ContextTagsContainer` | `HorizontalBox` | Row of context tag labels |
+| `bIsVisible` | Bool | Current visibility state |
+| `bUseWorldOffset` | Bool | If true, offset prompt to world location |
+| `AnimFadeIn` | `WidgetAnimation` | Fade in animation |
+| `AnimFadeOut` | `WidgetAnimation` | Fade out animation |
+| `AnimHoldProgress` | `WidgetAnimation` | Hold fill progress animation |
+| `PromptYOffset` | Float | Vertical offset from screen center (pixels) |
+
+---
+
+## Functions / Events
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Construct` | — | — | Cache detector, bind dispatchers, set to hidden |
+| `OnInteractionFocusGained` | Interactable: `I_Interactable`, InteractionInfo: `S_InteractionInfo` | — | Update prompt text/icon, play fade in |
+| `OnInteractionFocusLost` | Interactable: `I_Interactable` | — | Play fade out, clear state |
+| `UpdatePrompt` | Info: `S_InteractionInfo` | — | Set PromptText, ActionKeyIcon, hold duration |
+| `SetHoldProgress` | Progress: Float (0-1) | — | Update HoldProgressRing fill amount |
+| `OnHoldStarted` | Duration: Float | — | Play hold progress animation over Duration |
+| `OnHoldCancelled` | — | — | Stop hold animation, reset ring to 0 |
+| `OnHoldCompleted` | — | — | Ring fills to 1 at end of hold |
+| `SetContextTags` | Tags: Array of Text | — | Add context tag labels to ContextTagsContainer |
+| `UpdateScreenPosition` | — | — | Tick: if bUseWorldOffset, project world location to screen |
+
+---
+
+## Structs
+
+```cpp
+// Consumed from BPC_InteractionDetector
+S_InteractionInfo
+{
+    FText ActionLabel;           // "Open", "Pick Up", etc
+    FText ObjectName;            // "Wooden Door", "Old Note"
+    bool bRequiresHold;
+    float HoldDuration;          // seconds
+    UTexture2D* ActionKeyIcon;   // platform-specific input icon
+    TArray<FText> ContextTags;   // "Safe", "Locked", "Hold"
+}
+```
+
+---
+
+## Blueprint Flow — Focus Gained
+
+```mermaid
+sequenceDiagram
+    participant Player as Player
+    participant Detector as BPC_InteractionDetector
+    participant UI as WBP_InteractionPromptDisplay
+    participant Interactable as I_Interactable
+
+    Player->>Detector: Look at interactable
+    Detector->>Interactable: GetInteractionInfo()
+    Interactable-->>Detector: S_InteractionInfo
+    Detector-->>UI: OnFocusGained Interactable, Info
+    UI->>UI: UpdatePrompt Info
+    UI->>UI: SetVisibility Visible
+    UI->>UI: PlayAnimation FadeIn
+    Note over UI: Hold required?
+    alt Hold interaction
+        UI->>UI: OnHoldStarted Duration
+        loop Each tick
+            UI->>UI: SetHoldProgress elapsed/Duration
+        end
+        UI->>UI: OnHoldCompleted
+    else Tap interaction
+        UI->>UI: OnHoldCompleted instantly
+    end
+```
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnPromptShown` | — | Prompt becomes visible |
+| `OnPromptHidden` | — | Prompt becomes hidden |
+| `OnHoldComplete` | — | Hold-fill reaches 100% |
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`BPC_InteractionDetector`](../03-interaction/16_BPC_InteractionDetector.md) | Dispatchers | Receive focus gain/loss, hold progress |
+| [`WBP_HUDController`](WBP_HUDController.md) | Parent reference | Positioning coordination |
+| [`I_Interactable`](../01-core/03_I_InterfaceLibrary.md) | Function call | GetInteractionInfo for prompt data |
+
+---
+
+## Reuse Notes
+
+The prompt rendering pattern is used in both first-person and third-person contexts. The `bUseWorldOffset` flag lets this widget serve both diegetic HUD skins (watch screen show prompts) and traditional screen-center prompt systems. Context tags are optional — if the array is empty, the container collapses.
+
+- Renamed from `WBP_InteractionUI` to `WBP_InteractionPromptDisplay` per Master naming convention.
+- Cross-references updated: `WBP_HUD` → `WBP_HUDController`.
--- a/docs/blueprints/06-ui/49_WBP_InventoryMenu.md
+++ b/docs/blueprints/06-ui/49_WBP_InventoryMenu.md
@@ -0,0 +1,132 @@
+# WBP_InventoryMenu — Widget (Inventory Screen)
+
+**Parent Class:** `UUserWidget` (created via Widget Blueprint)
+**Dependencies:** `BPC_InventorySystem`, `SS_UIManager`, `BPC_ActiveItemSystem`, `BPC_EquipmentSlotSystem`, `DA_ItemData`
+**File:** `WBP_InventoryMenu`
+
+---
+
+## Purpose
+
+Full-screen inventory grid view. Supports standard grid-list display, diegetic overlay mode, and radial quick-slot menu. Reads from `BPC_InventorySystem` but never writes — all mutations go through the component.
+
+---
+
+## Responsibilities
+
+- Display inventory slots in a scrollable grid (3 columns, N rows)
+- Show item details in a side panel when an item is selected
+- Support drag-and-drop between slots, between slots and equipment slots, and between slots and quick slots
+- Support right-click / gamepad context menu (Use, Equip, Drop, Examine, Combine)
+- Display item tooltip on hover
+- Filter/sort by category via tabs (All, Documents, Tools, Keys, Consumables, Quest Items)
+- Display weight bar at bottom (filled fractional, color-coded per weight tier)
+- Support `E_InventoryViewMode` switching (Grid, Diegetic Overlay, Radial Quick)
+- Close on B/Cancel or when `OnMenuClosed` fires from `SS_UIManager`
+
+---
+
+## Enums
+
+```cpp
+// Defined within the widget or a shared parent
+E_InventoryViewMode
+{
+    Grid,
+    DiegeticOverlay,
+    RadialQuick
+}
+```
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `OwningInventory` | `BPC_InventorySystem` | Cached reference (set on Construct) |
+| `ViewMode` | `E_InventoryViewMode` | Current display mode |
+| `SelectedSlotIndex` | Int | Currently highlighted slot (-1 = none) |
+| `SelectedItemData` | `DA_ItemData` | Item currently shown in detail panel |
+| `GridPanel` | `UniformGridPanel` | Main slot grid |
+| `DetailPanel` | `WBP_ItemDetailPanel` | Right-side detail panel |
+| `WeightBar` | `ProgressBar` | Bottom weight bar |
+| `WeightText` | `TextBlock` | "12.5 / 50.0 kg" |
+| `TabButtons` | Array of `Button` | All, Documents, Tools, Keys, etc. |
+| `ActiveFilter` | `E_ItemCategory` | Current filter |
+| `ContextMenu` | `WBP_ContextMenu` | Right-click popup |
+| `RadialMenu` | `WBP_RadialMenu` | Radial quick-slot selector (if RadialQuick mode) |
+
+---
+
+## Functions / Events
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Construct` | — | — | Cache inventory, bind dispatchers, rebuild grid |
+| `RebuildGrid` | Filter: `E_ItemCategory` | — | Clear grid, add slot widgets for matching items |
+| `OnSlotClicked` | SlotIndex: Int | — | Set SelectedSlotIndex, update detail panel |
+| `ShowContextMenu` | SlotIndex: Int | — | Open context menu at mouse position |
+| `ContextMenuAction` | Action: `E_ItemAction` | — | Route to UseItem, EquipItem, DropItem, etc. |
+| `UseItem` | SlotIndex: Int | — | Call inventory.UseItem(SlotIndex) |
+| `EquipItem` | SlotIndex: Int | — | Call inventory.EquipFromSlot(SlotIndex) |
+| `DropItem` | SlotIndex: Int | — | Call inventory.DropItem(SlotIndex) |
+| `CombineItems` | SourceIndex: Int, TargetIndex: Int | — | Call inventory.CombineItems(Source, Target) |
+| `ExamineItem` | SlotIndex: Int | — | Request narrative system examine description |
+| `SwitchViewMode` | NewMode: `E_InventoryViewMode` | — | Transition between Grid/Diegetic/Radial |
+| `UpdateWeightBar` | CurrentWeight: Float, MaxWeight: Float | — | Set bar percent, color per tier, update text |
+| `OnInventoryChanged` | SlotIndex: Int | — | Called via dispatcher; rebuild affected row |
+| `HandleNavigation` | Direction: `E_NavDirection` | — | Keyboard/gamepad slot navigation |
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnItemSelected` | ItemData: `DA_ItemData` | A slot is clicked |
+| `OnItemUsed` | SlotIndex: Int | An item is used |
+| `OnItemEquipped` | SlotIndex: Int | An item is equipped |
+| `OnItemDropped` | SlotIndex: Int | An item is dropped from inventory |
+| `OnCombineRequested` | SourceIndex: Int, TargetIndex: Int | Combine action initiated |
+| `OnViewModeChanged` | NewMode: `E_InventoryViewMode` | View mode transitions |
+
+---
+
+## Blueprint Flow — Grid Population
+
+```mermaid
+flowchart TD
+    A[Construct widget] --> B[Cache BPC_InventorySystem]
+    B --> C[Bind OnInventoryChanged dispatcher]
+    C --> D[RebuildGrid current filter]
+    D --> E[Loop items in inventory]
+    E --> F{Matches filter?}
+    F -->|Yes| G[Create WBP_InventorySlot]
+    G --> H[Add to UniformGridPanel column row]
+    F -->|No| I[Skip]
+    H --> J[Bind slot.OnClicked]
+    J --> K[Update WeightBar]
+```
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`BPC_InventorySystem`](../04-inventory/BPC_InventorySystem.md) | Direct reference, dispatchers | Read items, execute mutations |
+| [`SS_UIManager`](44_SS_UIManager.md) | `OpenMenu` / `CloseMenu` | Menu lifecycle |
+| [`BPC_ActiveItemSystem`](../04-inventory/BPC_ActiveItemSystem.md) | Direct calls | Assign/clear quick slots from radial menu |
+| [`BPC_EquipmentSlotSystem`](../04-inventory/BPC_EquipmentSlotSystem.md) | Dispatcher (`OnEquipmentChanged`) | Update equipped indicator |
+| [`BPC_InteractionDetector`](../03-interaction/16_BPC_InteractionDetector.md) | Dispatcher | Drop item creates pickup actor |
+| [`BPC_NarrativeStateSystem`] | Function | Examine item triggers narrative |
+
+---
+
+## Reuse Notes
+
+The grid population loop is the same pattern used by container inventories and shop UIs — the only difference is the source `BPC_InventorySystem` reference. Consider creating a shared `WBP_SlotGrid` base if containers need the same logic. The Diegetic Overlay and Radial Quick modes are purely visual transformations of the same slot data.
+
+- Renamed from `WBP_InventoryUI` to `WBP_InventoryMenu` per Master naming convention.
+- Cross-references updated: `BPC_InventoryComponent` → `BPC_InventorySystem`, `BPC_InventoryQuickSlot` → `BPC_ActiveItemSystem`, `BPC_EquipmentSystem` → `BPC_EquipmentSlotSystem`.
--- a/docs/blueprints/06-ui/50_WBP_JournalDocumentViewer.md
+++ b/docs/blueprints/06-ui/50_WBP_JournalDocumentViewer.md
@@ -0,0 +1,106 @@
+# WBP_JournalDocumentViewer — Widget (Document and Journal Viewer)
+
+**File:** [`Content/Framework/UI/WBP_JournalDocumentViewer`](Content/Framework/UI/WBP_JournalDocumentViewer.uasset)
+**Parent Class:** `UUserWidget`
+**Dependencies:** [`BPC_DocumentArchiveSystem`](../04-inventory/BPC_DocumentArchiveSystem.md), [`BPC_JournalSystem`](../04-inventory/BPC_JournalSystem.md)
+
+**Purpose:** Displays collected documents, notes, and the player journal. Supports text scrolling, page turns, and image plates. Read-only presentation — never modifies game state.
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ActiveDocument` | S_DocumentEntry | Currently displayed document |
+| `DocumentList` | Array of S_DocumentEntry | All collected documents for sidebar navigation |
+| `ActiveJournalEntry` | S_JournalEntry | Currently displayed journal entry |
+| `JournalEntryList` | Array of S_JournalEntry | All journal entries for sidebar navigation |
+| `bShowPageTurnAnim` | Bool | Enable page turn animation |
+| `FontStyle` | E_DocumentFontStyle | Handwritten, Typewritten, Digital |
+| `ViewMode` | E_DocumentViewMode | Document, Journal, or Combined |
+| `DocumentTitleText` | TextBlock | Active document title |
+| `DocumentBodyText` | RichTextBlock | Scrollable document body |
+| `DocumentImage` | Image | Optional plate/figure image |
+| `SidebarList` | ListView | Navigation sidebar |
+
+## Enums
+
+```cpp
+E_DocumentFontStyle
+{
+    Handwritten,
+    Typewritten,
+    Digital,
+    BloodScrawled
+}
+
+E_DocumentViewMode
+{
+    DocumentsOnly,
+    JournalOnly,
+    CombinedTimeline
+}
+```
+
+## Functions / Events
+
+| Name | Inputs | Outputs | What it does |
+|------|--------|---------|--------------|
+| `OpenDocument` | DocumentTag: GameplayTag | — | Loads document from archive, displays with font style |
+| `CloseDocument` | — | — | Returns to document list |
+| `OpenJournal` | EntryTag: GameplayTag | — | Loads journal entry, displays |
+| `NextDocument` | — | — | Selects next document in list |
+| `PreviousDocument` | — | — | Selects previous document in list |
+| `NextPage` | — | — | Scrolls body text to next page |
+| `PreviousPage` | — | — | Scrolls body text to previous page |
+| `SetViewMode` | Mode: E_DocumentViewMode | — | Switches between document/journal/combined |
+| `MarkAsRead` | DocumentTag: GameplayTag | — | Sets bIsRead on document entry |
+| `RefreshList` | — | — | Rebuilds sidebar from archive and journal systems |
+| `SortByChapter` | — | — | Sorts documents/entries by discovery chapter |
+| `SortByType` | — | — | Sorts documents by type, entries by date |
+
+## Event Dispatchers
+
+| Name | Parameters | Fired when |
+|------|-----------|-----------|
+| `OnDocumentOpened` | DocumentTag: GameplayTag | Player opens a document |
+| `OnDocumentClosed` | — | Player closes document viewer |
+| `OnDocumentRead` | DocumentTag: GameplayTag | Document marked as read |
+
+## Blueprint Flow Diagram
+
+```mermaid
+flowchart TD
+    A[Player opens Journal/Documents] --> B[ViewMode = CombinedTimeline]
+    B --> C[RefreshList from BPC_DocumentArchiveSystem + BPC_JournalSystem]
+    C --> D[Populate SidebarList]
+    D --> E[Wait for selection]
+
+    E --> F{Item selected?}
+    F -->|Document| G[OpenDocument with DocumentTag]
+    F -->|Journal Entry| H[OpenJournal with EntryTag]
+
+    G --> I[Set ActiveDocument = entry from archive]
+    I --> J[Display title, body text, optional image]
+    I --> K[MarkAsRead]
+
+    H --> L[Set ActiveJournalEntry]
+    L --> M[Display heading, body, timestamp]
+```
+
+## Communications With
+
+| Target System | Method | Why |
+|---------------|--------|-----|
+| `BPC_DocumentArchiveSystem` | Direct read | Get all found documents |
+| `BPC_JournalSystem` | Direct read | Get all journal entries |
+| `WBP_InventoryMenu` | Parent navigation | Open from inventory tab |
+| `SS_UIManager` | Push/Pop | Menu stack management |
+
+## Reuse Notes
+
+- The `E_DocumentFontStyle` enum lets each project set the visual tone per document type
+- `ViewMode` can be restricted to DocumentsOnly for games without a journal
+- The page-turn anim is optional; disable for performance or minimalist UI
+- RichTextBlock supports markup — use for emphasis, different speaker colours, or lore highlight
--- a/docs/blueprints/06-ui/51_WBP_MainMenu.md
+++ b/docs/blueprints/06-ui/51_WBP_MainMenu.md
@@ -0,0 +1,47 @@
+# WBP_MainMenu — Widget (Main Menu)
+
+**Parent:** `UUserWidget`
+**Used by:** `SS_UIManager.OpenMenu("MainMenu")`
+**Depends On:** `SS_UIManager`, `SS_SaveManager`, `GI_GameFramework`
+
+---
+
+### Purpose
+Title screen with New Game, Continue, Load, Settings, Credits, Quit.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `bContinueAvailable` | Bool | Set by SaveManager check on Construct |
+| `AnimatedTitle` | `Image` or `TextBlock` | Animated game title |
+| `ContinueButton` | `Button` | Highlights if save exists |
+| `NewGameButton` | `Button` | Starts new game |
+| `LoadGameButton` | `Button` | Opens load slot list |
+| `SettingsButton` | `Button` | Opens settings menu |
+| `CreditsButton` | `Button` | Opens credits |
+| `QuitButton` | `Button` | Quit confirmation |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `OnConstruct` | — | — | Check SS_SaveManager.HasAnySave for continue availability |
+| `OnNewGame` | — | — | Call SS_SaveManager.ResetGameState, then OpenLevel "FirstLevel" |
+| `OnContinue` | — | — | Call SS_SaveManager.LoadLatestSave, then OpenLevel from save header |
+| `OnLoadGame` | — | — | Pushes load slot selection UI via SS_UIManager |
+| `OnSettings` | — | — | SS_UIManager.PushMenu "SettingsMenu" |
+| `OnCredits` | — | — | SS_UIManager.PushMenu "Credits" |
+| `OnQuit` | — | — | Show quit confirmation dialog |
+| `OnConfirmQuit` | — | — | `UKismetSystemLibrary.QuitGame` |
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`SS_UIManager`](44_SS_UIManager.md) | Push/Pop/Close/Open | Menu lifecycle |
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Save/Load functions | Save slots |
+| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | SetGamePhase, dispatchers | Phase transitions |
+
+### Reuse Notes
+- Split from original bundled `36_WBP_MenuWidgets.md` per Clean Slate refactoring plan
--- a/docs/blueprints/06-ui/52_WBP_MenuFlowController.md
+++ b/docs/blueprints/06-ui/52_WBP_MenuFlowController.md
@@ -0,0 +1,83 @@
+# WBP_MenuFlowController — Widget (Menu Flow Controller)
+
+**Parent:** `UUserWidget` (non-visible overlay that lives under SS_UIManager)
+**Depends On:** `SS_UIManager`, `GI_GameFramework`, `SS_SaveManager`
+
+---
+
+### Purpose
+Orchestrates transitions between MenuFlow states: SplashScreen > MainMenu > Settings transitions > Loading transitions > Level transitions > Credits > Quit.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `CurrentFlowState` | `E_MenuFlowState` | Current flow state |
+| `FadeWidget` | `Image` | Black full-screen fade image |
+| `FadeDuration` | Float | Fade duration in seconds (1.0) |
+| `AnimFadeIn` | `WidgetAnimation` | Fade from 0 to 1 opacity |
+| `AnimFadeOut` | `WidgetAnimation` | Fade from 1 to 0 opacity |
+| `bIsTransitioning` | Bool | Block input during transition |
+
+### Enums
+
+```cpp
+E_MenuFlowState
+{
+    SplashScreen,
+    MainMenu,
+    Settings,
+    Loading,
+    InGame,
+    Paused,
+    Credits,
+    Quit
+}
+```
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `TransitionToState` | NewState: `E_MenuFlowState` | — | Fade out, switch state, fade in |
+| `OnSplashComplete` | — | — | Auto-transition to MainMenu after splash timer |
+| `OnFadeOutComplete` | — | — | Switch visibility, load levels, then fade in |
+| `OpenMainMenu` | — | — | OpenLevel "MainMenu", then TransitionToState MainMenu |
+| `StartNewGame` | — | — | Fade out, OpenLevel first level, set InGame |
+| `ReturnToMainMenu` | — | — | OpenLevel "MainMenu", TransitionToState MainMenu |
+| `ShowCredits` | — | — | OpenLevel "CreditsMap", TransitionToState Credits |
+| `IsTransitioning` | — | Bool | Query lock |
+
+### Blueprint Flow — Menu Flow Transitions
+
+```mermaid
+flowchart LR
+    A[Splash] -->|timer| B[MainMenu]
+    B -->|New Game| C[Fade Out]
+    C --> D[OpenLevel FirstLevel]
+    D --> E[Fade In]
+    E --> F[InGame]
+    B -->|Settings| G[Push Settings Menu]
+    G -->|Back| B
+    F -->|ESC| H[Push Pause Menu]
+    H -->|Resume| F
+    H -->|Quit to Menu| I[Fade Out]
+    I --> J[OpenLevel MainMenu]
+    J --> B
+    F -->|Death| K[Fade to Black]
+    K --> L[Respawn or AltDeathSpace]
+    F -->|Credits| M[OpenLevel Credits]
+```
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`SS_UIManager`](44_SS_UIManager.md) | Push/Pop/Close/Open | Menu lifecycle |
+| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | SetGamePhase, dispatchers | Phase transitions |
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Save/Load functions | Save slots |
+| [`WBP_HUDController`](WBP_HUDController.md) | Parent reference | Fade coordination |
+
+### Reuse Notes
+- Manages transitions centrally — no individual menu needs to open levels or handle fade logic
+- Split from original bundled `36_WBP_MenuWidgets.md` per Clean Slate refactoring plan
--- a/docs/blueprints/06-ui/53_WBP_NotificationToast.md
+++ b/docs/blueprints/06-ui/53_WBP_NotificationToast.md
@@ -0,0 +1,52 @@
+# WBP_NotificationToast — Widget (Toast Notification)
+
+**Parent:** `UUserWidget`
+**Used by:** Any system via dispatcher
+**Depends On:** `WBP_HUDController`
+
+---
+
+### Purpose
+Non-blocking toast notification that slides in from top/left edge, displays for a duration, then slides out.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ToastText` | `TextBlock` | Notification body |
+| `ToastIcon` | `Image` | Optional icon |
+| `ToastDuration` | Float | Seconds before auto-hide (2-5) |
+| `AnimSlideIn` | `WidgetAnimation` | Slide in |
+| `AnimSlideOut` | `WidgetAnimation` | Slide out |
+| `ToastQueue` | Array of `FToastData` | Queued notifications if one is active |
+
+### Structs
+
+```cpp
+FToastData
+{
+    FText Message;
+    UTexture2D* Icon;
+    float Duration;
+    EToastPriority Priority; // Low, Normal, High
+}
+```
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `ShowToast` | Data: `FToastData` | — | If not playing, start; else queue |
+| `PlaySlideIn` | — | — | Play AnimSlideIn, set timer for duration |
+| `OnToastFinished` | — | — | Play AnimSlideOut, dequeue next |
+| `DismissAll` | — | — | Clear queue, force hide |
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`WBP_HUDController`](WBP_HUDController.md) | Parent reference / Dispatcher | Toast display routing |
+
+### Reuse Notes
+- Uses a queue system — any system can fire a toast by calling the appropriate dispatcher on WBP_HUDController
+- Split from original bundled `36_WBP_MenuWidgets.md` per Clean Slate refactoring plan
--- a/docs/blueprints/06-ui/54_WBP_ObjectiveDisplay.md
+++ b/docs/blueprints/06-ui/54_WBP_ObjectiveDisplay.md
@@ -0,0 +1,86 @@
+# WBP_ObjectiveDisplay — Widget (Objective Display)
+
+**Parent:** `UUserWidget`
+**Used by:** `WBP_HUDController`, `BPC_ObjectiveSystem`
+**Depends On:** `BPC_ObjectiveSystem`
+
+---
+
+### Purpose
+Displays current objectives as an overlay on the HUD. Shows active objective text, objective markers, and progress indicators. Updates in real-time as objectives are added, completed, or updated.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ObjectiveText` | `TextBlock` | Current objective description |
+| `ObjectiveMarker` | `Image` | Directional indicator if objective is off-screen |
+| `ProgressBar` | `ProgressBar` | Objective progress (0-1) if applicable |
+| `AnimFadeIn` | `WidgetAnimation` | Fade in on objective change |
+| `AnimFadeOut` | `WidgetAnimation` | Fade out when objective completes |
+| `AnimObjectiveComplete` | `WidgetAnimation` | Completion flourish |
+| `ObjectiveQueue` | Array of `S_ObjectiveData` | Queued objectives for sequential display |
+
+### Structs
+
+```cpp
+S_ObjectiveData
+{
+    FText ObjectiveText;
+    FGameplayTag ObjectiveTag;
+    float Progress;
+    bool bIsComplete;
+    FVector WorldLocation; // For off-screen marker
+}
+```
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `OnConstruct` | — | — | Bind to BPC_ObjectiveSystem dispatchers |
+| `OnObjectiveActivated` | Objective: `S_ObjectiveData` | — | Show objective with fade-in animation |
+| `OnObjectiveUpdated` | Objective: `S_ObjectiveData` | — | Update progress bar and text |
+| `OnObjectiveCompleted` | ObjectiveTag: GameplayTag | — | Play completion animation, then fade out |
+| `UpdateOffScreenMarker` | WorldLocation: FVector | — | Calculate screen position, rotate marker |
+| `ClearAllObjectives` | — | — | Clear all active objective displays |
+
+### Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnObjectiveDisplayed` | ObjectiveText: FText | New objective shown |
+| `OnObjectiveCleared` | — | All objectives cleared |
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`BPC_ObjectiveSystem`](../07-narrative/39_BPC_ObjectiveSystem.md) | Dispatcher | Receive objective changes |
+| [`WBP_HUDController`](WBP_HUDController.md) | Parent reference | Coordinate visibility with other HUD elements |
+
+### Blueprint Flow
+
+```
+[OnObjectiveActivated]
+  └─► Set ObjectiveText = Objective.ObjectiveText
+  └─► Set ProgressBar visibility based on objective type
+  └─► If objective has world location → Show ObjectiveMarker
+  └─► Play AnimFadeIn
+  └─► Broadcast OnObjectiveDisplayed
+
+[OnObjectiveCompleted]
+  └─► Play AnimObjectiveComplete
+  └─► Delay 2.0 seconds
+  └─► Play AnimFadeOut
+  └─► Show next queued objective if any
+
+[UpdateOffScreenMarker]
+  └─► Project world location to screen
+  └─► If behind camera → place at screen edge, rotate indicator
+  └─► Update ObjectiveMarker position + rotation
+```
+
+### Reuse Notes
+- Created as part of Clean Slate refactoring (Master Section 6.6)
+- Follows TEMPLATE.md format for all new blueprint specs
--- a/docs/blueprints/06-ui/55_WBP_PauseMenu.md
+++ b/docs/blueprints/06-ui/55_WBP_PauseMenu.md
@@ -0,0 +1,59 @@
+# WBP_PauseMenu — Widget (Pause Menu)
+
+**Parent:** `UUserWidget`
+**Used by:** `SS_UIManager.PushMenu("PauseMenu")`
+**Depends On:** `SS_UIManager`, `SS_SaveManager`, `GI_GameFramework`
+
+---
+
+### Purpose
+In-game pause overlay with Resume, Save, Load, Settings, Return to Main Menu.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ResumeButton` | `Button` | Closes menu, resumes game |
+| `SaveButton` | `Button` | Manual save |
+| `LoadButton` | `Button` | Load a different save |
+| `SettingsButton` | `Button` | Opens settings |
+| `QuitToMenuButton` | `Button` | Confirm quit to main menu |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `OnResume` | — | — | SS_UIManager.CloseTopMenu, set game phase back to InGame |
+| `OnSave` | — | — | SS_SaveManager.CreateManualSave, show notification |
+| `OnLoad` | — | — | Push load slot selection via SS_UIManager |
+| `OnSettings` | — | — | SS_UIManager.PushMenu "SettingsMenu" |
+| `OnQuitToMenu` | — | — | Show confirmation, confirm calls OpenMainMenu |
+
+### Blueprint Flow — Pause Menu Open
+
+```mermaid
+sequenceDiagram
+    participant Player as Player
+    participant UIMgr as SS_UIManager
+    participant GM as GI_GameFramework
+    participant HUD as WBP_HUDController
+
+    Player->>UIMgr: Press ESC
+    UIMgr->>GM: SetGamePhase Paused
+    GM->>HUD: OnPhaseChanged Paused
+    HUD->>HUD: Hide diegetic elements
+    UIMgr->>UIMgr: PushMenu PauseMenu
+    Note over UIMgr: Show mouse cursor
+    Note over UIMgr: Input mode = UI Only
+```
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`SS_UIManager`](44_SS_UIManager.md) | Push/Pop/Close/Open | Menu lifecycle |
+| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | SetGamePhase, dispatchers | Phase transitions |
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Save/Load functions | Save slots |
+
+### Reuse Notes
+- Split from original bundled `36_WBP_MenuWidgets.md` per Clean Slate refactoring plan
--- a/docs/blueprints/06-ui/56_WBP_ScreenEffectController.md
+++ b/docs/blueprints/06-ui/56_WBP_ScreenEffectController.md
@@ -0,0 +1,43 @@
+# WBP_ScreenEffectController — Widget (Screen Effects)
+
+**Parent:** `UUserWidget`
+**Used by:** `WBP_HUDController`, `BPC_HealthSystem`, `BPC_StressSystem`
+**Depends On:** `WBP_HUDController`
+
+---
+
+### Purpose
+Full-screen overlay for damage vignettes, jump scare flashes, stress distortion, and post-process material effects.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `DamageVignetteImage` | `Image` | Red vignette overlay |
+| `FlashImage` | `Image` | White flash for jump scares |
+| `StressDistortionMaterial` | `MaterialInstanceDynamic` | Screen distortion MID |
+| `DamageAnim` | `WidgetAnimation` | Fade in/out damage vignette |
+| `JumpScareAnim` | `WidgetAnimation` | Quick white flash + fade |
+| `StressAnim` | `WidgetAnimation` | Distortion intensity pulse |
+| `bIsFlashing` | Bool | Prevent double-trigger |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `TriggerDamageFlash` | Intensity: Float (0-1) | — | Set DamageVignette opacity, play DamageAnim |
+| `TriggerJumpScareFlash` | — | — | Play JumpScareAnim, prevent re-trigger during flash |
+| `SetStressDistortion` | Amount: Float (0-1) | — | Set scalar param on StressDistortionMaterial |
+| `ClearEffects` | — | — | Reset all overlays to 0 opacity |
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`WBP_HUDController`](WBP_HUDController.md) | Parent reference | Routing damage/stress events |
+| [`BPC_HealthSystem`](../02-player/08_BPC_HealthSystem.md) | Dispatcher | Damage flash triggers |
+| [`BPC_StressSystem`](../02-player/10_BPC_StressSystem.md) | Dispatcher | Stress distortion |
+
+### Reuse Notes
+- Reusable VFX overlay; the same widget handles damage, stress, and jump scares without duplication
+- Split from original bundled `36_WBP_MenuWidgets.md` per Clean Slate refactoring plan
--- a/docs/blueprints/06-ui/57_WBP_SettingsMenu.md
+++ b/docs/blueprints/06-ui/57_WBP_SettingsMenu.md
@@ -0,0 +1,103 @@
+# WBP_SettingsMenu — Widget (Settings Menu)
+
+**Parent:** `UUserWidget`
+**Used by:** `SS_UIManager.PushMenu("SettingsMenu")`
+**Depends On:** `SS_UIManager`, `SS_SettingsSystem`
+
+---
+
+### Purpose
+Full settings screen with sections: Audio, Video/Graphics, Gameplay, Controls, Accessibility.
+
+### Enums (local or global)
+
+```cpp
+E_SettingsTab
+{
+    Audio,
+    Video,
+    Gameplay,
+    Controls,
+    Accessibility
+}
+```
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ActiveTab` | `E_SettingsTab` | Currently visible tab |
+| `TabButtons` | Array of `Button` | Tab navigation buttons |
+| `TabPanels` | Array of `PanelWidget` | Tab content panels |
+
+**Audio Tab Children:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `MasterVolumeSlider` | `Slider` | 0-100 |
+| `SFXVolumeSlider` | `Slider` | 0-100 |
+| `MusicVolumeSlider` | `Slider` | 0-100 |
+| `VoiceVolumeSlider` | `Slider` | 0-100 |
+| `SubtitlesToggle` | `CheckBox` | On/Off |
+
+**Video Tab Children:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ResolutionDropdown` | `ComboBoxString` | Available resolutions |
+| `WindowModeDropdown` | `ComboBoxString` | Fullscreen, Windowed, Borderless |
+| `VSyncToggle` | `CheckBox` | On/Off |
+| `QualityPresetDropdown` | `ComboBoxString` | Low, Medium, High, Epic |
+| `BrightnessSlider` | `Slider` | 0.5-2.0 gamma |
+
+**Gameplay Tab Children:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `InvertYAxisToggle` | `CheckBox` | On/Off |
+| `SensitivitySlider` | `Slider` | Mouse sensitivity 0.1-5.0 |
+| `HoldDurationToggle` | `CheckBox` | Tap vs Hold for interactions |
+| `AutoPickupToggle` | `CheckBox` | On/Off |
+| `CrosshairToggle` | `CheckBox` | Show crosshair |
+
+**Controls Tab Children:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ActionMappingsList` | `ListView` | Key binding rows |
+| `ResetDefaultsButton` | `Button` | Reset all bindings |
+
+**Accessibility Tab Children:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `SubtitleSizeDropdown` | `ComboBoxString` | Small, Medium, Large |
+| `SubtitleBackgroundOpacity` | `Slider` | 0-100% |
+| `ColorblindModeDropdown` | `ComboBoxString` | None, Protanopia, Deuteranopia, Tritanopia |
+| `HighContrastUIToggle` | `CheckBox` | On/Off |
+| `CameraShakeIntensity` | `Slider` | 0-100% |
+| `MotionBlurToggle` | `CheckBox` | On/Off |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `OnConstruct` | — | — | Populate dropdowns from system, load saved settings |
+| `SwitchTab` | Tab: `E_SettingsTab` | — | Show selected panel, hide others |
+| `OnSettingChanged` | SettingName: FName, Value: Generic | — | Write to SS_SettingsSystem |
+| `SaveSettings` | — | — | SS_SettingsSystem.SaveToDisk |
+| `ApplyVideoSettings` | — | — | Apply resolution, window mode, quality |
+| `ResetToDefaults` | — | — | Load default values, re-populate UI |
+| `OnBack` | — | — | SaveSettings, SS_UIManager.PopMenu |
+| `RebindKey` | ActionName: FName | — | Listen for next key press, map to action |
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`SS_UIManager`](44_SS_UIManager.md) | Push/Pop | Menu lifecycle |
+| `SS_SettingsSystem` | Function calls | Read/write settings |
+
+### Reuse Notes
+- The tab panel pattern can be extended for mod settings or developer menus by adding new tab entries
+- Split from original bundled `36_WBP_MenuWidgets.md` per Clean Slate refactoring plan