feat: expand plugin architecture with event, persistence, and transform types (#154)

## Summary
- Introduce `IPlugin` base interface with shared metadata and lifecycle
for all plugin types
- Add `IEventPlugin` — headless event handlers that react to host events
with no UI
- Add `IPersistencePlugin` + `IClipRepository` — pluggable storage
backends (cloud API, database, etc.)
- Add `IClipTransformPlugin` — modify clip XML during import/export
operations
- Refactor `ClipRepository` to implement `IClipRepository` with async
methods
- Refactor `MainWindowViewModel` to use `IClipRepository` abstraction
instead of concrete `ClipRepository`
- Expand `PluginService` for multi-type plugin discovery and
categorization
- Generalize Plugin Manager UI to display all plugin types with type
labels
- Extend `IPluginHost` with `AllClips`, `ClipCollectionChanged`, and
`ShowStatus`
- Add plugin development documentation in `docs/plugins/`

Author: fuzzzerd

docs/plugins/event-plugins.md

@@ -0,0 +1,72 @@
+# Event Plugins
+
+Event plugins are headless — they react to host events with no UI panel.
+
+## Interface
+
+```csharp
+public interface IEventPlugin : IPlugin { }
+```
+
+`IEventPlugin` is a marker interface. All behavior comes from subscribing to `IPluginHost` events in `Initialize()` and unsubscribing in `Dispose()`.
+
+## When to Use
+
+- Auto-formatters that reformat XML on clip selection
+- Linters that validate clip structure and post diagnostics
+- Sync agents that mirror clips to an external system
+- Analytics or telemetry
+
+## Available Events
+
+| Event | When |
+|-------|------|
+| `SelectedClipChanged` | User selects a different clip |
+| `ClipContentChanged` | Clip XML changes (user edit or plugin push) |
+| `ClipCollectionChanged` | Clips added, removed, or reloaded |
+
+## Host Capabilities
+
+- `AllClips` — read the full clip collection for bulk operations
+- `ShowStatus(message)` — display feedback in the status bar
+- `UpdateSelectedClipXml(xml, pluginId)` — push XML changes back to the editor
+
+## Example: Auto-Formatter
+
+```csharp
+public class AutoFormatPlugin : IEventPlugin
+{
+    public string Id => "auto-format";
+    public string DisplayName => "Auto Formatter";
+    public string Version => "1.0.0";
+    public IReadOnlyList<PluginKeyBinding> KeyBindings => [];
+    public IReadOnlyList<PluginMenuAction> MenuActions => [];
+
+    private IPluginHost? _host;
+
+    public void Initialize(IPluginHost host)
+    {
+        _host = host;
+        _host.SelectedClipChanged += OnClipChanged;
+    }
+
+    private void OnClipChanged(object? sender, ClipInfo? clip)
+    {
+        if (clip is null) return;
+        var formatted = FormatXml(clip.Xml);
+        if (formatted != clip.Xml)
+        {
+            _host!.UpdateSelectedClipXml(formatted, Id);
+            _host.ShowStatus("Clip auto-formatted");
+        }
+    }
+
+    private static string FormatXml(string xml) => xml; // your formatting logic
+
+    public void Dispose()
+    {
+        if (_host is not null)
+            _host.SelectedClipChanged -= OnClipChanged;
+    }
+}
+```

docs/plugins/host-api.md

@@ -0,0 +1,69 @@
+# IPluginHost API Reference
+
+The `IPluginHost` interface is provided to plugins during `Initialize()`. It exposes the host application's state and services.
+
+## Properties
+
+### `ClipInfo? SelectedClip`
+
+The currently selected clip, or `null` if nothing is selected. Returns a snapshot — reading it multiple times may return different instances if the clip changed.
+
+### `IReadOnlyList<ClipInfo> AllClips`
+
+All clips currently loaded in the application. Useful for plugins that operate across the full clip set (linters, search indexers, sync agents).
+
+## Events
+
+### `SelectedClipChanged`
+
+```csharp
+event EventHandler<ClipInfo?> SelectedClipChanged;
+```
+
+Raised when the user selects a different clip in the list. The argument is the new clip, or `null` if deselected.
+
+### `ClipContentChanged`
+
+```csharp
+event EventHandler<ClipContentChangedArgs> ClipContentChanged;
+```
+
+Raised when clip content changes. Check `args.Origin` to determine the source:
+- `"editor"` — user edited in the structured editor (debounced)
+- Plugin ID — a plugin pushed XML changes (immediate)
+
+```csharp
+public record ClipContentChangedArgs(ClipInfo Clip, string Origin, bool IsPartial);
+```
+
+`IsPartial` is `true` when the XML was produced from an incomplete parse (e.g., user is mid-edit in the script editor).
+
+### `ClipCollectionChanged`
+
+```csharp
+event EventHandler? ClipCollectionChanged;
+```
+
+Raised when clips are added, removed, or the collection is reloaded.
+
+## Methods
+
+### `UpdateSelectedClipXml(string xml, string originPluginId)`
+
+Replace the XML content of the currently selected clip. The host syncs the new XML back to the structured editor automatically. Pass your plugin's `Id` as `originPluginId` for origin tagging — you'll receive your own change back via `ClipContentChanged` but can skip it by checking `args.Origin == Id`.
+
+### `RefreshSelectedClip() -> ClipInfo?`
+
+Flush the editor's in-progress state to XML and return a fresh snapshot. Use this before reading `SelectedClip` if you need XML that reflects any uncommitted edits in the structured editors.
+
+### `ShowStatus(string message)`
+
+Display a message in the status bar. Use this for user-visible feedback. The message auto-clears after a few seconds.
+
+## ClipInfo
+
+```csharp
+public record ClipInfo(string Name, string ClipType, string Xml);
+```
+
+A read-only snapshot of clip metadata and content. `ClipType` is the FileMaker clipboard format (e.g., `"Mac-XMSS"` for script steps, `"Mac-XMTB"` for tables).

docs/plugins/overview.md

@@ -0,0 +1,51 @@
+# SharpFM Plugin System
+
+SharpFM supports four types of plugins, all sharing a common base interface (`IPlugin`) for metadata and lifecycle.
+
+## Plugin Types
+
+| Type | Interface | Purpose |
+|------|-----------|---------|
+| **Panel** | `IPanelPlugin` | Sidebar UI panels that display clip data |
+| **Event** | `IEventPlugin` | Headless handlers that react to host events |
+| **Persistence** | `IPersistencePlugin` | Alternative storage backends (cloud, database) |
+| **Transform** | `IClipTransformPlugin` | Modify clip XML during import/export |
+
+## Getting Started
+
+### 1. Create a Class Library
+
+Create a new .NET 8 class library and reference `SharpFM.Plugin`:
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="path/to/SharpFM.Plugin.csproj" />
+  </ItemGroup>
+</Project>
+```
+
+### 2. Implement a Plugin Interface
+
+Choose the interface that matches your use case and implement it. Every plugin must provide:
+
+- `Id` — unique identifier (e.g., `"my-plugin"`)
+- `DisplayName` — shown in the Plugins menu
+- `Version` — shown in the Plugin Manager
+- `Initialize(IPluginHost host)` — called once at startup
+- `Dispose()` — cleanup when unloaded
+
+### 3. Build and Install
+
+Build your plugin as a DLL and install it via the Plugin Manager ("Install from File...") or copy it to the `plugins/` directory next to the SharpFM executable.
+
+## Discovery
+
+SharpFM scans the `plugins/` directory at startup for `.dll` files. Each assembly is loaded in its own `AssemblyLoadContext` and reflected for types implementing `IPlugin` subtypes. Each class is categorized into exactly one plugin type based on the interface it implements.
+
+## Licensing
+
+The `SharpFM.Plugin` project is GPL with a **plugin exception**: plugins that implement these interfaces are not subject to the GPL and may use any license, including proprietary.

docs/plugins/panel-plugins.md

@@ -0,0 +1,73 @@
+# Panel Plugins
+
+Panel plugins provide a sidebar UI panel in the SharpFM main window.
+
+## Interface
+
+```csharp
+public interface IPanelPlugin : IPlugin
+{
+    Control CreatePanel();
+}
+```
+
+`CreatePanel()` is called once when the user activates the plugin. Only one panel plugin can be active at a time. Toggling the same plugin closes it; toggling a different one switches the panel content.
+
+## Lifecycle
+
+1. `Initialize(IPluginHost host)` — subscribe to host events here
+2. `CreatePanel()` — create your Avalonia `Control` (called when plugin is toggled on)
+3. `Dispose()` — unsubscribe from events and clean up
+
+## Subscribing to Events
+
+```csharp
+public void Initialize(IPluginHost host)
+{
+    _host = host;
+    _host.SelectedClipChanged += OnClipChanged;
+    _host.ClipContentChanged += OnContentChanged;
+}
+```
+
+## Bidirectional Sync
+
+If your plugin edits clip XML, use origin tagging to avoid feedback loops:
+
+```csharp
+// Push changes to the host
+_host.UpdateSelectedClipXml(newXml, Id);
+
+// Skip your own updates
+private void OnContentChanged(object? sender, ClipContentChangedArgs args)
+{
+    if (args.Origin == Id) return; // I caused this change
+    _viewModel.LoadClip(args.Clip);
+}
+```
+
+## Example: Minimal Read-Only Panel
+
+```csharp
+public class MyPlugin : IPanelPlugin
+{
+    public string Id => "my-plugin";
+    public string DisplayName => "My Plugin";
+    public string Version => "1.0.0";
+    public IReadOnlyList<PluginKeyBinding> KeyBindings => [];
+    public IReadOnlyList<PluginMenuAction> MenuActions => [];
+
+    private IPluginHost? _host;
+
+    public void Initialize(IPluginHost host) => _host = host;
+
+    public Control CreatePanel()
+    {
+        var text = new TextBlock { Text = _host?.SelectedClip?.Name ?? "No clip" };
+        _host!.SelectedClipChanged += (_, clip) => text.Text = clip?.Name ?? "No clip";
+        return text;
+    }
+
+    public void Dispose() { }
+}
+```

docs/plugins/persistence-plugins.md

@@ -0,0 +1,85 @@
+# Persistence Plugins
+
+Persistence plugins provide alternative storage backends for clips.
+
+## Interfaces
+
+### IPersistencePlugin
+
+```csharp
+public interface IPersistencePlugin : IPlugin
+{
+    IClipRepository CreateRepository();
+}
+```
+
+The plugin handles discovery and lifecycle. `CreateRepository()` is called when the user selects this storage provider.
+
+### IClipRepository
+
+```csharp
+public interface IClipRepository
+{
+    string ProviderName { get; }
+    string CurrentLocation { get; }
+    bool SupportsLocationPicker { get; }
+    Task<IReadOnlyList<ClipData>> LoadClipsAsync();
+    Task SaveClipsAsync(IReadOnlyList<ClipData> clips);
+    Task<string?> PickLocationAsync();
+}
+```
+
+The repository handles all data operations. Methods are async to support remote backends.
+
+### ClipData
+
+```csharp
+public record ClipData(string Name, string ClipType, string Xml);
+```
+
+The persistence DTO. Separate from `ClipInfo` (which is used for plugin notifications) so the two can evolve independently.
+
+## Built-In vs Plugin Storage
+
+The built-in file system storage (`ClipRepository`) implements `IClipRepository` directly — it is **not** a plugin. Plugin-provided backends come through `IPersistencePlugin`.
+
+At startup, the host builds a list of available repositories:
+1. The built-in file system repository
+2. One from each loaded `IPersistencePlugin` via `CreateRepository()`
+
+## Example: Cloud API Storage Plugin
+
+```csharp
+public class CloudStoragePlugin : IPersistencePlugin
+{
+    public string Id => "cloud-storage";
+    public string DisplayName => "Cloud Storage";
+    public string Version => "1.0.0";
+    public IReadOnlyList<PluginKeyBinding> KeyBindings => [];
+    public IReadOnlyList<PluginMenuAction> MenuActions => [];
+
+    public void Initialize(IPluginHost host) { }
+    public IClipRepository CreateRepository() => new CloudRepository();
+    public void Dispose() { }
+}
+
+public class CloudRepository : IClipRepository
+{
+    public string ProviderName => "Cloud API";
+    public string CurrentLocation => "https://api.example.com/clips";
+    public bool SupportsLocationPicker => false;
+
+    public async Task<IReadOnlyList<ClipData>> LoadClipsAsync()
+    {
+        // Fetch clips from your API
+        return [];
+    }
+
+    public async Task SaveClipsAsync(IReadOnlyList<ClipData> clips)
+    {
+        // Push clips to your API
+    }
+
+    public Task<string?> PickLocationAsync() => Task.FromResult<string?>(null);
+}
+```