Host and Runtime Internals

1. Startup flow

MainForm ctor
  -> BuildBaseMenus()  // Help only
  -> LoadPlugins()
     -> PluginLoader.LoadPlugins(Plugins/**.plugin.json)
     -> plugin.OnLoad(hostContext)
     -> RebuildAllDirtyRootMenus()
  -> RestoreDockLayout() on Shown

Source: src/RetroWaveLab.Host.WinForms/MainForm.cs, src/RetroWaveLab.Core.Runtime/PluginLoader.cs.

2. Menu ordering implementation

// root ordering
OrderBy(GetRootSortOrder)
ThenBy(GetRootFirstSequence)
ThenBy(root.Text, OrdinalIgnoreCase)

// item ordering within root/group
OrderBy(reg.Sort)
ThenBy(reg.GroupSortKey)
ThenBy(reg.GroupName)
ThenBy(reg.Sequence)

Root sort is first-seen per root. Help root is forced to sort 1000.

Source: src/RetroWaveLab.Host.WinForms/MainForm.cs.

3. Plugin loading and shared assembly rule

var manifests = Directory.GetFiles(pluginsRoot, "*.plugin.json", SearchOption.AllDirectories);
var context = new PluginLoadContext(assemblyPath);
var assembly = context.LoadFromAssemblyPath(assemblyPath);
var entryType = assembly.GetType(manifest.EntryType, throwOnError: true)!;
var plugin = (IPlugin)Activator.CreateInstance(entryType)!;
plugin.OnLoad(hostContext);

PluginLoadContext shares RetroWaveLab.Core.Abstractions with host so interface types match.

Source: src/RetroWaveLab.Core.Runtime/PluginLoader.cs.

4. Runtime buses and ownership

• SampleControllerBus: state + active buffer broadcast.
• AudioSystemBus: playback/recording commands + telemetry events.
• TransportOptionsBus: play-scope and follow/loop options.
• SelectionEventBus: selection change phases.
• WaveHoverEventBus: hover readout payload for status UI.

Source: src/RetroWaveLab.Core.Runtime/Buses.cs.

5. Document service responsibilities

• Owns open documents and active document switching.
• Keeps per-document sample editor state snapshots.
• Performs safe buffer replacement/copy operations and publishes to sample bus.
• Provides preview session API for effect dialogues.
• Tracks edit revision/action metadata.

Source: src/RetroWaveLab.Core.Runtime/Documents.cs.

6. Preset store responsibilities

• Stores presets under Presets/<PluginName>/.
• Uses deterministic SHA-2 filename from normalised pluginName:presetName.
• Provides LastUsed(pluginName) state retrieval.
• Supports add/update/delete and list discovery.

Source: src/RetroWaveLab.Core.Runtime/Presets.cs.