From 1bff24c19bbc9d140526f4503534f13f4d4e937b Mon Sep 17 00:00:00 2001
From: Nate Bross <nate@brosstribe.com>
Date: Wed, 22 Apr 2026 18:54:58 -0500
Subject: [PATCH 1/2] feat: add plugin configuration API

Plugins declare a typed PluginConfigSchema and receive persisted values via
OnConfigChanged. The host stores per-plugin JSON under
%LocalAppData%/SharpFM/plugin-config/ and renders a generic settings dialog
from the schema in the Plugin Manager. Plugins with an empty schema incur
zero overhead and show a disabled Configure button.

Closes #183
---
 .../ClipInspectorPanel.axaml                  |   4 +-
 .../ClipInspectorPlugin.cs                    |  35 +-
 .../ClipInspectorViewModel.cs                 |   6 +
 .../XmlViewerPlugin.cs                        |   2 +
 src/SharpFM.Plugin/IPlugin.cs                 |  16 +
 src/SharpFM.Plugin/PluginConfigSchema.cs      |  48 ++
 src/SharpFM/App.axaml.cs                      |   5 +-
 src/SharpFM/MainWindow.axaml.cs               |   8 +-
 .../PluginManager/PluginConfigDialog.axaml    |  33 ++
 .../PluginManager/PluginConfigDialog.axaml.cs | 158 +++++++
 .../PluginManager/PluginManagerViewModel.cs   |  10 +-
 .../PluginManager/PluginManagerWindow.axaml   |   2 +
 .../PluginManagerWindow.axaml.cs              |  22 +-
 src/SharpFM/Services/PluginConfigService.cs   | 197 +++++++++
 src/SharpFM/Services/PluginService.cs         |   9 +-
 .../PluginConfigSchemaTests.cs                |  46 ++
 .../PluginConfigServiceTests.cs               | 413 ++++++++++++++++++
 .../PluginManagerViewModelTests.cs            |   2 +
 .../PluginServiceInstallTests.cs              |   5 +-
 .../PluginServiceTests.cs                     |   8 +-
 .../ViewModels/MainWindowViewModelTests.cs    |   2 +
 21 files changed, 1015 insertions(+), 16 deletions(-)
 create mode 100644 src/SharpFM.Plugin/PluginConfigSchema.cs
 create mode 100644 src/SharpFM/PluginManager/PluginConfigDialog.axaml
 create mode 100644 src/SharpFM/PluginManager/PluginConfigDialog.axaml.cs
 create mode 100644 src/SharpFM/Services/PluginConfigService.cs
 create mode 100644 tests/SharpFM.Plugin.Tests/PluginConfigSchemaTests.cs
 create mode 100644 tests/SharpFM.Plugin.Tests/PluginConfigServiceTests.cs

diff --git a/src/SharpFM.Plugin.Sample/ClipInspectorPanel.axaml b/src/SharpFM.Plugin.Sample/ClipInspectorPanel.axaml
index 2cdf87a..6730aa5 100644
--- a/src/SharpFM.Plugin.Sample/ClipInspectorPanel.axaml
+++ b/src/SharpFM.Plugin.Sample/ClipInspectorPanel.axaml
@@ -19,12 +19,12 @@
                 <TextBlock Classes="Fluent2Body" Text="{Binding ClipType}" />
             </StackPanel>
 
-            <StackPanel Spacing="2">
+            <StackPanel Spacing="2" IsVisible="{Binding ShowElementCount}">
                 <TextBlock Classes="Fluent2Caption" Opacity="0.7" Text="XML Elements" />
                 <TextBlock Classes="Fluent2Body" Text="{Binding ElementCount}" />
             </StackPanel>
 
-            <StackPanel Spacing="2">
+            <StackPanel Spacing="2" IsVisible="{Binding ShowXmlSize}">
                 <TextBlock Classes="Fluent2Caption" Opacity="0.7" Text="Approx. Size" />
                 <TextBlock Classes="Fluent2Body" Text="{Binding XmlSize}" />
             </StackPanel>
diff --git a/src/SharpFM.Plugin.Sample/ClipInspectorPlugin.cs b/src/SharpFM.Plugin.Sample/ClipInspectorPlugin.cs
index 98d1274..22685d5 100644
--- a/src/SharpFM.Plugin.Sample/ClipInspectorPlugin.cs
+++ b/src/SharpFM.Plugin.Sample/ClipInspectorPlugin.cs
@@ -17,8 +17,37 @@ public class ClipInspectorPlugin : IPanelPlugin
     public IReadOnlyList<PluginKeyBinding> KeyBindings => [];
     public IReadOnlyList<PluginMenuAction> MenuActions => [];
 
+    public PluginConfigSchema ConfigSchema { get; } = new(new[]
+    {
+        new PluginConfigField(
+            Key: "ShowElementCount",
+            Label: "Show XML element count",
+            Type: PluginConfigFieldType.Bool,
+            DefaultValue: true,
+            Description: "Display the number of XML elements in the selected clip."),
+        new PluginConfigField(
+            Key: "ShowXmlSize",
+            Label: "Show approximate size",
+            Type: PluginConfigFieldType.Bool,
+            DefaultValue: true,
+            Description: "Display the approximate byte size of the clip's XML."),
+    });
+
+    public void OnConfigChanged(IReadOnlyDictionary<string, object?> values)
+    {
+        _showElementCount = values.TryGetValue("ShowElementCount", out var a) && a is bool ba ? ba : true;
+        _showXmlSize = values.TryGetValue("ShowXmlSize", out var b) && b is bool bb ? bb : true;
+        if (_viewModel is not null)
+        {
+            _viewModel.ShowElementCount = _showElementCount;
+            _viewModel.ShowXmlSize = _showXmlSize;
+        }
+    }
+
     private IPluginHost? _host;
     private ClipInspectorViewModel? _viewModel;
+    private bool _showElementCount = true;
+    private bool _showXmlSize = true;
 
     public void Initialize(IPluginHost host)
     {
@@ -29,7 +58,11 @@ public void Initialize(IPluginHost host)
 
     public Control CreatePanel()
     {
-        _viewModel = new ClipInspectorViewModel();
+        _viewModel = new ClipInspectorViewModel
+        {
+            ShowElementCount = _showElementCount,
+            ShowXmlSize = _showXmlSize,
+        };
         _viewModel.Update(_host?.SelectedClip);
         return new ClipInspectorPanel { DataContext = _viewModel };
     }
diff --git a/src/SharpFM.Plugin.Sample/ClipInspectorViewModel.cs b/src/SharpFM.Plugin.Sample/ClipInspectorViewModel.cs
index fb3ad96..e4460f5 100644
--- a/src/SharpFM.Plugin.Sample/ClipInspectorViewModel.cs
+++ b/src/SharpFM.Plugin.Sample/ClipInspectorViewModel.cs
@@ -30,6 +30,12 @@ private void Notify([CallerMemberName] string name = "")
     private bool _hasClip;
     public bool HasClip { get => _hasClip; private set { _hasClip = value; Notify(); } }
 
+    private bool _showElementCount = true;
+    public bool ShowElementCount { get => _showElementCount; set { _showElementCount = value; Notify(); } }
+
+    private bool _showXmlSize = true;
+    public bool ShowXmlSize { get => _showXmlSize; set { _showXmlSize = value; Notify(); } }
+
     public void Update(ClipData? clip)
     {
         if (clip is null)
diff --git a/src/SharpFM.Plugin.XmlViewer/XmlViewerPlugin.cs b/src/SharpFM.Plugin.XmlViewer/XmlViewerPlugin.cs
index 8e2af88..a773a8c 100644
--- a/src/SharpFM.Plugin.XmlViewer/XmlViewerPlugin.cs
+++ b/src/SharpFM.Plugin.XmlViewer/XmlViewerPlugin.cs
@@ -22,6 +22,8 @@ public class XmlViewerPlugin : IPanelPlugin
         [new PluginKeyBinding("Ctrl+Shift+X", "Toggle XML Viewer", () => { })];
 
     public IReadOnlyList<PluginMenuAction> MenuActions => [];
+    public PluginConfigSchema ConfigSchema => PluginConfigSchema.Empty;
+    public void OnConfigChanged(IReadOnlyDictionary<string, object?> values) { }
 
     public void Initialize(IPluginHost host)
     {
diff --git a/src/SharpFM.Plugin/IPlugin.cs b/src/SharpFM.Plugin/IPlugin.cs
index 5788939..dcf1105 100644
--- a/src/SharpFM.Plugin/IPlugin.cs
+++ b/src/SharpFM.Plugin/IPlugin.cs
@@ -46,4 +46,20 @@ public interface IPlugin : IDisposable
     /// as a submenu with "Toggle Panel" plus these custom actions.
     /// </summary>
     IReadOnlyList<PluginMenuAction> MenuActions { get; }
+
+    /// <summary>
+    /// Schema for user-tunable configuration values. The host persists these on the
+    /// plugin's behalf and renders a generic settings UI from the schema. Return
+    /// <see cref="PluginConfigSchema.Empty"/> if the plugin has no configuration.
+    /// </summary>
+    PluginConfigSchema ConfigSchema { get; }
+
+    /// <summary>
+    /// Called by the host with the current values for fields declared in
+    /// <see cref="ConfigSchema"/>: once after <see cref="Initialize"/> with the
+    /// persisted (or default) values, and again whenever the user saves edits in the
+    /// Plugin Manager. Keys match <see cref="PluginConfigField.Key"/>; values are
+    /// coerced to the CLR type implied by <see cref="PluginConfigField.Type"/>.
+    /// </summary>
+    void OnConfigChanged(IReadOnlyDictionary<string, object?> values);
 }
diff --git a/src/SharpFM.Plugin/PluginConfigSchema.cs b/src/SharpFM.Plugin/PluginConfigSchema.cs
new file mode 100644
index 0000000..b801fcb
--- /dev/null
+++ b/src/SharpFM.Plugin/PluginConfigSchema.cs
@@ -0,0 +1,48 @@
+using System;
+using System.Collections.Generic;
+
+namespace SharpFM.Plugin;
+
+/// <summary>
+/// Supported field types for a plugin configuration schema. The host renders a
+/// different control per type and coerces persisted values to the matching CLR type.
+/// </summary>
+public enum PluginConfigFieldType
+{
+    String,
+    MultilineString,
+    Bool,
+    Int,
+    Double,
+    Enum
+}
+
+/// <summary>
+/// A single configurable value declared by a plugin.
+/// </summary>
+/// <param name="Key">Dictionary key used when values are passed back to the plugin.</param>
+/// <param name="Label">Human-readable label shown in the settings UI.</param>
+/// <param name="Type">Field type — determines the rendered control and value coercion.</param>
+/// <param name="DefaultValue">
+/// Value returned when the field has never been set or the persisted value is invalid.
+/// Must be assignable to the CLR type implied by <paramref name="Type"/>.
+/// </param>
+/// <param name="Description">Optional caption shown beneath the control.</param>
+/// <param name="EnumValues">Allowed values when <paramref name="Type"/> is <see cref="PluginConfigFieldType.Enum"/>.</param>
+public sealed record PluginConfigField(
+    string Key,
+    string Label,
+    PluginConfigFieldType Type,
+    object? DefaultValue = null,
+    string? Description = null,
+    IReadOnlyList<string>? EnumValues = null);
+
+/// <summary>
+/// Describes a plugin's user-tunable configuration. The host uses this to
+/// persist values, generate a settings UI, and push the current values into the plugin.
+/// </summary>
+public sealed record PluginConfigSchema(IReadOnlyList<PluginConfigField> Fields)
+{
+    /// <summary>Schema for plugins with no configuration.</summary>
+    public static PluginConfigSchema Empty { get; } = new(Array.Empty<PluginConfigField>());
+}
diff --git a/src/SharpFM/App.axaml.cs b/src/SharpFM/App.axaml.cs
index 22b3ea3..dd02f7f 100644
--- a/src/SharpFM/App.axaml.cs
+++ b/src/SharpFM/App.axaml.cs
@@ -49,7 +49,8 @@ public override void OnFrameworkInitializationCompleted()
             // Load plugins
             var pluginHost = new PluginHost(viewModel, loggerFactory);
             var pluginUIHost = new PluginUIHost(pluginHost);
-            var pluginService = new PluginService(logger);
+            var pluginConfigService = new PluginConfigService(logger);
+            var pluginService = new PluginService(logger, pluginConfigService);
             pluginService.LoadPlugins(pluginUIHost);
 
             viewModel.AllPlugins = pluginService.AllPlugins;
@@ -62,7 +63,7 @@ public override void OnFrameworkInitializationCompleted()
 
             // Give the window access to plugin services for the manager dialog
             if (desktop.MainWindow is MainWindow mainWindow)
-                mainWindow.SetPluginServices(pluginService, pluginUIHost);
+                mainWindow.SetPluginServices(pluginService, pluginUIHost, pluginConfigService);
 
             desktop.MainWindow.DataContext = viewModel;
 
diff --git a/src/SharpFM/MainWindow.axaml.cs b/src/SharpFM/MainWindow.axaml.cs
index 8fc40aa..0927958 100644
--- a/src/SharpFM/MainWindow.axaml.cs
+++ b/src/SharpFM/MainWindow.axaml.cs
@@ -26,6 +26,7 @@ public partial class MainWindow : Window
     private TextMate.Installation? _scriptTextMateInstallation;
     private PluginService? _pluginService;
     private PluginUIHost? _pluginHost;
+    private PluginConfigService? _pluginConfigService;
 
     public MainWindow()
     {
@@ -58,10 +59,11 @@ public MainWindow()
         DataContextChanged += OnDataContextChanged;
     }
 
-    public void SetPluginServices(PluginService pluginService, PluginUIHost pluginHost)
+    public void SetPluginServices(PluginService pluginService, PluginUIHost pluginHost, PluginConfigService pluginConfigService)
     {
         _pluginService = pluginService;
         _pluginHost = pluginHost;
+        _pluginConfigService = pluginConfigService;
     }
 
     private void OnDataContextChanged(object? sender, EventArgs e)
@@ -229,11 +231,11 @@ private void UpdatePluginPanelContent()
 
     private void ShowPluginManager()
     {
-        if (_pluginService is null || _pluginHost is null) return;
+        if (_pluginService is null || _pluginHost is null || _pluginConfigService is null) return;
         if (DataContext is not MainWindowViewModel vm) return;
 
         var window = new PluginManagerWindow();
-        window.Configure(_pluginService, _pluginHost, vm);
+        window.Configure(_pluginService, _pluginHost, vm, _pluginConfigService);
         window.ShowDialog(this);
     }
 
diff --git a/src/SharpFM/PluginManager/PluginConfigDialog.axaml b/src/SharpFM/PluginManager/PluginConfigDialog.axaml
new file mode 100644
index 0000000..80c6e6a
--- /dev/null
+++ b/src/SharpFM/PluginManager/PluginConfigDialog.axaml
@@ -0,0 +1,33 @@
+<Window
+    xmlns="https://github.com/avaloniaui"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    x:Class="SharpFM.PluginManager.PluginConfigDialog"
+    Width="500"
+    Height="520"
+    CanResize="True"
+    WindowStartupLocation="CenterOwner">
+
+    <Grid Margin="16" RowDefinitions="Auto,*,Auto">
+        <TextBlock
+            Grid.Row="0"
+            x:Name="headerText"
+            Classes="Fluent2Subtitle"
+            Margin="0,0,0,12" />
+
+        <Border Grid.Row="1" Classes="Fluent2SurfaceElevated">
+            <ScrollViewer Padding="12">
+                <StackPanel x:Name="fieldsPanel" Spacing="12" />
+            </ScrollViewer>
+        </Border>
+
+        <StackPanel
+            Grid.Row="2"
+            Orientation="Horizontal"
+            HorizontalAlignment="Right"
+            Spacing="8"
+            Margin="0,12,0,0">
+            <Button x:Name="cancelButton" Classes="Fluent2" Content="Cancel" />
+            <Button x:Name="okButton" Classes="Fluent2Primary" Content="OK" />
+        </StackPanel>
+    </Grid>
+</Window>
diff --git a/src/SharpFM/PluginManager/PluginConfigDialog.axaml.cs b/src/SharpFM/PluginManager/PluginConfigDialog.axaml.cs
new file mode 100644
index 0000000..756da37
--- /dev/null
+++ b/src/SharpFM/PluginManager/PluginConfigDialog.axaml.cs
@@ -0,0 +1,158 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Avalonia.Controls;
+using Avalonia.Layout;
+using Avalonia.Markup.Xaml;
+using SharpFM.Plugin;
+
+namespace SharpFM.PluginManager;
+
+[ExcludeFromCodeCoverage]
+public partial class PluginConfigDialog : Window
+{
+    private readonly Dictionary<string, Func<object?>> _readers = new(StringComparer.Ordinal);
+    private Dictionary<string, object?>? _result;
+
+    public PluginConfigDialog()
+    {
+        InitializeComponent();
+    }
+
+    private void InitializeComponent() => AvaloniaXamlLoader.Load(this);
+
+    public static async System.Threading.Tasks.Task<IReadOnlyDictionary<string, object?>?> ShowAsync(
+        Window owner,
+        string pluginDisplayName,
+        PluginConfigSchema schema,
+        IReadOnlyDictionary<string, object?> currentValues)
+    {
+        var dialog = new PluginConfigDialog();
+        dialog.Build(pluginDisplayName, schema, currentValues);
+        await dialog.ShowDialog(owner);
+        return dialog._result;
+    }
+
+    private void Build(string pluginDisplayName, PluginConfigSchema schema, IReadOnlyDictionary<string, object?> currentValues)
+    {
+        Title = $"Configure {pluginDisplayName}";
+        var header = this.FindControl<TextBlock>("headerText");
+        if (header is not null) header.Text = pluginDisplayName;
+
+        var panel = this.FindControl<StackPanel>("fieldsPanel");
+        if (panel is not null)
+        {
+            foreach (var field in schema.Fields)
+            {
+                currentValues.TryGetValue(field.Key, out var current);
+                panel.Children.Add(BuildFieldControl(field, current));
+            }
+        }
+
+        var ok = this.FindControl<Button>("okButton");
+        var cancel = this.FindControl<Button>("cancelButton");
+        if (ok is not null) ok.Click += (_, _) => { _result = Collect(schema); Close(); };
+        if (cancel is not null) cancel.Click += (_, _) => { _result = null; Close(); };
+    }
+
+    private Control BuildFieldControl(PluginConfigField field, object? current)
+    {
+        var container = new StackPanel { Spacing = 4, Orientation = Orientation.Vertical };
+        container.Children.Add(new TextBlock { Text = field.Label, FontWeight = Avalonia.Media.FontWeight.SemiBold });
+
+        Control editor;
+        switch (field.Type)
+        {
+            case PluginConfigFieldType.String:
+            {
+                var tb = new TextBox { Text = current?.ToString() ?? string.Empty };
+                _readers[field.Key] = () => tb.Text ?? string.Empty;
+                editor = tb;
+                break;
+            }
+            case PluginConfigFieldType.MultilineString:
+            {
+                var tb = new TextBox
+                {
+                    Text = current?.ToString() ?? string.Empty,
+                    AcceptsReturn = true,
+                    TextWrapping = Avalonia.Media.TextWrapping.Wrap,
+                    MinHeight = 100,
+                };
+                _readers[field.Key] = () => tb.Text ?? string.Empty;
+                editor = tb;
+                break;
+            }
+            case PluginConfigFieldType.Bool:
+            {
+                var cb = new CheckBox { IsChecked = current is bool b && b };
+                _readers[field.Key] = () => cb.IsChecked ?? false;
+                editor = cb;
+                break;
+            }
+            case PluginConfigFieldType.Int:
+            {
+                var nud = new NumericUpDown
+                {
+                    Value = current is int i ? (decimal?)i : null,
+                    Increment = 1m,
+                    FormatString = "0",
+                };
+                _readers[field.Key] = () => nud.Value is { } v ? (object)(int)v : null;
+                editor = nud;
+                break;
+            }
+            case PluginConfigFieldType.Double:
+            {
+                var nud = new NumericUpDown
+                {
+                    Value = current is double d ? (decimal?)(decimal)d : null,
+                    Increment = 0.1m,
+                };
+                _readers[field.Key] = () => nud.Value is { } v ? (object)(double)v : null;
+                editor = nud;
+                break;
+            }
+            case PluginConfigFieldType.Enum:
+            {
+                var combo = new ComboBox();
+                if (field.EnumValues is not null)
+                {
+                    foreach (var v in field.EnumValues) combo.Items.Add(v);
+                    combo.SelectedItem = current as string ?? field.DefaultValue as string;
+                }
+                _readers[field.Key] = () => combo.SelectedItem as string;
+                editor = combo;
+                break;
+            }
+            default:
+                editor = new TextBlock { Text = $"(unsupported field type: {field.Type})" };
+                break;
+        }
+
+        container.Children.Add(editor);
+
+        if (!string.IsNullOrWhiteSpace(field.Description))
+        {
+            container.Children.Add(new TextBlock
+            {
+                Text = field.Description,
+                Classes = { "Fluent2Caption" },
+                Opacity = 0.7,
+            });
+        }
+
+        return container;
+    }
+
+    private Dictionary<string, object?> Collect(PluginConfigSchema schema)
+    {
+        var values = new Dictionary<string, object?>(StringComparer.Ordinal);
+        foreach (var field in schema.Fields)
+        {
+            if (_readers.TryGetValue(field.Key, out var reader))
+                values[field.Key] = reader();
+        }
+        return values;
+    }
+}
diff --git a/src/SharpFM/PluginManager/PluginManagerViewModel.cs b/src/SharpFM/PluginManager/PluginManagerViewModel.cs
index 2252bcf..f6553e4 100644
--- a/src/SharpFM/PluginManager/PluginManagerViewModel.cs
+++ b/src/SharpFM/PluginManager/PluginManagerViewModel.cs
@@ -18,6 +18,7 @@ private void Notify([CallerMemberName] string name = "") =>
     public string Description => Plugin.Description;
     public string PluginVersion => Plugin.Version;
     public string AssemblyName => Plugin.GetType().Assembly.GetName().Name ?? "(unknown)";
+    public bool CanConfigure => Plugin.ConfigSchema.Fields.Count > 0;
 
     private bool _isActive;
     public bool IsActive
@@ -45,10 +46,17 @@ private void Notify([CallerMemberName] string name = "") =>
     public PluginEntry? SelectedPlugin
     {
         get => _selectedPlugin;
-        set { _selectedPlugin = value; Notify(); Notify(nameof(HasSelection)); }
+        set
+        {
+            _selectedPlugin = value;
+            Notify();
+            Notify(nameof(HasSelection));
+            Notify(nameof(CanConfigureSelected));
+        }
     }
 
     public bool HasSelection => _selectedPlugin is not null;
+    public bool CanConfigureSelected => _selectedPlugin?.CanConfigure ?? false;
 
     public void Refresh(IReadOnlyList<IPlugin> allPlugins, string? activePluginId)
     {
diff --git a/src/SharpFM/PluginManager/PluginManagerWindow.axaml b/src/SharpFM/PluginManager/PluginManagerWindow.axaml
index 6b3276e..e7eea37 100644
--- a/src/SharpFM/PluginManager/PluginManagerWindow.axaml
+++ b/src/SharpFM/PluginManager/PluginManagerWindow.axaml
@@ -63,6 +63,8 @@
         <!-- Actions -->
         <StackPanel Grid.Row="1" Orientation="Horizontal" HorizontalAlignment="Right" Spacing="8">
             <Button x:Name="installButton" Classes="Fluent2" Content="Install from File..." />
+            <Button x:Name="configureButton" Classes="Fluent2" Content="Configure..."
+                    IsEnabled="{Binding CanConfigureSelected}" />
             <Button x:Name="removeButton" Classes="Fluent2" Content="Remove"
                     IsEnabled="{Binding HasSelection}" />
             <Button x:Name="closeButton" Classes="Fluent2Primary" Content="Close" />
diff --git a/src/SharpFM/PluginManager/PluginManagerWindow.axaml.cs b/src/SharpFM/PluginManager/PluginManagerWindow.axaml.cs
index 49bb5f6..690feec 100644
--- a/src/SharpFM/PluginManager/PluginManagerWindow.axaml.cs
+++ b/src/SharpFM/PluginManager/PluginManagerWindow.axaml.cs
@@ -17,6 +17,7 @@ public partial class PluginManagerWindow : Window
     private PluginService? _pluginService;
     private PluginUIHost? _host;
     private MainWindowViewModel? _mainVm;
+    private PluginConfigService? _configService;
 
     public PluginManagerWindow()
     {
@@ -24,19 +25,22 @@ public PluginManagerWindow()
         DataContext = _viewModel;
 
         var install = this.FindControl<Button>("installButton");
+        var configure = this.FindControl<Button>("configureButton");
         var remove = this.FindControl<Button>("removeButton");
         var close = this.FindControl<Button>("closeButton");
 
         if (install is not null) install.Click += OnInstall;
+        if (configure is not null) configure.Click += OnConfigure;
         if (remove is not null) remove.Click += OnRemove;
         if (close is not null) close.Click += (_, _) => Close();
     }
 
-    public void Configure(PluginService pluginService, PluginUIHost host, MainWindowViewModel mainVm)
+    public void Configure(PluginService pluginService, PluginUIHost host, MainWindowViewModel mainVm, PluginConfigService configService)
     {
         _pluginService = pluginService;
         _host = host;
         _mainVm = mainVm;
+        _configService = configService;
         _viewModel.Refresh(pluginService.AllPlugins, host.ActivePluginId);
     }
 
@@ -64,6 +68,22 @@ private async void OnInstall(object? sender, Avalonia.Interactivity.RoutedEventA
         }
     }
 
+    private async void OnConfigure(object? sender, Avalonia.Interactivity.RoutedEventArgs e)
+    {
+        if (_configService is null) return;
+        var entry = _viewModel.SelectedPlugin;
+        if (entry is null || !entry.CanConfigure) return;
+
+        var plugin = entry.Plugin;
+        var schema = plugin.ConfigSchema;
+        var current = _configService.Load(plugin.Id, schema);
+        var edited = await PluginConfigDialog.ShowAsync(this, plugin.DisplayName, schema, current);
+        if (edited is null) return;
+
+        _configService.Save(plugin.Id, schema, edited);
+        _configService.Apply(plugin);
+    }
+
     private void OnRemove(object? sender, Avalonia.Interactivity.RoutedEventArgs e)
     {
         if (_pluginService is null || _host is null || _mainVm is null) return;
diff --git a/src/SharpFM/Services/PluginConfigService.cs b/src/SharpFM/Services/PluginConfigService.cs
new file mode 100644
index 0000000..f6232bb
--- /dev/null
+++ b/src/SharpFM/Services/PluginConfigService.cs
@@ -0,0 +1,197 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using SharpFM.Plugin;
+
+namespace SharpFM.Services;
+
+/// <summary>
+/// Persists plugin configuration values as per-plugin JSON files under
+/// <c>%LocalAppData%/SharpFM/plugin-config/</c>. The service validates and coerces
+/// values against the caller-supplied <see cref="PluginConfigSchema"/> on every load
+/// so a drifted or hand-edited file can never crash the host.
+/// </summary>
+public class PluginConfigService
+{
+    private readonly ILogger _logger;
+
+    public string ConfigDirectory { get; }
+
+    public PluginConfigService(ILogger logger)
+        : this(logger, DefaultDirectory())
+    {
+    }
+
+    public PluginConfigService(ILogger logger, string configDirectory)
+    {
+        _logger = logger;
+        ConfigDirectory = configDirectory;
+    }
+
+    private static string DefaultDirectory() => Path.Combine(
+        Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+        "SharpFM", "plugin-config");
+
+    /// <summary>
+    /// Load configuration values for <paramref name="pluginId"/> against
+    /// <paramref name="schema"/>. Missing, malformed, or type-incompatible values
+    /// fall back to the field's <see cref="PluginConfigField.DefaultValue"/>. Keys in
+    /// the file that are not in the schema are dropped.
+    /// </summary>
+    public IReadOnlyDictionary<string, object?> Load(string pluginId, PluginConfigSchema schema)
+    {
+        var path = GetConfigPath(pluginId);
+        Dictionary<string, JsonElement>? raw = null;
+        if (File.Exists(path))
+        {
+            try
+            {
+                var text = File.ReadAllText(path);
+                raw = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(text);
+            }
+            catch (Exception ex)
+            {
+                _logger.LogWarning(ex, "Malformed plugin config at {Path}; falling back to defaults.", path);
+            }
+        }
+
+        var result = new Dictionary<string, object?>(StringComparer.Ordinal);
+        foreach (var field in schema.Fields)
+        {
+            if (raw is not null && raw.TryGetValue(field.Key, out var element)
+                && TryCoerce(element, field, out var coerced))
+            {
+                result[field.Key] = coerced;
+            }
+            else
+            {
+                if (raw is not null && raw.ContainsKey(field.Key))
+                {
+                    _logger.LogWarning(
+                        "Plugin config field {Key} for {PluginId} has an invalid value; using default.",
+                        field.Key, pluginId);
+                }
+                result[field.Key] = field.DefaultValue;
+            }
+        }
+        return result;
+    }
+
+    /// <summary>
+    /// Load the persisted (or default) values for <paramref name="plugin"/> and push
+    /// them into <see cref="IPlugin.OnConfigChanged"/>. No-op if the plugin declares
+    /// an empty schema. Exceptions from the plugin are caught and logged so one bad
+    /// plugin cannot abort host startup.
+    /// </summary>
+    public void Apply(IPlugin plugin)
+    {
+        var schema = plugin.ConfigSchema;
+        if (schema.Fields.Count == 0) return;
+
+        var values = Load(plugin.Id, schema);
+        try
+        {
+            plugin.OnConfigChanged(values);
+        }
+        catch (Exception ex)
+        {
+            _logger.LogWarning(ex, "Plugin {Id} threw from OnConfigChanged; continuing.", plugin.Id);
+        }
+    }
+
+    /// <summary>
+    /// Persist <paramref name="values"/> for <paramref name="pluginId"/>. Only keys
+    /// declared in <paramref name="schema"/> are written — extra keys are dropped.
+    /// </summary>
+    public void Save(string pluginId, PluginConfigSchema schema, IReadOnlyDictionary<string, object?> values)
+    {
+        Directory.CreateDirectory(ConfigDirectory);
+        var toWrite = new Dictionary<string, object?>(StringComparer.Ordinal);
+        foreach (var field in schema.Fields)
+        {
+            if (values.TryGetValue(field.Key, out var v))
+                toWrite[field.Key] = v;
+        }
+
+        var path = GetConfigPath(pluginId);
+        var text = JsonSerializer.Serialize(toWrite, new JsonSerializerOptions { WriteIndented = true });
+        File.WriteAllText(path, text);
+    }
+
+    /// <summary>Path to the config file for a given plugin id. Sanitized so that
+    /// ids containing path separators or other unsafe characters cannot escape
+    /// <see cref="ConfigDirectory"/>.</summary>
+    public string GetConfigPath(string pluginId)
+    {
+        var safe = SanitizeId(pluginId);
+        return Path.Combine(ConfigDirectory, safe + ".json");
+    }
+
+    private static string SanitizeId(string pluginId)
+    {
+        if (string.IsNullOrWhiteSpace(pluginId))
+            return "_";
+
+        var invalid = Path.GetInvalidFileNameChars();
+        var chars = pluginId.Select(c =>
+            invalid.Contains(c) || c == '.' || c == Path.DirectorySeparatorChar || c == Path.AltDirectorySeparatorChar
+                ? '_' : c).ToArray();
+        var result = new string(chars).Trim('.', '_', ' ');
+        return string.IsNullOrEmpty(result) ? "_" : result;
+    }
+
+    private static bool TryCoerce(JsonElement element, PluginConfigField field, out object? value)
+    {
+        value = null;
+        try
+        {
+            switch (field.Type)
+            {
+                case PluginConfigFieldType.String:
+                case PluginConfigFieldType.MultilineString:
+                    if (element.ValueKind == JsonValueKind.String)
+                    {
+                        value = element.GetString();
+                        return true;
+                    }
+                    return false;
+                case PluginConfigFieldType.Bool:
+                    if (element.ValueKind is JsonValueKind.True or JsonValueKind.False)
+                    {
+                        value = element.GetBoolean();
+                        return true;
+                    }
+                    return false;
+                case PluginConfigFieldType.Int:
+                    if (element.ValueKind == JsonValueKind.Number && element.TryGetInt32(out var i))
+                    {
+                        value = i;
+                        return true;
+                    }
+                    return false;
+                case PluginConfigFieldType.Double:
+                    if (element.ValueKind == JsonValueKind.Number && element.TryGetDouble(out var d))
+                    {
+                        value = d;
+                        return true;
+                    }
+                    return false;
+                case PluginConfigFieldType.Enum:
+                    if (element.ValueKind != JsonValueKind.String) return false;
+                    var s = element.GetString();
+                    if (field.EnumValues is null || !field.EnumValues.Contains(s)) return false;
+                    value = s;
+                    return true;
+                default:
+                    return false;
+            }
+        }
+        catch
+        {
+            return false;
+        }
+    }
+}
diff --git a/src/SharpFM/Services/PluginService.cs b/src/SharpFM/Services/PluginService.cs
index e5f6fb3..dadab9b 100644
--- a/src/SharpFM/Services/PluginService.cs
+++ b/src/SharpFM/Services/PluginService.cs
@@ -15,6 +15,7 @@ namespace SharpFM.Services;
 public class PluginService
 {
     private readonly ILogger _logger;
+    private readonly PluginConfigService _configService;
     private readonly List<IPlugin> _plugins = [];
 
     /// <summary>All loaded plugins.</summary>
@@ -22,14 +23,15 @@ public class PluginService
 
     public string PluginsDirectory { get; }
 
-    public PluginService(ILogger logger)
-        : this(logger, Path.Combine(AppContext.BaseDirectory, "plugins"))
+    public PluginService(ILogger logger, PluginConfigService configService)
+        : this(logger, configService, Path.Combine(AppContext.BaseDirectory, "plugins"))
     {
     }
 
-    public PluginService(ILogger logger, string pluginsDirectory)
+    public PluginService(ILogger logger, PluginConfigService configService, string pluginsDirectory)
     {
         _logger = logger;
+        _configService = configService;
         PluginsDirectory = pluginsDirectory;
     }
 
@@ -187,6 +189,7 @@ private void LoadPluginAssembly(string dllPath, IPluginHost host)
             if (Activator.CreateInstance(type) is not IPlugin plugin) continue;
 
             plugin.Initialize(host);
+            _configService.Apply(plugin);
             _plugins.Add(plugin);
 
             _logger.LogInformation("Loaded plugin: {Id} ({DisplayName})", plugin.Id, plugin.DisplayName);
diff --git a/tests/SharpFM.Plugin.Tests/PluginConfigSchemaTests.cs b/tests/SharpFM.Plugin.Tests/PluginConfigSchemaTests.cs
new file mode 100644
index 0000000..a755e6a
--- /dev/null
+++ b/tests/SharpFM.Plugin.Tests/PluginConfigSchemaTests.cs
@@ -0,0 +1,46 @@
+using SharpFM.Plugin;
+using Xunit;
+
+namespace SharpFM.Plugin.Tests;
+
+public class PluginConfigSchemaTests
+{
+    [Fact]
+    public void Empty_HasZeroFields()
+    {
+        Assert.Empty(PluginConfigSchema.Empty.Fields);
+    }
+
+    [Fact]
+    public void Empty_IsStableSingleton()
+    {
+        // Same reference on every access — callers can compare without allocation concerns.
+        Assert.Same(PluginConfigSchema.Empty, PluginConfigSchema.Empty);
+    }
+
+    [Theory]
+    [InlineData(PluginConfigFieldType.String)]
+    [InlineData(PluginConfigFieldType.MultilineString)]
+    [InlineData(PluginConfigFieldType.Bool)]
+    [InlineData(PluginConfigFieldType.Int)]
+    [InlineData(PluginConfigFieldType.Double)]
+    [InlineData(PluginConfigFieldType.Enum)]
+    public void Field_RoundTripsAllProperties(PluginConfigFieldType type)
+    {
+        var enumValues = type == PluginConfigFieldType.Enum ? new[] { "a", "b" } : null;
+        var field = new PluginConfigField(
+            Key: "k",
+            Label: "My Label",
+            Type: type,
+            DefaultValue: "def",
+            Description: "desc",
+            EnumValues: enumValues);
+
+        Assert.Equal("k", field.Key);
+        Assert.Equal("My Label", field.Label);
+        Assert.Equal(type, field.Type);
+        Assert.Equal("def", field.DefaultValue);
+        Assert.Equal("desc", field.Description);
+        Assert.Equal(enumValues, field.EnumValues);
+    }
+}
diff --git a/tests/SharpFM.Plugin.Tests/PluginConfigServiceTests.cs b/tests/SharpFM.Plugin.Tests/PluginConfigServiceTests.cs
new file mode 100644
index 0000000..b0bb304
--- /dev/null
+++ b/tests/SharpFM.Plugin.Tests/PluginConfigServiceTests.cs
@@ -0,0 +1,413 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Avalonia.Controls;
+using Microsoft.Extensions.Logging.Abstractions;
+using SharpFM.Plugin;
+using SharpFM.Plugin.UI;
+using SharpFM.Services;
+using Xunit;
+
+namespace SharpFM.Plugin.Tests;
+
+public class PluginConfigServiceTests : IDisposable
+{
+    private readonly string _dir;
+    private readonly PluginConfigService _svc;
+
+    public PluginConfigServiceTests()
+    {
+        _dir = Path.Combine(Path.GetTempPath(), $"sharpfm-cfg-{Guid.NewGuid()}");
+        _svc = new PluginConfigService(NullLogger.Instance, _dir);
+    }
+
+    public void Dispose()
+    {
+        if (Directory.Exists(_dir)) Directory.Delete(_dir, recursive: true);
+    }
+
+    // ---------------- Happy-path ----------------
+
+    [Fact]
+    public void Load_WithNoFile_ReturnsDefaults()
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("s", "S", PluginConfigFieldType.String, "hello"),
+            new PluginConfigField("n", "N", PluginConfigFieldType.Int, 7),
+        });
+
+        var values = _svc.Load("p1", schema);
+
+        Assert.Equal("hello", values["s"]);
+        Assert.Equal(7, values["n"]);
+        Assert.False(File.Exists(_svc.GetConfigPath("p1")), "Load must not create a file.");
+    }
+
+    [Theory]
+    [InlineData(PluginConfigFieldType.String, "hello world")]
+    [InlineData(PluginConfigFieldType.MultilineString, "line1\nline2")]
+    [InlineData(PluginConfigFieldType.Bool, true)]
+    [InlineData(PluginConfigFieldType.Bool, false)]
+    [InlineData(PluginConfigFieldType.Int, 42)]
+    [InlineData(PluginConfigFieldType.Double, 3.14)]
+    public void Save_ThenLoad_ReturnsSameValue(PluginConfigFieldType type, object value)
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("k", "K", type, DefaultValue: GetDefault(type)),
+        });
+
+        _svc.Save("p1", schema, new Dictionary<string, object?> { ["k"] = value });
+        var loaded = _svc.Load("p1", schema);
+
+        Assert.Equal(value, loaded["k"]);
+    }
+
+    [Fact]
+    public void Save_ThenLoad_Enum_ReturnsSameValue()
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("color", "Color", PluginConfigFieldType.Enum,
+                DefaultValue: "red", EnumValues: new[] { "red", "green", "blue" }),
+        });
+
+        _svc.Save("p1", schema, new Dictionary<string, object?> { ["color"] = "green" });
+        var loaded = _svc.Load("p1", schema);
+
+        Assert.Equal("green", loaded["color"]);
+    }
+
+    [Fact]
+    public void Save_WritesJsonAtExpectedPath()
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("s", "S", PluginConfigFieldType.String, ""),
+        });
+
+        _svc.Save("my-plugin", schema, new Dictionary<string, object?> { ["s"] = "v" });
+
+        var path = _svc.GetConfigPath("my-plugin");
+        Assert.True(File.Exists(path));
+        Assert.Contains("\"s\"", File.ReadAllText(path));
+    }
+
+    [Fact]
+    public void TwoPlugins_WriteIndependentFiles()
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("s", "S", PluginConfigFieldType.String, "def"),
+        });
+
+        _svc.Save("a", schema, new Dictionary<string, object?> { ["s"] = "va" });
+        _svc.Save("b", schema, new Dictionary<string, object?> { ["s"] = "vb" });
+
+        Assert.Equal("va", _svc.Load("a", schema)["s"]);
+        Assert.Equal("vb", _svc.Load("b", schema)["s"]);
+    }
+
+    // ---------------- Regression guards ----------------
+
+    [Fact]
+    public void Load_WithMalformedJson_ReturnsDefaults_DoesNotThrow()
+    {
+        Directory.CreateDirectory(_dir);
+        File.WriteAllText(Path.Combine(_dir, "p1.json"), "{ not valid json");
+
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("s", "S", PluginConfigFieldType.String, "fallback"),
+        });
+
+        var values = _svc.Load("p1", schema);
+        Assert.Equal("fallback", values["s"]);
+    }
+
+    [Fact]
+    public void Load_WithMissingField_FillsFromDefault()
+    {
+        Directory.CreateDirectory(_dir);
+        File.WriteAllText(Path.Combine(_dir, "p1.json"), "{\"a\": \"persisted\"}");
+
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("a", "A", PluginConfigFieldType.String, "defA"),
+            new PluginConfigField("b", "B", PluginConfigFieldType.String, "defB"),
+        });
+
+        var values = _svc.Load("p1", schema);
+        Assert.Equal("persisted", values["a"]);
+        Assert.Equal("defB", values["b"]);
+    }
+
+    [Fact]
+    public void Load_WithWrongType_FallsBackToDefault_OtherFieldsIntact()
+    {
+        Directory.CreateDirectory(_dir);
+        File.WriteAllText(Path.Combine(_dir, "p1.json"),
+            "{\"num\": \"not a number\", \"name\": \"ok\"}");
+
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("num", "Num", PluginConfigFieldType.Int, 99),
+            new PluginConfigField("name", "Name", PluginConfigFieldType.String, "def"),
+        });
+
+        var values = _svc.Load("p1", schema);
+        Assert.Equal(99, values["num"]);
+        Assert.Equal("ok", values["name"]);
+    }
+
+    [Fact]
+    public void Load_WithUnknownKey_DropsIt_AndSaveDoesNotReWriteIt()
+    {
+        Directory.CreateDirectory(_dir);
+        var path = Path.Combine(_dir, "p1.json");
+        File.WriteAllText(path, "{\"known\": \"v\", \"old-renamed\": \"leftover\"}");
+
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("known", "Known", PluginConfigFieldType.String, "def"),
+        });
+
+        var values = _svc.Load("p1", schema);
+        Assert.False(values.ContainsKey("old-renamed"));
+        Assert.Equal("v", values["known"]);
+
+        _svc.Save("p1", schema, values);
+        var text = File.ReadAllText(path);
+        Assert.DoesNotContain("old-renamed", text);
+    }
+
+    [Fact]
+    public void Load_EnumValueNotInAllowedList_FallsBackToDefault()
+    {
+        Directory.CreateDirectory(_dir);
+        File.WriteAllText(Path.Combine(_dir, "p1.json"), "{\"color\": \"puce\"}");
+
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("color", "C", PluginConfigFieldType.Enum,
+                DefaultValue: "red", EnumValues: new[] { "red", "green", "blue" }),
+        });
+
+        var values = _svc.Load("p1", schema);
+        Assert.Equal("red", values["color"]);
+    }
+
+    [Theory]
+    [InlineData("../evil")]
+    [InlineData("foo/bar")]
+    [InlineData("foo\\bar")]
+    [InlineData(":weird")]
+    [InlineData("")]
+    [InlineData("   ")]
+    [InlineData("....")]
+    public void Save_SanitizesPluginId_CannotEscapeConfigDirectory(string pluginId)
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("s", "S", PluginConfigFieldType.String, "def"),
+        });
+        _svc.Save(pluginId, schema, new Dictionary<string, object?> { ["s"] = "v" });
+
+        var path = _svc.GetConfigPath(pluginId);
+        var fullConfigDir = Path.GetFullPath(_dir);
+        var fullFile = Path.GetFullPath(path);
+
+        Assert.StartsWith(fullConfigDir + Path.DirectorySeparatorChar, fullFile);
+
+        // Save/Load still works for the sanitized name.
+        var loaded = _svc.Load(pluginId, schema);
+        Assert.Equal("v", loaded["s"]);
+    }
+
+    [Fact]
+    public void ConfigDirectory_IsCreatedOnFirstSave()
+    {
+        Assert.False(Directory.Exists(_dir));
+
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("s", "S", PluginConfigFieldType.String, ""),
+        });
+        _svc.Save("p1", schema, new Dictionary<string, object?> { ["s"] = "v" });
+
+        Assert.True(Directory.Exists(_dir));
+    }
+
+    [Fact]
+    public void Save_OnlyPersistsSchemaKeys()
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("keep", "K", PluginConfigFieldType.String, ""),
+        });
+
+        _svc.Save("p1", schema, new Dictionary<string, object?>
+        {
+            ["keep"] = "yes",
+            ["drop-me"] = "leaked",
+        });
+
+        var text = File.ReadAllText(_svc.GetConfigPath("p1"));
+        Assert.Contains("keep", text);
+        Assert.DoesNotContain("drop-me", text);
+        Assert.DoesNotContain("leaked", text);
+    }
+
+    // ---------------- Lifecycle (Apply) ----------------
+
+    [Fact]
+    public void Apply_PluginWithSchema_ReceivesInitialValues()
+    {
+        var plugin = new FakePlugin
+        {
+            ConfigSchemaOverride = new PluginConfigSchema(new[]
+            {
+                new PluginConfigField("s", "S", PluginConfigFieldType.String, "defaultS"),
+                new PluginConfigField("n", "N", PluginConfigFieldType.Int, 10),
+            }),
+        };
+        plugin.Initialize(null!);
+
+        _svc.Apply(plugin);
+
+        Assert.Equal(new[] { "Initialize", "OnConfigChanged" }, plugin.CallOrder);
+        Assert.NotNull(plugin.LastConfigValues);
+        Assert.Equal("defaultS", plugin.LastConfigValues!["s"]);
+        Assert.Equal(10, plugin.LastConfigValues!["n"]);
+    }
+
+    [Fact]
+    public void Apply_PluginWithPersistedConfig_ReceivesStoredValues()
+    {
+        Directory.CreateDirectory(_dir);
+        File.WriteAllText(Path.Combine(_dir, "fake.json"), "{\"n\": 42}");
+
+        var plugin = new FakePlugin
+        {
+            Id = "fake",
+            ConfigSchemaOverride = new PluginConfigSchema(new[]
+            {
+                new PluginConfigField("n", "N", PluginConfigFieldType.Int, 1),
+            }),
+        };
+
+        _svc.Apply(plugin);
+
+        Assert.Equal(42, plugin.LastConfigValues!["n"]);
+    }
+
+    [Fact]
+    public void Apply_PluginWithEmptySchema_DoesNotInvokeOnConfigChanged_NorWriteFile()
+    {
+        var plugin = new FakePlugin { ConfigSchemaOverride = PluginConfigSchema.Empty };
+
+        _svc.Apply(plugin);
+
+        Assert.Null(plugin.LastConfigValues);
+        Assert.False(Directory.Exists(_dir));
+    }
+
+    [Fact]
+    public void Apply_PluginThrowsFromOnConfigChanged_DoesNotPropagate()
+    {
+        var plugin = new FakePlugin
+        {
+            ConfigSchemaOverride = new PluginConfigSchema(new[]
+            {
+                new PluginConfigField("s", "S", PluginConfigFieldType.String, "x"),
+            }),
+            ThrowOnConfigChanged = true,
+        };
+
+        // Must not throw — host must keep loading other plugins.
+        _svc.Apply(plugin);
+    }
+
+    [Fact]
+    public void SaveFromUi_Flow_PersistsAndIsReadableByFreshService()
+    {
+        var schema = new PluginConfigSchema(new[]
+        {
+            new PluginConfigField("s", "S", PluginConfigFieldType.String, "def"),
+        });
+
+        var plugin = new FakePlugin { Id = "ui-flow", ConfigSchemaOverride = schema };
+        var edited = new Dictionary<string, object?> { ["s"] = "new-value" };
+
+        _svc.Save(plugin.Id, schema, edited);
+        _svc.Apply(plugin);
+
+        Assert.Equal("new-value", plugin.LastConfigValues!["s"]);
+
+        var fresh = new PluginConfigService(NullLogger.Instance, _dir);
+        var reloaded = fresh.Load(plugin.Id, schema);
+        Assert.Equal("new-value", reloaded["s"]);
+    }
+
+    [Fact]
+    public void Apply_DoesNotRepeatedlyQueryConfigSchema()
+    {
+        // Guard against accidental per-call schema allocation in plugin authors'
+        // implementations becoming a repeated-read perf problem on the host.
+        var plugin = new FakePlugin
+        {
+            ConfigSchemaOverride = new PluginConfigSchema(new[]
+            {
+                new PluginConfigField("s", "S", PluginConfigFieldType.String, "x"),
+            }),
+        };
+
+        _svc.Apply(plugin);
+
+        Assert.InRange(plugin.ConfigSchemaReads, 1, 3);
+    }
+
+    // ---------------- Helpers ----------------
+
+    private static object GetDefault(PluginConfigFieldType t) => t switch
+    {
+        PluginConfigFieldType.String or PluginConfigFieldType.MultilineString => "",
+        PluginConfigFieldType.Bool => false,
+        PluginConfigFieldType.Int => 0,
+        PluginConfigFieldType.Double => 0.0,
+        _ => "",
+    };
+
+    private sealed class FakePlugin : IPlugin
+    {
+        public string Id { get; set; } = "fake";
+        public string DisplayName => "Fake";
+        public string Description => "";
+        public string Version => "0.0.0";
+        public IReadOnlyList<PluginKeyBinding> KeyBindings => [];
+        public IReadOnlyList<PluginMenuAction> MenuActions => [];
+
+        public PluginConfigSchema ConfigSchemaOverride { get; set; } = PluginConfigSchema.Empty;
+        public int ConfigSchemaReads;
+        public PluginConfigSchema ConfigSchema
+        {
+            get { ConfigSchemaReads++; return ConfigSchemaOverride; }
+        }
+
+        public bool ThrowOnConfigChanged { get; set; }
+        public IReadOnlyDictionary<string, object?>? LastConfigValues { get; private set; }
+        public List<string> CallOrder { get; } = new();
+
+        public void Initialize(IPluginHost host) => CallOrder.Add("Initialize");
+
+        public void OnConfigChanged(IReadOnlyDictionary<string, object?> values)
+        {
+            CallOrder.Add("OnConfigChanged");
+            LastConfigValues = values;
+            if (ThrowOnConfigChanged) throw new InvalidOperationException("boom");
+        }
+
+        public void Dispose() { }
+    }
+}
diff --git a/tests/SharpFM.Plugin.Tests/PluginManagerViewModelTests.cs b/tests/SharpFM.Plugin.Tests/PluginManagerViewModelTests.cs
index 8d0e02c..f90943c 100644
--- a/tests/SharpFM.Plugin.Tests/PluginManagerViewModelTests.cs
+++ b/tests/SharpFM.Plugin.Tests/PluginManagerViewModelTests.cs
@@ -16,6 +16,8 @@ private class StubPlugin : IPanelPlugin
         public string Version => "1.0.0-test";
         public IReadOnlyList<PluginKeyBinding> KeyBindings => [];
         public IReadOnlyList<PluginMenuAction> MenuActions => [];
+        public PluginConfigSchema ConfigSchema { get; set; } = PluginConfigSchema.Empty;
+        public void OnConfigChanged(IReadOnlyDictionary<string, object?> values) { }
         public Control CreatePanel() => new TextBlock();
         public void Initialize(IPluginHost host) { }
         public void Dispose() { }
diff --git a/tests/SharpFM.Plugin.Tests/PluginServiceInstallTests.cs b/tests/SharpFM.Plugin.Tests/PluginServiceInstallTests.cs
index 50b4102..0cb3162 100644
--- a/tests/SharpFM.Plugin.Tests/PluginServiceInstallTests.cs
+++ b/tests/SharpFM.Plugin.Tests/PluginServiceInstallTests.cs
@@ -1,5 +1,6 @@
 using System.IO;
 using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
 using SharpFM.Services;
 using Xunit;
 
@@ -10,7 +11,9 @@ public class PluginServiceInstallTests
     private static PluginService CreateService(string pluginsDir)
     {
         var logger = LoggerFactory.Create(_ => { }).CreateLogger<PluginService>();
-        return new PluginService(logger, pluginsDir);
+        var configDir = Path.Combine(Path.GetTempPath(), $"sharpfm-cfg-{Guid.NewGuid()}");
+        var configService = new PluginConfigService(NullLogger.Instance, configDir);
+        return new PluginService(logger, configService, pluginsDir);
     }
 
     [Fact]
diff --git a/tests/SharpFM.Plugin.Tests/PluginServiceTests.cs b/tests/SharpFM.Plugin.Tests/PluginServiceTests.cs
index f8d2455..fd18ac9 100644
--- a/tests/SharpFM.Plugin.Tests/PluginServiceTests.cs
+++ b/tests/SharpFM.Plugin.Tests/PluginServiceTests.cs
@@ -38,13 +38,17 @@ public class PluginServiceTests
     private static PluginService CreateService(string pluginsDir)
     {
         var logger = LoggerFactory.Create(_ => { }).CreateLogger<PluginService>();
-        return new PluginService(logger, pluginsDir);
+        var configDir = Path.Combine(Path.GetTempPath(), $"sharpfm-cfg-{Guid.NewGuid()}");
+        var configService = new PluginConfigService(NullLogger.Instance, configDir);
+        return new PluginService(logger, configService, pluginsDir);
     }
 
     [Fact]
     public void LoadPlugins_NoPluginsDir_LoadsZero()
     {
-        var service = new PluginService(NullLogger.Instance);
+        var configDir = Path.Combine(Path.GetTempPath(), $"sharpfm-cfg-{Guid.NewGuid()}");
+        var configService = new PluginConfigService(NullLogger.Instance, configDir);
+        var service = new PluginService(NullLogger.Instance, configService);
         var host = new MockPluginHost();
 
         // AppContext.BaseDirectory won't have a plugins/ dir in test
diff --git a/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs b/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs
index cbe74ad..6f106fd 100644
--- a/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs
+++ b/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs
@@ -273,6 +273,8 @@ private class StubPanelPlugin : IPanelPlugin
         public IReadOnlyList<PluginKeyBinding> TestKeyBindings { get; set; } = [];
         public IReadOnlyList<PluginKeyBinding> KeyBindings => TestKeyBindings;
         public IReadOnlyList<PluginMenuAction> MenuActions => [];
+        public PluginConfigSchema ConfigSchema => PluginConfigSchema.Empty;
+        public void OnConfigChanged(IReadOnlyDictionary<string, object?> values) { }
         public Control CreatePanel() => new TextBlock { Text = "stub" };
         public void Initialize(IPluginHost host) { }
         public void Dispose() { }

From ef9805f92b91a8fd4208848f7b4cc64cd4e049ed Mon Sep 17 00:00:00 2001
From: Nate Bross <nate@brosstribe.com>
Date: Wed, 22 Apr 2026 19:07:39 -0500
Subject: [PATCH 2/2] chore: silence CS0067 on IPluginHost mock events

IPluginHost requires SelectedClipChanged, ClipContentChanged, and
ClipCollectionChanged, but test mocks don't need to raise them. Scope
the suppression tightly with #pragma so it doesn't mask real issues.
---
 tests/SharpFM.Plugin.Tests/XmlViewerPluginTests.cs         | 2 ++
 tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/tests/SharpFM.Plugin.Tests/XmlViewerPluginTests.cs b/tests/SharpFM.Plugin.Tests/XmlViewerPluginTests.cs
index c411be3..b350db6 100644
--- a/tests/SharpFM.Plugin.Tests/XmlViewerPluginTests.cs
+++ b/tests/SharpFM.Plugin.Tests/XmlViewerPluginTests.cs
@@ -138,9 +138,11 @@ public class TrackingPluginHost : IPluginHost
     public IReadOnlyList<ClipData> AllClips { get; set; } = [];
     public string? LastUpdatedXml { get; private set; }
     public string? LastOriginPluginId { get; private set; }
+#pragma warning disable CS0067 // Events required by IPluginHost, not raised by this mock.
     public event EventHandler<ClipData?>? SelectedClipChanged;
     public event EventHandler<ClipContentChangedArgs>? ClipContentChanged;
     public event EventHandler? ClipCollectionChanged;
+#pragma warning restore CS0067
 
     public void UpdateSelectedClipXml(string xml, string originPluginId)
     {
diff --git a/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs b/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs
index 6f106fd..6dad2d1 100644
--- a/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs
+++ b/tests/SharpFM.Tests/ViewModels/MainWindowViewModelTests.cs
@@ -248,9 +248,11 @@ private class MockPluginHost : IPluginHost
     {
         public Model.ClipData? SelectedClip { get; set; }
         public IReadOnlyList<Model.ClipData> AllClips { get; set; } = [];
+#pragma warning disable CS0067 // Events required by IPluginHost, not raised by this mock.
         public event EventHandler<Model.ClipData?>? SelectedClipChanged;
         public event EventHandler<ClipContentChangedArgs>? ClipContentChanged;
         public event EventHandler? ClipCollectionChanged;
+#pragma warning restore CS0067
         public ILogger CreateLogger(string categoryName) => NullLogger.Instance;
         public Model.ClipData? GetClip(string clipName) => null;
         public void UpdateClipXml(string clipName, string xml, string originPluginId) { }