@signalsandsorcery/plugin-sdk 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,368 @@
+# @signalsandsorcery/plugin-sdk
+
+Plugin SDK for building custom generator plugins for [Signals & Sorcery](https://signalsandsorcery.com) — an AI-powered music production workstation.
+
+Plugins extend the Loop Workstation with custom input generators that create MIDI patterns, manage audio samples, generate AI audio textures, or combine all three. Each plugin gets its own accordion section in the workstation UI and a scoped `PluginHost` API for interacting with tracks, MIDI, audio, and more.
+
+## Installation
+
+```bash
+npm install @signalsandsorcery/plugin-sdk
+```
+
+## Documentation
+
+Full documentation is available at [signalsandsorcery.com/plugin-sdk](https://signalsandsorcery.com/plugin-sdk/):
+
+- [Getting Started](https://signalsandsorcery.com/plugin-sdk/getting-started.html) — Directory structure, manifest, installation, debugging
+- [API Reference](https://signalsandsorcery.com/plugin-sdk/api-reference.html) — Complete PluginHost API with type signatures and examples
+- [Tutorial: Euclidean Rhythm Generator](https://signalsandsorcery.com/plugin-sdk/tutorial.html) — Build a working plugin from scratch
+
+## Reference Plugins
+
+These built-in plugins serve as reference implementations:
+
+| Plugin | Type | Description | Source |
+|--------|------|-------------|--------|
+| Synth Generator | `midi` | AI-powered MIDI generation with Surge XT presets | [sas-synth-plugin](https://github.com/shiehn/sas-synth-plugin) |
+| Sample Player | `sample` | Sample library browser with time-stretching | [sas-sample-plugin](https://github.com/shiehn/sas-sample-plugin) |
+| Audio Texture | `audio` | AI audio texture generation | [sas-audio-plugin](https://github.com/shiehn/sas-audio-plugin) |
+
+## What's in the SDK
+
+### Types
+
+The core plugin contract — everything you need to implement a generator plugin:
+
+```typescript
+import type {
+  GeneratorPlugin,    // Interface your plugin class implements
+  PluginHost,         // Scoped API surface (tracks, MIDI, audio, LLM, etc.)
+  PluginUIProps,      // Props passed to your React component
+  PluginManifest,     // plugin.json schema
+  MusicalContext,     // Key, mode, BPM, bars, chords
+  MidiClipData,       // MIDI clip payload
+  PluginMidiNote,     // Individual MIDI note
+  PluginTrackHandle,  // Track identity returned by createTrack()
+  PluginError,        // Typed error class with error codes
+} from '@signalsandsorcery/plugin-sdk';
+```
+
+### UI Components
+
+Pre-built components that match the host app's visual style:
+
+| Component | Description |
+|-----------|-------------|
+| `TrackRow` | Full-featured track row with prompt input, generate/shuffle/copy buttons, mute/solo, volume/pan, FX drawer, instrument drawer, and progress overlay |
+| `VolumeSlider` | Compact horizontal volume slider (0-1) with dB tooltip |
+| `PanSlider` | Compact horizontal pan slider (-1 to +1) with double-click to center |
+| `FxToggleBar` | Per-track FX control panel with 6 categories, 5 presets each, and dry/wet sliders |
+| `SorceryProgressBar` | Animated progress bar with time-based pacing for long operations |
+| `InstrumentDrawer` | Searchable grid of available VST3/AU instrument plugins |
+
+```typescript
+import { TrackRow, VolumeSlider, PanSlider, FxToggleBar, SorceryProgressBar } from '@signalsandsorcery/plugin-sdk';
+```
+
+### Hooks
+
+```typescript
+import { useSceneState } from '@signalsandsorcery/plugin-sdk';
+
+// Maintains separate state per scene — preserved across scene switches
+const [prompts, setPrompts, setPromptsForScene] = useSceneState(activeSceneId, {});
+```
+
+### Constants
+
+```typescript
+import {
+  VALID_INSTRUMENT_ROLES,  // ['bass', 'kick', 'snare', 'lead', 'pad', ...]
+  PLUGIN_SDK_VERSION,      // '1.0.0'
+  FX_CATEGORIES,           // ['eq', 'compressor', 'chorus', 'phaser', 'delay', 'reverb']
+  FX_PRESET_CONFIGS,       // Preset definitions for all 6 FX categories
+} from '@signalsandsorcery/plugin-sdk';
+```
+
+## Quick Start
+
+### 1. Create the manifest (`plugin.json`)
+
+```json
+{
+  "id": "@my-org/my-plugin",
+  "displayName": "My Plugin",
+  "version": "1.0.0",
+  "description": "A custom generator plugin",
+  "generatorType": "midi",
+  "main": "index.js",
+  "minHostVersion": "1.0.0",
+  "capabilities": {
+    "requiresLLM": true,
+    "requiresSurgeXT": true
+  }
+}
+```
+
+Generator types: `midi` | `audio` | `sample` | `hybrid`
+
+### 2. Implement the plugin class
+
+```typescript
+import type { GeneratorPlugin, PluginHost, PluginUIProps, PluginSettingsSchema, MusicalContext } from '@signalsandsorcery/plugin-sdk';
+import { MyPanel } from './components/Panel';
+
+export class MyPlugin implements GeneratorPlugin {
+  readonly id = '@my-org/my-plugin';
+  readonly displayName = 'My Plugin';
+  readonly version = '1.0.0';
+  readonly description = 'A custom generator plugin';
+  readonly generatorType = 'midi' as const;
+
+  private host: PluginHost | null = null;
+
+  async activate(host: PluginHost): Promise<void> {
+    this.host = host;
+  }
+
+  async deactivate(): Promise<void> {
+    this.host = null;
+  }
+
+  getUIComponent() {
+    return MyPanel;
+  }
+
+  getSettingsSchema(): PluginSettingsSchema | null {
+    return null;
+  }
+
+  // Optional lifecycle hooks
+  async onSceneChanged(sceneId: string | null): Promise<void> { }
+  onContextChanged(context: MusicalContext): void { }
+}
+```
+
+### 3. Build the UI
+
+```tsx
+import type { PluginUIProps } from '@signalsandsorcery/plugin-sdk';
+
+export function MyPanel({ host, activeSceneId, isAuthenticated, isConnected }: PluginUIProps) {
+  const handleGenerate = async () => {
+    if (!activeSceneId) {
+      host.showToast('warning', 'No Scene', 'Select a scene first');
+      return;
+    }
+
+    // Create a track
+    const track = await host.createTrack({ name: 'My Track', role: 'lead', loadSynth: true });
+
+    // Get musical context
+    const context = await host.getMusicalContext();
+
+    // Write MIDI
+    await host.writeMidiClip(track.id, {
+      startTime: 0,
+      endTime: (context.bars * 4 * 60) / context.bpm,
+      tempo: context.bpm,
+      notes: [
+        { pitch: 60, startBeat: 0, durationBeats: 1, velocity: 100 },
+        { pitch: 64, startBeat: 1, durationBeats: 1, velocity: 90 },
+        { pitch: 67, startBeat: 2, durationBeats: 1, velocity: 85 },
+        { pitch: 72, startBeat: 3, durationBeats: 1, velocity: 100 },
+      ],
+    });
+
+    host.showToast('success', 'Done', 'Pattern generated');
+  };
+
+  return (
+    <div>
+      <button onClick={handleGenerate} disabled={!isConnected}>
+        Generate
+      </button>
+    </div>
+  );
+}
+```
+
+### 4. Install the plugin
+
+Place the compiled plugin in:
+
+```
+~/.signals-and-sorcery/plugins/my-plugin/
+  plugin.json
+  index.js
+  ...
+```
+
+Restart Signals & Sorcery. The plugin appears in the workstation accordion.
+
+## PluginHost API Overview
+
+All methods are available on the `host` object your plugin receives in `activate()` and via `PluginUIProps.host`. Methods marked with **ownership** can only modify tracks the calling plugin created.
+
+### Track Management
+| Method | Description |
+|--------|-------------|
+| `createTrack(options)` | Create a track with name, role, synth, instrument |
+| `deleteTrack(trackId)` | Delete an owned track |
+| `getPluginTracks()` | List all tracks this plugin owns in the active scene |
+| `getTrackInfo(trackId)` | Detailed track state (mute, volume, pan, plugins) |
+| `adoptSceneTracks()` | Re-claim unowned tracks matching generator type |
+| `setTrackMute/Volume/Pan/Solo/Name` | Track property setters |
+| `shufflePreset(trackId)` | Randomize Surge XT preset (keeps MIDI) |
+| `duplicateTrack(trackId)` | Clone track with MIDI + new preset |
+
+### MIDI Operations
+| Method | Description |
+|--------|-------------|
+| `writeMidiClip(trackId, clip)` | Write MIDI notes (replaces existing) |
+| `clearMidi(trackId)` | Clear all MIDI from a track |
+| `postProcessMidi(notes, options)` | Quantize, swing, scale enforcement, humanization |
+| `auditionNote(trackId, pitch, velocity, durationMs)` | Preview a single note |
+
+### Audio Operations
+| Method | Description |
+|--------|-------------|
+| `writeAudioClip(trackId, filePath, position?)` | Place audio file on track |
+| `generateAudioTexture(request)` | AI audio generation from text prompt |
+
+### Plugin/Synth Operations
+| Method | Description |
+|--------|-------------|
+| `loadSynthPlugin(trackId, pluginName)` | Load VST3/AU plugin |
+| `setPluginState/getPluginState` | Save/restore base64-encoded preset data |
+| `getTrackPlugins(trackId)` | List loaded plugins |
+| `getAvailableInstruments()` | Get scanned VST3/AU instruments |
+| `setTrackInstrument(trackId, pluginId)` | Change instrument (preserves MIDI) |
+
+### FX Operations
+Six categories in signal chain order: `eq` > `compressor` > `chorus` > `phaser` > `delay` > `reverb`
+
+| Method | Description |
+|--------|-------------|
+| `getTrackFxState(trackId)` | Get enabled/preset/dryWet per category |
+| `toggleTrackFx(trackId, category, enabled)` | Enable/disable FX category |
+| `setTrackFxPreset(trackId, category, presetIndex)` | Set FX preset (0-4) |
+| `setTrackFxDryWet(trackId, category, value)` | Set dry/wet mix (0.0-1.0) |
+
+### Scene Context
+| Method | Description |
+|--------|-------------|
+| `getGenerationContext(excludeTrackId?)` | Full context + concurrent track MIDI data |
+| `getMusicalContext()` | Key, mode, BPM, bars, genre, chords |
+| `getActiveSceneId()` | Current scene ID (synchronous) |
+| `getSceneList()` | All scenes in the project |
+
+### Transport & Events
+| Method | Description |
+|--------|-------------|
+| `onTrackStateChange(listener)` | Real-time mute, solo, volume, pan updates |
+| `onTransportEvent(listener)` | Play, stop, BPM change, position |
+| `onDeckBoundary(listener)` | Loop boundary events (bar, beat, loopCount) |
+| `onSceneChange(listener)` | Scene selection changes |
+| `onEngineReady(listener)` | Engine finished loading tracks |
+| `getTransportState()` | Current playback state snapshot |
+
+### LLM Access
+| Method | Description |
+|--------|-------------|
+| `generateWithLLM(request)` | Generate text/JSON (metered, requires auth) |
+| `isLLMAvailable()` | Check auth + gateway reachability |
+
+### Preset System
+| Method | Description |
+|--------|-------------|
+| `getPresetCategories(pluginName)` | Available Surge XT categories |
+| `getRandomPreset(category)` | Random preset from category |
+| `getPresetByName(category, name)` | Specific preset lookup |
+| `classifyPresetCategory(description)` | LLM-based text-to-category |
+
+### Scene Composition
+| Method | Description |
+|--------|-------------|
+| `composeScene(options)` | Bulk LLM arrangement generation |
+| `onComposeProgress(listener)` | Progress events (planning, generating, complete) |
+
+### Data Persistence
+| Method | Description |
+|--------|-------------|
+| `getSceneData/setSceneData/getAllSceneData/deleteSceneData` | Per-scene key-value storage |
+| `getProjectData/setProjectData` | Project-wide storage |
+| `settings.get/set/getAll/onChange` | Global settings (cross-project) |
+| `getDataDirectory()` | Plugin's isolated data directory path |
+
+### Plugin Presets
+| Method | Description |
+|--------|-------------|
+| `getPluginPresets(category?)` | Get saved presets for this plugin |
+| `savePluginPreset(options)` | Save a preset (name, category, data) |
+| `deletePluginPreset(id)` | Delete a preset |
+
+### File System & Network
+| Method | Description |
+|--------|-------------|
+| `showOpenDialog/showSaveDialog` | Native file dialogs (requires `fileDialog` capability) |
+| `downloadFile/importFile` | Download/copy files to plugin data directory |
+| `httpRequest(options)` | HTTP requests (requires `network` capability with `allowedHosts`) |
+
+### Secure Storage
+| Method | Description |
+|--------|-------------|
+| `storeSecret/getSecret/deleteSecret` | OS keychain encryption, per-plugin scoped |
+
+### Sample Library
+| Method | Description |
+|--------|-------------|
+| `getSamples/getSampleById` | Query sample library |
+| `importSamples(filePaths)` | Import audio files |
+| `createSampleTrack/deleteSampleTrack` | Manage sample tracks |
+| `getPluginSampleTracks()` | List owned sample tracks |
+| `timeStretchSample(sampleId, targetBpm)` | Time-stretch to target BPM |
+
+### Notifications & Progress
+| Method | Description |
+|--------|-------------|
+| `showToast(type, title, message?)` | Toast notification (info/success/warning/error) |
+| `setProgress(trackId, progress)` | Track progress bar (0-100, -1 to hide) |
+| `setStatusMessage(message)` | Accordion header status text |
+| `confirmAction(title, message)` | Confirmation dialog |
+
+## Error Codes
+
+All errors are `PluginError` instances with a typed `code` property:
+
+| Code | Description |
+|------|-------------|
+| `NOT_OWNED` | Tried to modify a track not owned by this plugin |
+| `TRACK_NOT_FOUND` | Track ID doesn't exist in engine |
+| `TRACK_LIMIT_EXCEEDED` | Plugin has too many tracks (default: 16 per scene) |
+| `NO_ACTIVE_SCENE` | No scene is selected |
+| `ENGINE_ERROR` | Audio engine call failed |
+| `INVALID_MIDI` | Malformed MIDI data |
+| `FILE_NOT_FOUND` | Referenced file doesn't exist |
+| `INVALID_FORMAT` | Unsupported audio format |
+| `PLUGIN_NOT_FOUND` | VST/AU plugin not installed |
+| `LLM_BUDGET_EXCEEDED` | Over daily token limit |
+| `LLM_UNAVAILABLE` | LLM gateway unreachable |
+| `NOT_AUTHENTICATED` | User not logged in |
+| `TIMEOUT` | Operation timed out |
+| `CANCELLED` | User cancelled the operation |
+| `INCOMPATIBLE` | Plugin requires newer SDK version |
+| `CAPABILITY_DENIED` | Plugin lacks required capability in manifest |
+| `SECRET_NOT_FOUND` | Secret key doesn't exist |
+
+## Security Model
+
+- **Ownership scoping** — Plugins can only modify tracks they created (enforced at runtime)
+- **Capability gating** — Network and file system access require manifest declarations
+- **Secret isolation** — Each plugin's secrets are encrypted and scoped per plugin
+- **Track limits** — 16 tracks per plugin per scene (configurable)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -163,6 +163,10 @@ interface PluginHost {
     getTrackInstrument(trackId: string): Promise<InstrumentDescriptor | null>;
     /** Change the instrument plugin on a track. Preserves MIDI data. */
     setTrackInstrument(trackId: string, pluginId: string): Promise<void>;
+    /** Open the instrument plugin's native editor GUI as a floating window. */
+    showInstrumentEditor(trackId: string): Promise<void>;
+    /** Close the instrument plugin's editor window. */
+    hideInstrumentEditor(trackId: string): Promise<void>;
     /** Get the FULL generation context for the active scene. */
     getGenerationContext(excludeTrackId?: string): Promise<PluginGenerationContext>;
     /** Get lightweight musical context (no concurrent track MIDI data). */
@@ -267,6 +271,24 @@ interface PluginHost {
     logMetric(name: string, durationMs: number, metadata?: Record<string, unknown>): void;
     /** Start a timer. Returns a stop function that logs the duration. */
     startTimer(name: string): () => void;
+    /** Split an audio track into stems (vocals, drums, bass, other). Creates new muted tracks. */
+    splitStems(trackId: string): Promise<PluginStemSplitResult>;
+    /** Check if the stem splitter binary is available. */
+    isStemSplitterAvailable(): Promise<boolean>;
+}
+/** Stem type identifiers */
+type StemType = 'vocals' | 'drums' | 'bass' | 'other';
+/** Result of splitting an audio track into stems */
+interface PluginStemSplitResult {
+    /** Created stem tracks with audio loaded (all auto-muted) */
+    stems: PluginStemTrackInfo[];
+}
+/** Information about a single stem track created by stem splitting */
+interface PluginStemTrackInfo {
+    /** The stem type (vocals, drums, bass, other) */
+    stemType: StemType;
+    /** Track handle for the new stem track */
+    track: PluginTrackHandle;
 }
 interface ExportedPluginData {
     pluginId: string;
@@ -902,14 +924,20 @@ interface SDKTrackRowProps {
     instrumentsLoading?: boolean;
     /** Re-scan for instruments */
     onRefreshInstruments?: () => void;
+    /** Which stage the instrument drawer is in */
+    instrumentDrawerStage?: 'instruments' | 'editor';
+    /** Called when user clicks "Open Editor" */
+    onShowEditor?: () => void;
+    /** Called when user wants to go back from editor view */
+    onBackToInstruments?: () => void;
 }
-declare function TrackRow({ track, prompt, runtimeState, fxDetailState, fxDrawerOpen, isGenerating, isAuthenticated, error, hasMidi, generationProgress, estimatedGenerationMs, onPromptChange, onGenerate, onShuffle, onCopy, onDelete, contentSlot, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onFxToggle, onFxPresetChange, onFxDryWetChange, onToggleFxDrawer, onProgressChange, accentColor, instrumentName, instrumentMissing, instrumentDrawerOpen, onToggleInstrumentDrawer, availableInstruments, currentInstrumentPluginId, onInstrumentSelect, instrumentsLoading, onRefreshInstruments, }: SDKTrackRowProps): React.ReactElement;
+declare function TrackRow({ track, prompt, runtimeState, fxDetailState, fxDrawerOpen, isGenerating, isAuthenticated, error, hasMidi, generationProgress, estimatedGenerationMs, onPromptChange, onGenerate, onShuffle, onCopy, onDelete, contentSlot, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onFxToggle, onFxPresetChange, onFxDryWetChange, onToggleFxDrawer, onProgressChange, accentColor, instrumentName, instrumentMissing, instrumentDrawerOpen, onToggleInstrumentDrawer, availableInstruments, currentInstrumentPluginId, onInstrumentSelect, instrumentsLoading, onRefreshInstruments, instrumentDrawerStage, onShowEditor, onBackToInstruments, }: SDKTrackRowProps): React.ReactElement;
 
 /**
- * InstrumentDrawer — Sliding drawer for selecting instrument plugins (VST3/AU).
+ * InstrumentDrawer — Two-stage nested menu for instrument selection + editor access.
  *
- * Appears below the track controls when the "P" button is toggled.
- * Shows a searchable grid of available instrument plugins.
+ * Stage 1 (instruments): Searchable grid of available VST3/AU instrument plugins.
+ * Stage 2 (editor): Shows "Open Editor" button for the selected plugin's native GUI.
  */
 
 interface InstrumentDrawerProps {
@@ -923,8 +951,16 @@ interface InstrumentDrawerProps {
     onSelect: (pluginId: string) => void;
     /** Called when user clicks refresh to re-scan plugins */
     onRefresh: () => void;
+    /** Which stage the drawer is in */
+    stage?: 'instruments' | 'editor';
+    /** Called when user clicks "Open Editor" */
+    onShowEditor?: () => void;
+    /** Called when user wants to go back from editor view to instrument list */
+    onBackToInstruments?: () => void;
+    /** Name of the selected instrument (for display in editor header) */
+    selectedInstrumentName?: string | null;
 }
-declare function InstrumentDrawer({ instruments, currentPluginId, isLoading, onSelect, onRefresh, }: InstrumentDrawerProps): React.ReactElement;
+declare function InstrumentDrawer({ instruments, currentPluginId, isLoading, onSelect, onRefresh, stage, onShowEditor, onBackToInstruments, selectedInstrumentName, }: InstrumentDrawerProps): React.ReactElement;
 
 /**
  * VolumeSlider Component
@@ -1133,4 +1169,4 @@ declare function sliderToDb(slider: number): number;
  */
 declare function dbToSlider(db: number): number;
 
-export { type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, type CreateTrackOptions, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, type DeckBoundaryEvent, type DeckBoundaryListener, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, type GeneratorPlugin, type GeneratorType, type InstrumentDescriptor, InstrumentDrawer, type InstrumentDrawerProps, type LLMGenerationRequest, type LLMGenerationResult, type MidiClipData, type MidiWriteResult, type MixInterpolation, type MusicalContext, PLUGIN_SDK_VERSION, PanSlider, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginStatus, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackRuntimeState, type PluginTransportState, type PluginUIProps, type PostProcessOptions, type SDKTrackRowProps, SLIDER_UNITY, type SavePluginPresetOptions, type SceneChangeListener, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type TrackFxDetailState, type TrackFxState, TrackRow, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };
+export { type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, type CreateTrackOptions, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, type DeckBoundaryEvent, type DeckBoundaryListener, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, type GeneratorPlugin, type GeneratorType, type InstrumentDescriptor, InstrumentDrawer, type InstrumentDrawerProps, type LLMGenerationRequest, type LLMGenerationResult, type MidiClipData, type MidiWriteResult, type MixInterpolation, type MusicalContext, PLUGIN_SDK_VERSION, PanSlider, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackRuntimeState, type PluginTransportState, type PluginUIProps, type PostProcessOptions, type SDKTrackRowProps, SLIDER_UNITY, type SavePluginPresetOptions, type SceneChangeListener, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type StemType, type TrackFxDetailState, type TrackFxState, TrackRow, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };

package/dist/index.d.ts

@@ -163,6 +163,10 @@ interface PluginHost {
     getTrackInstrument(trackId: string): Promise<InstrumentDescriptor | null>;
     /** Change the instrument plugin on a track. Preserves MIDI data. */
     setTrackInstrument(trackId: string, pluginId: string): Promise<void>;
+    /** Open the instrument plugin's native editor GUI as a floating window. */
+    showInstrumentEditor(trackId: string): Promise<void>;
+    /** Close the instrument plugin's editor window. */
+    hideInstrumentEditor(trackId: string): Promise<void>;
     /** Get the FULL generation context for the active scene. */
     getGenerationContext(excludeTrackId?: string): Promise<PluginGenerationContext>;
     /** Get lightweight musical context (no concurrent track MIDI data). */
@@ -267,6 +271,24 @@ interface PluginHost {
     logMetric(name: string, durationMs: number, metadata?: Record<string, unknown>): void;
     /** Start a timer. Returns a stop function that logs the duration. */
     startTimer(name: string): () => void;
+    /** Split an audio track into stems (vocals, drums, bass, other). Creates new muted tracks. */
+    splitStems(trackId: string): Promise<PluginStemSplitResult>;
+    /** Check if the stem splitter binary is available. */
+    isStemSplitterAvailable(): Promise<boolean>;
+}
+/** Stem type identifiers */
+type StemType = 'vocals' | 'drums' | 'bass' | 'other';
+/** Result of splitting an audio track into stems */
+interface PluginStemSplitResult {
+    /** Created stem tracks with audio loaded (all auto-muted) */
+    stems: PluginStemTrackInfo[];
+}
+/** Information about a single stem track created by stem splitting */
+interface PluginStemTrackInfo {
+    /** The stem type (vocals, drums, bass, other) */
+    stemType: StemType;
+    /** Track handle for the new stem track */
+    track: PluginTrackHandle;
 }
 interface ExportedPluginData {
     pluginId: string;
@@ -902,14 +924,20 @@ interface SDKTrackRowProps {
     instrumentsLoading?: boolean;
     /** Re-scan for instruments */
     onRefreshInstruments?: () => void;
+    /** Which stage the instrument drawer is in */
+    instrumentDrawerStage?: 'instruments' | 'editor';
+    /** Called when user clicks "Open Editor" */
+    onShowEditor?: () => void;
+    /** Called when user wants to go back from editor view */
+    onBackToInstruments?: () => void;
 }
-declare function TrackRow({ track, prompt, runtimeState, fxDetailState, fxDrawerOpen, isGenerating, isAuthenticated, error, hasMidi, generationProgress, estimatedGenerationMs, onPromptChange, onGenerate, onShuffle, onCopy, onDelete, contentSlot, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onFxToggle, onFxPresetChange, onFxDryWetChange, onToggleFxDrawer, onProgressChange, accentColor, instrumentName, instrumentMissing, instrumentDrawerOpen, onToggleInstrumentDrawer, availableInstruments, currentInstrumentPluginId, onInstrumentSelect, instrumentsLoading, onRefreshInstruments, }: SDKTrackRowProps): React.ReactElement;
+declare function TrackRow({ track, prompt, runtimeState, fxDetailState, fxDrawerOpen, isGenerating, isAuthenticated, error, hasMidi, generationProgress, estimatedGenerationMs, onPromptChange, onGenerate, onShuffle, onCopy, onDelete, contentSlot, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onFxToggle, onFxPresetChange, onFxDryWetChange, onToggleFxDrawer, onProgressChange, accentColor, instrumentName, instrumentMissing, instrumentDrawerOpen, onToggleInstrumentDrawer, availableInstruments, currentInstrumentPluginId, onInstrumentSelect, instrumentsLoading, onRefreshInstruments, instrumentDrawerStage, onShowEditor, onBackToInstruments, }: SDKTrackRowProps): React.ReactElement;
 
 /**
- * InstrumentDrawer — Sliding drawer for selecting instrument plugins (VST3/AU).
+ * InstrumentDrawer — Two-stage nested menu for instrument selection + editor access.
  *
- * Appears below the track controls when the "P" button is toggled.
- * Shows a searchable grid of available instrument plugins.
+ * Stage 1 (instruments): Searchable grid of available VST3/AU instrument plugins.
+ * Stage 2 (editor): Shows "Open Editor" button for the selected plugin's native GUI.
  */
 
 interface InstrumentDrawerProps {
@@ -923,8 +951,16 @@ interface InstrumentDrawerProps {
     onSelect: (pluginId: string) => void;
     /** Called when user clicks refresh to re-scan plugins */
     onRefresh: () => void;
+    /** Which stage the drawer is in */
+    stage?: 'instruments' | 'editor';
+    /** Called when user clicks "Open Editor" */
+    onShowEditor?: () => void;
+    /** Called when user wants to go back from editor view to instrument list */
+    onBackToInstruments?: () => void;
+    /** Name of the selected instrument (for display in editor header) */
+    selectedInstrumentName?: string | null;
 }
-declare function InstrumentDrawer({ instruments, currentPluginId, isLoading, onSelect, onRefresh, }: InstrumentDrawerProps): React.ReactElement;
+declare function InstrumentDrawer({ instruments, currentPluginId, isLoading, onSelect, onRefresh, stage, onShowEditor, onBackToInstruments, selectedInstrumentName, }: InstrumentDrawerProps): React.ReactElement;
 
 /**
  * VolumeSlider Component
@@ -1133,4 +1169,4 @@ declare function sliderToDb(slider: number): number;
  */
 declare function dbToSlider(db: number): number;
 
-export { type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, type CreateTrackOptions, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, type DeckBoundaryEvent, type DeckBoundaryListener, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, type GeneratorPlugin, type GeneratorType, type InstrumentDescriptor, InstrumentDrawer, type InstrumentDrawerProps, type LLMGenerationRequest, type LLMGenerationResult, type MidiClipData, type MidiWriteResult, type MixInterpolation, type MusicalContext, PLUGIN_SDK_VERSION, PanSlider, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginStatus, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackRuntimeState, type PluginTransportState, type PluginUIProps, type PostProcessOptions, type SDKTrackRowProps, SLIDER_UNITY, type SavePluginPresetOptions, type SceneChangeListener, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type TrackFxDetailState, type TrackFxState, TrackRow, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };
+export { type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, type CreateTrackOptions, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, type DeckBoundaryEvent, type DeckBoundaryListener, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, type GeneratorPlugin, type GeneratorType, type InstrumentDescriptor, InstrumentDrawer, type InstrumentDrawerProps, type LLMGenerationRequest, type LLMGenerationResult, type MidiClipData, type MidiWriteResult, type MixInterpolation, type MusicalContext, PLUGIN_SDK_VERSION, PanSlider, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackRuntimeState, type PluginTransportState, type PluginUIProps, type PostProcessOptions, type SDKTrackRowProps, SLIDER_UNITY, type SavePluginPresetOptions, type SceneChangeListener, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type StemType, type TrackFxDetailState, type TrackFxState, TrackRow, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };

package/dist/index.js

@@ -125,24 +125,60 @@ function InstrumentDrawer({
   currentPluginId,
   isLoading,
   onSelect,
-  onRefresh
+  onRefresh,
+  stage = "instruments",
+  onShowEditor,
+  onBackToInstruments,
+  selectedInstrumentName
 }) {
   const [search, setSearch] = (0, import_react.useState)("");
   const SURGE_XT_DEFAULT_ID = "Surge XT";
   const filtered = (0, import_react.useMemo)(() => {
-    const all = instruments.filter(
+    let all = instruments.filter(
       (i) => i.name !== "Surge XT"
     );
-    if (!search.trim()) return all;
-    const q = search.toLowerCase();
-    return all.filter(
-      (i) => i.name.toLowerCase().includes(q) || i.manufacturer.toLowerCase().includes(q)
-    );
-  }, [instruments, search]);
+    if (search.trim()) {
+      const q = search.toLowerCase();
+      all = all.filter(
+        (i) => i.name.toLowerCase().includes(q) || i.manufacturer.toLowerCase().includes(q)
+      );
+    }
+    if (currentPluginId) {
+      const selectedIdx = all.findIndex((i) => i.pluginId === currentPluginId);
+      if (selectedIdx > 0) {
+        const [selected] = all.splice(selectedIdx, 1);
+        all.unshift(selected);
+      }
+    }
+    return all;
+  }, [instruments, search, currentPluginId]);
   const isDefaultSelected = currentPluginId === null;
   const isSelected = (pluginId) => {
     return pluginId === currentPluginId;
   };
+  if (stage === "editor") {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "flex flex-col gap-2", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "flex items-center gap-2", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "button",
+          {
+            onClick: () => onBackToInstruments?.(),
+            className: "px-2 py-1 text-xs rounded-sm border border-sas-border text-sas-muted hover:text-sas-accent hover:border-sas-accent transition-colors",
+            children: "\u2190 Back"
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "text-xs text-sas-muted font-medium truncate flex-1", children: selectedInstrumentName ?? "Plugin" })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        "button",
+        {
+          onClick: () => onShowEditor?.(),
+          className: "w-full py-2 text-xs font-medium rounded-sm border border-sas-accent bg-sas-accent/20 text-sas-accent hover:bg-sas-accent/40 transition-colors",
+          children: "Open Plugin Editor"
+        }
+      )
+    ] });
+  }
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "flex flex-col gap-2", children: [
     /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "flex items-center gap-2", children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
@@ -1007,7 +1043,10 @@ function TrackRow({
   currentInstrumentPluginId,
   onInstrumentSelect,
   instrumentsLoading,
-  onRefreshInstruments
+  onRefreshInstruments,
+  instrumentDrawerStage,
+  onShowEditor,
+  onBackToInstruments
 }) {
   const { muted: isMuted, solo: isSoloed, volume: currentVolume, pan: currentPan } = runtimeState;
   const needsGeneration = !!(prompt?.trim() && !hasMidi && !isGenerating);
@@ -1152,9 +1191,9 @@ function TrackRow({
                 {
                   "data-testid": "sdk-shuffle-button",
                   onClick: onShuffle,
-                  disabled: !hasMidi || isGenerating,
-                  className: `w-14 py-0.5 rounded-sm text-xs font-medium transition-colors border ${!hasMidi || isGenerating ? "bg-sas-panel border-sas-border text-sas-muted/30 cursor-not-allowed" : "bg-sas-panel-alt border-sas-border text-sas-muted hover:border-sas-accent hover:text-sas-accent"}`,
-                  title: hasMidi ? "Re-roll sound (keep MIDI)" : "Generate MIDI first",
+                  disabled: !hasMidi || isGenerating || !!currentInstrumentPluginId,
+                  className: `w-14 py-0.5 rounded-sm text-xs font-medium transition-colors border ${!hasMidi || isGenerating || !!currentInstrumentPluginId ? "bg-sas-panel border-sas-border text-sas-muted/30 cursor-not-allowed" : "bg-sas-panel-alt border-sas-border text-sas-muted hover:border-sas-accent hover:text-sas-accent"}`,
+                  title: currentInstrumentPluginId ? "Shuffle only works with default Surge XT" : hasMidi ? "Re-roll sound (keep MIDI)" : "Generate MIDI first",
                   children: "Shuffle"
                 }
               ),
@@ -1214,7 +1253,11 @@ function TrackRow({
         currentPluginId: currentInstrumentPluginId ?? null,
         isLoading: instrumentsLoading ?? false,
         onSelect: onInstrumentSelect,
-        onRefresh: onRefreshInstruments
+        onRefresh: onRefreshInstruments,
+        stage: instrumentDrawerStage,
+        onShowEditor,
+        onBackToInstruments,
+        selectedInstrumentName: instrumentName
       }
     ) })
   ] });