From ffe69f7a99aae174bd42ed6d052215fb35d210e0 Mon Sep 17 00:00:00 2001 From: Yu Leng Date: Wed, 26 Nov 2025 16:23:36 +0800 Subject: [PATCH] Replace ASCII diagrams with Mermaid in documentation Updated `host-settings-awareness.md` to replace outdated ASCII art diagrams with modern `mermaid` diagrams for improved readability and maintainability. - Replaced the high-level architecture overview with a `mermaid` flowchart to better illustrate component relationships and cross-process communication. - Replaced the initial settings delivery process diagram with a `mermaid` sequence diagram, detailing the flow for both OOP extensions and built-in commands. - Replaced the settings change notification diagram with a `mermaid` sequence diagram, showing the propagation of settings changes and UI updates in extensions. These changes enhance the clarity and visual appeal of the documentation, making it easier for developers to understand the processes. --- .../host-settings-awareness.md | 200 +++++++----------- 1 file changed, 71 insertions(+), 129 deletions(-) diff --git a/src/modules/cmdpal/doc/host-settings-awareness/host-settings-awareness.md b/src/modules/cmdpal/doc/host-settings-awareness/host-settings-awareness.md index 75d4f67a75..11440cc404 100644 --- a/src/modules/cmdpal/doc/host-settings-awareness/host-settings-awareness.md +++ b/src/modules/cmdpal/doc/host-settings-awareness/host-settings-awareness.md @@ -86,47 +86,28 @@ Some extensions may want to provide experiences that align with the host's confi ### Architecture Overview -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Command Palette Host │ -│ ┌─────────────────┐ ┌──────────────────┐ │ -│ │ SettingsModel │───▶│HostSettingsConv- │ │ -│ │ │ │ erter │ │ -│ └────────┬────────┘ └────────┬─────────┘ │ -│ │ │ │ -│ │SettingsChanged │ IHostSettings │ -│ ▼ ▼ │ -│ ┌─────────────────────────────────────────────────┐ │ -│ │ ExtensionService │ │ -│ │ NotifyHostSettingsChanged(IHostSettings) │ │ -│ └────────────────────┬────────────────────────────┘ │ -│ │ │ -└───────────────────────┼──────────────────────────────────────────┘ - │ Cross-Process (COM/WinRT) - ▼ -┌───────────────────────────────────────────────────────────────────┐ -│ Extension Process │ -│ ┌────────────────────────────────────────────────┐ │ -│ │ CommandProvider │ │ -│ │ OnHostSettingsChanged(IHostSettings settings) │ │ -│ └────────────────────┬───────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────────┐ │ -│ │ HostSettingsManager │ │ -│ │ ┌──────────────────────────────────────────┐ │ │ -│ │ │ Current: IHostSettings │ │ │ -│ │ │ SettingsChanged: event Action │ │ │ -│ │ └──────────────────────────────────────────┘ │ │ -│ └────────────────────┬───────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────────┐ │ -│ │ Extension Pages / Commands │ │ -│ │ (Subscribe to HostSettingsManager. │ │ -│ │ SettingsChanged or read Current) │ │ -│ └────────────────────────────────────────────────┘ │ -└───────────────────────────────────────────────────────────────────┘ +```mermaid +flowchart TB + subgraph Host["Command Palette Host"] + SM[SettingsModel] + HSC[HostSettingsConverter] + ES["ExtensionService
NotifyHostSettingsChanged(IHostSettings)"] + + SM -->|SettingsChanged| ES + SM --> HSC + HSC -->|IHostSettings| ES + end + + ES -->|"Cross-Process (COM/WinRT)"| CP + + subgraph Extension["Extension Process"] + CP["CommandProvider
OnHostSettingsChanged(IHostSettings)"] + HSM["HostSettingsManager
━━━━━━━━━━━━━━━━━━━━
Current: IHostSettings
SettingsChanged: event Action"] + EPC["Extension Pages / Commands
(Subscribe to HostSettingsManager.SettingsChanged
or read Current)"] + + CP --> HSM + HSM --> EPC + end ``` ### Key Components @@ -451,100 +432,61 @@ This design ensures: This diagram shows how initial host settings are delivered to extensions when they first load: -``` -┌─────────────────────┐ ┌─────────────────────────┐ ┌────────────────────┐ ┌─────────────────┐ -│TopLevelCommandManager│ │CommandProviderWrapper │ │ExtensionWrapper │ │Extension Process│ -└──────────┬──────────┘ └────────────┬────────────┘ └─────────┬──────────┘ └────────┬────────┘ - │ │ │ │ - │ LoadTopLevelCommandsFromProvider() │ │ - │─────────────────────────▶│ │ │ - │ │ │ │ - │ │ LoadTopLevelCommands() │ │ - │ │────────────────────────▶│ │ - │ │ │ │ - │ │◀────────────────────────│ │ - │ │ │ │ - │ │ SendInitialHostSettings() │ - │ │──────┐ │ │ - │ │ │ Get settings │ │ - │ │◀─────┘ │ │ - │ │ │ │ - │ │ [OOP Extension] │ │ - │ │ NotifyHostSettingsChanged(settings) │ - │ │────────────────────────▶│ │ - │ │ │ │ - │ │ │ GetApiExtensionStubs() - │ │ │─────────────────────▶│ - │ │ │ │ - │ │ │◀─────────────────────│ - │ │ │ [stubs array] │ - │ │ │ │ - │ │ │ OnHostSettingsChanged(settings) - │ │ │─────────────────────▶│ - │ │ │ │ - │ │ │ │ HostSettingsManager - │ │ │ │ .Update(settings) - │ │ │ │──────┐ - │ │ │ │ │ - │ │ │ │◀─────┘ - │ │ │ │ - │ │ [Built-in Command] │ │ - │ │ OnHostSettingsChanged(settings) (direct call) │ - │ │───────────────────────────────────────────────▶│ - │ │ │ │ - │◀─────────────────────────│ │ │ - │ │ │ │ +```mermaid +sequenceDiagram + participant TLCM as TopLevelCommandManager + participant CPW as CommandProviderWrapper + participant EW as ExtensionWrapper + participant EP as Extension Process + + TLCM->>CPW: LoadTopLevelCommandsFromProvider() + CPW->>EW: LoadTopLevelCommands() + EW-->>CPW: (commands loaded) + + CPW->>CPW: SendInitialHostSettings()
Get settings + + alt OOP Extension + CPW->>EW: NotifyHostSettingsChanged(settings) + EW->>EP: GetApiExtensionStubs() + EP-->>EW: [stubs array] + EW->>EP: OnHostSettingsChanged(settings) + EP->>EP: HostSettingsManager.Update(settings) + else Built-in Command + CPW->>EP: OnHostSettingsChanged(settings)
(direct call) + EP->>EP: HostSettingsManager.Update(settings) + end + + CPW-->>TLCM: (complete) ``` ### Settings Change Notification This diagram shows how settings changes are propagated to all extensions: -``` -┌───────────┐ ┌────────────┐ ┌────────────────┐ ┌─────────────────┐ ┌─────────────────┐ -│ User │ │SettingsModel│ │ExtensionService│ │ExtensionWrapper │ │Extension Process│ -└─────┬─────┘ └──────┬─────┘ └───────┬────────┘ └────────┬────────┘ └────────┬────────┘ - │ │ │ │ │ - │ Change setting│ │ │ │ - │──────────────▶│ │ │ │ - │ │ │ │ │ - │ │ SettingsChanged event │ │ - │ │───────────────▶│ │ │ - │ │ │ │ │ - │ │ │ ToHostSettings() │ │ - │ │ │──────┐ │ │ - │ │ │ │ Convert │ │ - │ │ │◀─────┘ │ │ - │ │ │ │ │ - │ │ │ NotifyHostSettingsChanged(settings) │ - │ │ │───────────────────▶│ │ - │ │ │ │ │ - │ │ │ [For each extension] │ - │ │ │ │ │ - │ │ │ │ GetApiExtensionStubs() - │ │ │ │───────────────────▶│ - │ │ │ │ │ - │ │ │ │◀───────────────────│ - │ │ │ │ [stubs array] │ - │ │ │ │ │ - │ │ │ │ OnHostSettingsChanged(settings) - │ │ │ │───────────────────▶│ - │ │ │ │ │ - │ │ │ │ │ HostSettingsManager - │ │ │ │ │ .Update(settings) - │ │ │ │ │──────┐ - │ │ │ │ │ │ - │ │ │ │ │◀─────┘ - │ │ │ │ │ - │ │ │ │ │ SettingsChanged - │ │ │ │ │ event fired - │ │ │ │ │──────┐ - │ │ │ │ │ │ - │ │ │ │ │◀─────┘ - │ │ │ │ │ - │ │ │ │ │ Extension pages - │ │ │ │ │ update UI - │ │ │ │ │ +```mermaid +sequenceDiagram + participant User + participant SM as SettingsModel + participant ES as ExtensionService + participant EW as ExtensionWrapper + participant EP as Extension Process + + User->>SM: Change setting + SM->>ES: SettingsChanged event + + ES->>ES: ToHostSettings()
Convert settings + + ES->>EW: NotifyHostSettingsChanged(settings) + + loop For each extension + EW->>EP: GetApiExtensionStubs() + EP-->>EW: [stubs array] + EW->>EP: OnHostSettingsChanged(settings) + + EP->>EP: HostSettingsManager.Update(settings) + EP->>EP: SettingsChanged event fired + EP->>EP: Extension pages update UI + end ``` ## Example Usage