@signalsandsorcery/plugin-sdk 1.3.2 → 2.0.1

package/dist/index.d.mts

@@ -145,10 +145,37 @@ interface PluginHost {
     setTrackSolo(trackId: string, solo: boolean): Promise<void>;
     /** Rename a track. Only works on owned tracks. */
     setTrackName(trackId: string, name: string): Promise<void>;
+    /**
+     * Persist a track's musical role to the `tracks.role` column. Call this
+     * after an LLM generation classifies the track (e.g. `'bass'`, `'lead'`,
+     * `'pad'`, `'fx'`, `'kicks'`) so downstream features — especially the v1
+     * transition generator's layer classifier — can see the role.
+     *
+     * Canonical values understood by the transition classifier include
+     * `bass`, `drums`, `lead`, `chords`, `pad`, `arp`, `fx`, `kicks`,
+     * `snares`, `hats`, `clap`, `perc`, `riser`, `impact`. Anything else is
+     * stored verbatim but won't match the neutral-role set.
+     *
+     * Only works on owned tracks.
+     */
+    setTrackRole(trackId: string, role: string): Promise<void>;
     /** Shuffle preset: keep MIDI, apply a random preset from the same category. Only works on owned tracks. */
     shufflePreset(trackId: string): Promise<ShufflePresetResult>;
     /** Duplicate track: copy MIDI + role to a new track with a different preset. Only works on owned tracks. */
     duplicateTrack(trackId: string): Promise<PluginTrackHandle>;
+    /**
+     * Return the canonical list of valid role tokens that the host's
+     * classifier and UI understand. Plugins should use this list when
+     * building LLM prompts or validating role values before calling
+     * {@link setTrackRole}.
+     *
+     * The assistant owns the canonical taxonomy — plugins MUST NOT ship
+     * their own hardcoded list, which would drift from the host. Pair with
+     * {@link setTrackRole} to persist a classified role.
+     *
+     * @since SDK 2.0.0
+     */
+    getValidRoles(): readonly string[];
     /** Get detailed FX state for a track (enabled, preset, dry/wet per category). */
     getTrackFxState(trackId: string): Promise<PluginTrackFxDetailState>;
     /** Toggle an FX category on/off for a track. */
@@ -1313,13 +1340,6 @@ type SetSceneState<T> = (value: T | ((prev: T) => T)) => void;
 type SetSceneStateForScene<T> = (sceneId: string, value: T | ((prev: T) => T)) => void;
 declare function useSceneState<T>(activeSceneId: string | null, initialValue: T): [T, SetSceneState<T>, SetSceneStateForScene<T>];
 
-/**
- * Valid instrument roles for synth track generation.
- * Used in LLM prompts and preset selection.
- * Canonical source — imported by both plugin SDK and core services.
- */
-declare const VALID_INSTRUMENT_ROLES: readonly string[];
-
 /**
  * Plugin SDK Version
  *
@@ -1328,7 +1348,7 @@ declare const VALID_INSTRUMENT_ROLES: readonly string[];
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "1.2.0";
+declare const PLUGIN_SDK_VERSION = "2.0.0";
 
 /**
  * FX Preset Definitions
@@ -1382,4 +1402,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 ExportMidiBundleOptions, type ExportMidiBundleResult, 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 PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, 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 PluginSkill, type PluginSkillInputSchema, 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 };
+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 ExportMidiBundleOptions, type ExportMidiBundleResult, 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 PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, 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 PluginSkill, type PluginSkillInputSchema, 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, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };

package/dist/index.d.ts

@@ -145,10 +145,37 @@ interface PluginHost {
     setTrackSolo(trackId: string, solo: boolean): Promise<void>;
     /** Rename a track. Only works on owned tracks. */
     setTrackName(trackId: string, name: string): Promise<void>;
+    /**
+     * Persist a track's musical role to the `tracks.role` column. Call this
+     * after an LLM generation classifies the track (e.g. `'bass'`, `'lead'`,
+     * `'pad'`, `'fx'`, `'kicks'`) so downstream features — especially the v1
+     * transition generator's layer classifier — can see the role.
+     *
+     * Canonical values understood by the transition classifier include
+     * `bass`, `drums`, `lead`, `chords`, `pad`, `arp`, `fx`, `kicks`,
+     * `snares`, `hats`, `clap`, `perc`, `riser`, `impact`. Anything else is
+     * stored verbatim but won't match the neutral-role set.
+     *
+     * Only works on owned tracks.
+     */
+    setTrackRole(trackId: string, role: string): Promise<void>;
     /** Shuffle preset: keep MIDI, apply a random preset from the same category. Only works on owned tracks. */
     shufflePreset(trackId: string): Promise<ShufflePresetResult>;
     /** Duplicate track: copy MIDI + role to a new track with a different preset. Only works on owned tracks. */
     duplicateTrack(trackId: string): Promise<PluginTrackHandle>;
+    /**
+     * Return the canonical list of valid role tokens that the host's
+     * classifier and UI understand. Plugins should use this list when
+     * building LLM prompts or validating role values before calling
+     * {@link setTrackRole}.
+     *
+     * The assistant owns the canonical taxonomy — plugins MUST NOT ship
+     * their own hardcoded list, which would drift from the host. Pair with
+     * {@link setTrackRole} to persist a classified role.
+     *
+     * @since SDK 2.0.0
+     */
+    getValidRoles(): readonly string[];
     /** Get detailed FX state for a track (enabled, preset, dry/wet per category). */
     getTrackFxState(trackId: string): Promise<PluginTrackFxDetailState>;
     /** Toggle an FX category on/off for a track. */
@@ -1313,13 +1340,6 @@ type SetSceneState<T> = (value: T | ((prev: T) => T)) => void;
 type SetSceneStateForScene<T> = (sceneId: string, value: T | ((prev: T) => T)) => void;
 declare function useSceneState<T>(activeSceneId: string | null, initialValue: T): [T, SetSceneState<T>, SetSceneStateForScene<T>];
 
-/**
- * Valid instrument roles for synth track generation.
- * Used in LLM prompts and preset selection.
- * Canonical source — imported by both plugin SDK and core services.
- */
-declare const VALID_INSTRUMENT_ROLES: readonly string[];
-
 /**
  * Plugin SDK Version
  *
@@ -1328,7 +1348,7 @@ declare const VALID_INSTRUMENT_ROLES: readonly string[];
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "1.2.0";
+declare const PLUGIN_SDK_VERSION = "2.0.0";
 
 /**
  * FX Preset Definitions
@@ -1382,4 +1402,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 ExportMidiBundleOptions, type ExportMidiBundleResult, 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 PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, 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 PluginSkill, type PluginSkillInputSchema, 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 };
+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 ExportMidiBundleOptions, type ExportMidiBundleResult, 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 PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, 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 PluginSkill, type PluginSkillInputSchema, 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, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };

package/dist/index.js

@@ -39,7 +39,6 @@ __export(index_exports, {
   SLIDER_UNITY: () => SLIDER_UNITY,
   SorceryProgressBar: () => SorceryProgressBar,
   TrackRow: () => TrackRow,
-  VALID_INSTRUMENT_ROLES: () => VALID_INSTRUMENT_ROLES,
   VolumeSlider: () => VolumeSlider,
   calculateTimeBasedTarget: () => calculateTimeBasedTarget,
   dbToSlider: () => dbToSlider,
@@ -1293,37 +1292,8 @@ function useSceneState(activeSceneId, initialValue) {
   return [currentValue, setForCurrentScene, setForScene];
 }
 
-// src/constants/instrument-roles.ts
-var VALID_INSTRUMENT_ROLES = [
-  "bass",
-  "kick",
-  "snare",
-  "hat",
-  "808",
-  "percussion",
-  "lead",
-  "pad",
-  "keys",
-  "piano",
-  "organ",
-  "pluck",
-  "strings",
-  "brass",
-  "winds",
-  "bell",
-  "mallet",
-  "guitar",
-  "synth",
-  "atmosphere",
-  "drone",
-  "rhythm",
-  "soundscape",
-  "vocal",
-  "fx"
-];
-
 // src/constants/sdk-version.ts
-var PLUGIN_SDK_VERSION = "1.2.0";
+var PLUGIN_SDK_VERSION = "2.0.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DB_MAX,
@@ -1345,7 +1315,6 @@ var PLUGIN_SDK_VERSION = "1.2.0";
   SLIDER_UNITY,
   SorceryProgressBar,
   TrackRow,
-  VALID_INSTRUMENT_ROLES,
   VolumeSlider,
   calculateTimeBasedTarget,
   dbToSlider,