@signalsandsorcery/plugin-sdk 2.24.1 → 2.26.1

package/dist/index.d.mts

@@ -227,6 +227,16 @@ interface PluginHost {
     setTrackMute(trackId: string, muted: boolean): Promise<void>;
     /** Set track volume (linear 0.0 - 1.0). Only works on owned tracks. */
     setTrackVolume(trackId: string, volume: number): Promise<void>;
+    /**
+     * Set/replace a time-based volume automation curve (a fade envelope) on a track,
+     * or clear it with an empty array. Points are {time: seconds, db}; linear between
+     * points. Used by crossfade tracks to fade origin↔target across the looped
+     * transition. Optional — callers MUST null-check. @since SDK 2.25.0
+     */
+    setTrackVolumeAutomation?(trackId: string, points: Array<{
+        time: number;
+        db: number;
+    }>): Promise<void>;
     /** Set track pan (-1.0 left to 1.0 right). Only works on owned tracks. */
     setTrackPan(trackId: string, pan: number): Promise<void>;
     /** Set track solo state. Only works on owned tracks. */
@@ -537,6 +547,11 @@ interface PluginHost {
         key: string;
         mode: string;
     } | null>;
+    /**
+     * Read a scene's human display name by db id (for labelling a crossfade's
+     * origin/target scenes). Optional — callers MUST null-check. @since SDK 2.26.0
+     */
+    getSceneName?(sceneDbId: string): Promise<string | null>;
     /** Subscribe to transport state changes. Returns unsubscribe function. */
     onTransportEvent(listener: TransportEventListener): UnsubscribeFn;
     /** Subscribe to deck boundary events. Returns unsubscribe function. */
@@ -2592,6 +2607,10 @@ interface CrossfadePairMeta {
     sliderPos: number;
     originDbId: string;
     targetDbId: string;
+    /** DB id of the ORIGIN source track (in the from scene) — drives the "used once" exclusion. */
+    originSourceDbId: string;
+    /** DB id of the TARGET source track (in the to scene). */
+    targetSourceDbId: string;
     originSourceName: string;
     originSoundLabel: string;
     targetSourceName: string;
@@ -2606,6 +2625,28 @@ declare function asCrossfadeMeta(val: unknown): CrossfadeMeta | null;
  * row instead of vanishing.
  */
 declare function parseCrossfadePairs(sceneData: Record<string, unknown>): CrossfadePairMeta[];
+/** One volume-automation point: a dB value at a time offset (seconds from clip start). */
+interface VolumeAutomationPoint {
+    time: number;
+    db: number;
+}
+/** Origin + target volume curves for one crossfade pair. */
+interface CrossfadeVolumeCurves {
+    origin: VolumeAutomationPoint[];
+    target: VolumeAutomationPoint[];
+}
+/**
+ * Equal-power crossfade volume curves over a transition of `bars` at `bpm`.
+ * The ORIGIN layer fades OUT and the TARGET fades IN; `sliderPos` (0..1) sets
+ * WHERE in time the equal-power (-3 dB) crossover sits — 0 = hand off near the
+ * start, 1 = hold the origin until near the end. Points span the clip window
+ * [0, durationSeconds] so the engine re-reads them each loop (re-fade per loop).
+ * `steps`+1 points with linear interpolation approximate the cos/sin curve.
+ *
+ * Returns dB point arrays for `host.setTrackVolumeAutomation` — origin on the top
+ * layer, target on the bottom. @since SDK 2.25.0
+ */
+declare function buildCrossfadeVolumeCurves(bars: number, bpm: number, sliderPos: number, steps?: number): CrossfadeVolumeCurves;
 
 /**
  * CrossfadeTrackRow — a transition "crossfade track": two stacked TrackRows
@@ -2794,8 +2835,9 @@ declare function ImportTrackModal({ host, open, onClose, onImported, title, test
  *
  * Shown only inside a `scene_type='transition'` scene. The user picks an ORIGIN
  * track (from the transition's FROM scene) and a TARGET track (from its TO
- * scene). Crossfades are same-role: once an origin is chosen, the target
- * dropdown is filtered to the origin's role.
+ * scene), in ANY order — the only constraint is same plugin/family (the picker is
+ * per-panel). A source track already used in a crossfade is hidden (via
+ * excludeSourceDbIds), so each source is used at most once.
  *
  * Self-fetching: given the scoped `host`, it calls `host.listSceneFamilyTracks`
  * for both scenes (ungated — a transition deliberately bridges different keys).
@@ -2813,7 +2855,7 @@ interface CrossfadeSelection {
     dbId: string;
     /** Display name (for the row caption). */
     name: string;
-    /** Musical role (same for both — enforced by the picker). */
+    /** Musical role of the source track (the panel uses the TARGET's for generation). */
     role?: string;
 }
 interface CrossfadeModalProps {
@@ -2829,6 +2871,12 @@ interface CrossfadeModalProps {
     fromSceneName?: string;
     /** Display name for the target scene heading (optional). */
     toSceneName?: string;
+    /**
+     * Source-track DB ids already used in a crossfade (origin + target of every
+     * existing pair in this panel). Hidden from BOTH dropdowns so each source is
+     * used at most once. @since SDK 2.26.0
+     */
+    excludeSourceDbIds?: readonly string[];
     /** Close handler (Escape, backdrop, Cancel, or after a successful create). */
     onClose: () => void;
     /** Build the crossfade pair. Should reject on failure so the modal shows it. */
@@ -2836,7 +2884,7 @@ interface CrossfadeModalProps {
     /** data-testid prefix. */
     testIdPrefix?: string;
 }
-declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
+declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
 
 /**
  * ConfirmDialog — styled in-app confirmation modal (SDK component).
@@ -3561,7 +3609,7 @@ declare function useSoundHistory(applySound: (trackId: string, descriptor: unkno
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.24.0";
+declare const PLUGIN_SDK_VERSION = "2.26.0";
 
 /**
  * FX Preset Definitions
@@ -3709,4 +3757,4 @@ interface PickTopKOptions {
  */
 declare function pickTopKWeighted<T>(scored: ReadonlyArray<ScoredCandidate<T>>, options?: PickTopKOptions): T | null;
 
-export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, 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, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, 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 PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asCrossfadeMeta, buildCrossfadeInpaintPrompt, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };
+export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, type CrossfadeVolumeCurves, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, 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, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, 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 PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asCrossfadeMeta, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };

package/dist/index.d.ts

@@ -227,6 +227,16 @@ interface PluginHost {
     setTrackMute(trackId: string, muted: boolean): Promise<void>;
     /** Set track volume (linear 0.0 - 1.0). Only works on owned tracks. */
     setTrackVolume(trackId: string, volume: number): Promise<void>;
+    /**
+     * Set/replace a time-based volume automation curve (a fade envelope) on a track,
+     * or clear it with an empty array. Points are {time: seconds, db}; linear between
+     * points. Used by crossfade tracks to fade origin↔target across the looped
+     * transition. Optional — callers MUST null-check. @since SDK 2.25.0
+     */
+    setTrackVolumeAutomation?(trackId: string, points: Array<{
+        time: number;
+        db: number;
+    }>): Promise<void>;
     /** Set track pan (-1.0 left to 1.0 right). Only works on owned tracks. */
     setTrackPan(trackId: string, pan: number): Promise<void>;
     /** Set track solo state. Only works on owned tracks. */
@@ -537,6 +547,11 @@ interface PluginHost {
         key: string;
         mode: string;
     } | null>;
+    /**
+     * Read a scene's human display name by db id (for labelling a crossfade's
+     * origin/target scenes). Optional — callers MUST null-check. @since SDK 2.26.0
+     */
+    getSceneName?(sceneDbId: string): Promise<string | null>;
     /** Subscribe to transport state changes. Returns unsubscribe function. */
     onTransportEvent(listener: TransportEventListener): UnsubscribeFn;
     /** Subscribe to deck boundary events. Returns unsubscribe function. */
@@ -2592,6 +2607,10 @@ interface CrossfadePairMeta {
     sliderPos: number;
     originDbId: string;
     targetDbId: string;
+    /** DB id of the ORIGIN source track (in the from scene) — drives the "used once" exclusion. */
+    originSourceDbId: string;
+    /** DB id of the TARGET source track (in the to scene). */
+    targetSourceDbId: string;
     originSourceName: string;
     originSoundLabel: string;
     targetSourceName: string;
@@ -2606,6 +2625,28 @@ declare function asCrossfadeMeta(val: unknown): CrossfadeMeta | null;
  * row instead of vanishing.
  */
 declare function parseCrossfadePairs(sceneData: Record<string, unknown>): CrossfadePairMeta[];
+/** One volume-automation point: a dB value at a time offset (seconds from clip start). */
+interface VolumeAutomationPoint {
+    time: number;
+    db: number;
+}
+/** Origin + target volume curves for one crossfade pair. */
+interface CrossfadeVolumeCurves {
+    origin: VolumeAutomationPoint[];
+    target: VolumeAutomationPoint[];
+}
+/**
+ * Equal-power crossfade volume curves over a transition of `bars` at `bpm`.
+ * The ORIGIN layer fades OUT and the TARGET fades IN; `sliderPos` (0..1) sets
+ * WHERE in time the equal-power (-3 dB) crossover sits — 0 = hand off near the
+ * start, 1 = hold the origin until near the end. Points span the clip window
+ * [0, durationSeconds] so the engine re-reads them each loop (re-fade per loop).
+ * `steps`+1 points with linear interpolation approximate the cos/sin curve.
+ *
+ * Returns dB point arrays for `host.setTrackVolumeAutomation` — origin on the top
+ * layer, target on the bottom. @since SDK 2.25.0
+ */
+declare function buildCrossfadeVolumeCurves(bars: number, bpm: number, sliderPos: number, steps?: number): CrossfadeVolumeCurves;
 
 /**
  * CrossfadeTrackRow — a transition "crossfade track": two stacked TrackRows
@@ -2794,8 +2835,9 @@ declare function ImportTrackModal({ host, open, onClose, onImported, title, test
  *
  * Shown only inside a `scene_type='transition'` scene. The user picks an ORIGIN
  * track (from the transition's FROM scene) and a TARGET track (from its TO
- * scene). Crossfades are same-role: once an origin is chosen, the target
- * dropdown is filtered to the origin's role.
+ * scene), in ANY order — the only constraint is same plugin/family (the picker is
+ * per-panel). A source track already used in a crossfade is hidden (via
+ * excludeSourceDbIds), so each source is used at most once.
  *
  * Self-fetching: given the scoped `host`, it calls `host.listSceneFamilyTracks`
  * for both scenes (ungated — a transition deliberately bridges different keys).
@@ -2813,7 +2855,7 @@ interface CrossfadeSelection {
     dbId: string;
     /** Display name (for the row caption). */
     name: string;
-    /** Musical role (same for both — enforced by the picker). */
+    /** Musical role of the source track (the panel uses the TARGET's for generation). */
     role?: string;
 }
 interface CrossfadeModalProps {
@@ -2829,6 +2871,12 @@ interface CrossfadeModalProps {
     fromSceneName?: string;
     /** Display name for the target scene heading (optional). */
     toSceneName?: string;
+    /**
+     * Source-track DB ids already used in a crossfade (origin + target of every
+     * existing pair in this panel). Hidden from BOTH dropdowns so each source is
+     * used at most once. @since SDK 2.26.0
+     */
+    excludeSourceDbIds?: readonly string[];
     /** Close handler (Escape, backdrop, Cancel, or after a successful create). */
     onClose: () => void;
     /** Build the crossfade pair. Should reject on failure so the modal shows it. */
@@ -2836,7 +2884,7 @@ interface CrossfadeModalProps {
     /** data-testid prefix. */
     testIdPrefix?: string;
 }
-declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
+declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
 
 /**
  * ConfirmDialog — styled in-app confirmation modal (SDK component).
@@ -3561,7 +3609,7 @@ declare function useSoundHistory(applySound: (trackId: string, descriptor: unkno
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.24.0";
+declare const PLUGIN_SDK_VERSION = "2.26.0";
 
 /**
  * FX Preset Definitions
@@ -3709,4 +3757,4 @@ interface PickTopKOptions {
  */
 declare function pickTopKWeighted<T>(scored: ReadonlyArray<ScoredCandidate<T>>, options?: PickTopKOptions): T | null;
 
-export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, 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, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, 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 PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asCrossfadeMeta, buildCrossfadeInpaintPrompt, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };
+export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, type CrossfadeVolumeCurves, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, 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, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, 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 PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asCrossfadeMeta, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };

package/dist/index.js

@@ -73,6 +73,7 @@ __export(index_exports, {
   analyzeWavPeak: () => analyzeWavPeak,
   asCrossfadeMeta: () => asCrossfadeMeta,
   buildCrossfadeInpaintPrompt: () => buildCrossfadeInpaintPrompt,
+  buildCrossfadeVolumeCurves: () => buildCrossfadeVolumeCurves,
   calculateTimeBasedTarget: () => calculateTimeBasedTarget,
   cellToPx: () => cellToPx,
   centerScrollTop: () => centerScrollTop,
@@ -2569,6 +2570,8 @@ function parseCrossfadePairs(sceneData) {
       sliderPos: g.origin.meta.sliderPos,
       originDbId: g.origin.dbId,
       targetDbId: g.target.dbId,
+      originSourceDbId: g.origin.meta.sourceTrackDbId,
+      targetSourceDbId: g.target.meta.sourceTrackDbId,
       originSourceName: g.origin.meta.sourceName,
       originSoundLabel: g.origin.meta.soundLabel,
       targetSourceName: g.target.meta.sourceName,
@@ -2577,6 +2580,25 @@ function parseCrossfadePairs(sceneData) {
   }
   return pairs;
 }
+var FADE_FLOOR_DB = -80;
+function gainToDb(gain) {
+  return gain <= 1e-4 ? FADE_FLOOR_DB : Math.max(FADE_FLOOR_DB, 20 * Math.log10(gain));
+}
+function buildCrossfadeVolumeCurves(bars, bpm, sliderPos, steps = 32) {
+  const durationSeconds = bars * 4 * 60 / Math.max(1, bpm);
+  const s = Math.min(0.98, Math.max(0.02, sliderPos));
+  const round = (n) => Math.round(n * 1e3) / 1e3;
+  const origin = [];
+  const target = [];
+  for (let i = 0; i <= steps; i++) {
+    const x = i / steps;
+    const time = round(x * durationSeconds);
+    const theta = x <= s ? x / s * (Math.PI / 4) : Math.PI / 4 + (x - s) / (1 - s) * (Math.PI / 4);
+    origin.push({ time, db: Math.round(gainToDb(Math.cos(theta)) * 100) / 100 });
+    target.push({ time, db: Math.round(gainToDb(Math.sin(theta)) * 100) / 100 });
+  }
+  return { origin, target };
+}
 
 // src/crossfade-inpaint.ts
 var PITCH_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
@@ -2825,6 +2847,7 @@ function CrossfadeModal({
   toSceneId,
   fromSceneName,
   toSceneName,
+  excludeSourceDbIds,
   onClose,
   onCreate,
   testIdPrefix = "crossfade-modal"
@@ -2834,6 +2857,8 @@ function CrossfadeModal({
   const [targetDbId, setTargetDbId] = (0, import_react12.useState)("");
   const [isCreating, setIsCreating] = (0, import_react12.useState)(false);
   const [error, setError] = (0, import_react12.useState)(null);
+  const [fromName, setFromName] = (0, import_react12.useState)(null);
+  const [toName, setToName] = (0, import_react12.useState)(null);
   const cancelRef = (0, import_react12.useRef)(null);
   const refresh = (0, import_react12.useCallback)(async () => {
     if (!host.listSceneFamilyTracks) {
@@ -2842,12 +2867,15 @@ function CrossfadeModal({
     }
     setLoad({ status: "loading" });
     try {
-      const [origin, target] = await Promise.all([
+      const [origin, target, fName, tName] = await Promise.all([
         host.listSceneFamilyTracks(fromSceneId),
-        host.listSceneFamilyTracks(toSceneId)
+        host.listSceneFamilyTracks(toSceneId),
+        host.getSceneName ? host.getSceneName(fromSceneId) : Promise.resolve(null),
+        host.getSceneName ? host.getSceneName(toSceneId) : Promise.resolve(null)
       ]);
+      setFromName(fName);
+      setToName(tName);
       setLoad({ status: "ready", origin, target });
-      setOriginDbId(origin[0]?.dbId ?? "");
     } catch (err) {
       setLoad({ status: "error", message: err instanceof Error ? err.message : "Failed to load tracks." });
     }
@@ -2861,21 +2889,26 @@ function CrossfadeModal({
       void refresh();
     }
   }, [open, refresh]);
-  const originTrack = (0, import_react12.useMemo)(
-    () => load.status === "ready" ? load.origin.find((t) => t.dbId === originDbId) ?? null : null,
-    [load, originDbId]
+  const excludeSet = (0, import_react12.useMemo)(() => new Set(excludeSourceDbIds ?? []), [excludeSourceDbIds]);
+  const originCandidates = (0, import_react12.useMemo)(
+    () => load.status === "ready" ? load.origin.filter((t) => !excludeSet.has(t.dbId)) : [],
+    [load, excludeSet]
   );
-  const originRole = originTrack?.role;
-  const targetCandidates = (0, import_react12.useMemo)(() => {
-    if (load.status !== "ready") return [];
-    if (!originRole) return load.target;
-    return load.target.filter((t) => t.role === originRole);
-  }, [load, originRole]);
+  const targetCandidates = (0, import_react12.useMemo)(
+    () => load.status === "ready" ? load.target.filter((t) => !excludeSet.has(t.dbId)) : [],
+    [load, excludeSet]
+  );
+  (0, import_react12.useEffect)(() => {
+    if (!originCandidates.some((t) => t.dbId === originDbId)) {
+      setOriginDbId(originCandidates[0]?.dbId ?? "");
+    }
+  }, [originCandidates, originDbId]);
   (0, import_react12.useEffect)(() => {
     if (!targetCandidates.some((t) => t.dbId === targetDbId)) {
       setTargetDbId(targetCandidates[0]?.dbId ?? "");
     }
   }, [targetCandidates, targetDbId]);
+  const originTrack = originCandidates.find((t) => t.dbId === originDbId) ?? null;
   const targetTrack = targetCandidates.find((t) => t.dbId === targetDbId) ?? null;
   const canCreate = !isCreating && !!originTrack && !!targetTrack;
   const handleClose = (0, import_react12.useCallback)(() => {
@@ -2896,6 +2929,8 @@ function CrossfadeModal({
       setIsCreating(false);
     }
   }, [originTrack, targetTrack, onCreate, onClose]);
+  const fromLabel = fromName ?? fromSceneName ?? null;
+  const toLabel = toName ?? toSceneName ?? null;
   if (!open) return null;
   return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(Modal, { open, onClose: handleClose, testIdPrefix, initialFocusRef: cancelRef, children: /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(
     "div",
@@ -2908,24 +2943,31 @@ function CrossfadeModal({
         /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("p", { className: "text-[11px] text-sas-muted leading-relaxed", children: [
           "Bridge a track from",
           " ",
-          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: fromSceneName ?? "the origin scene" }),
+          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: fromLabel ?? "the origin scene" }),
           " into one from",
           " ",
-          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: toSceneName ?? "the target scene" }),
+          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: toLabel ?? "the target scene" }),
           ". Both layers share one generated part; each keeps its own preset."
         ] }),
         load.status === "loading" && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { className: "text-xs text-sas-muted py-4 text-center", children: "Loading tracks\u2026" }),
         load.status === "error" && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { className: "text-xs text-sas-danger py-4 text-center", children: load.message }),
-        load.status === "ready" && (load.origin.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
+        load.status === "ready" && (originCandidates.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(
           "div",
           {
             className: "text-xs text-sas-muted py-4 text-center",
             "data-testid": `${testIdPrefix}-empty-origin`,
-            children: "No matching tracks in the origin scene. Add one there first."
+            children: [
+              "No available tracks in ",
+              fromLabel ?? "the origin scene",
+              ". Add one (or free one from another crossfade) first."
+            ]
           }
         ) : /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(import_jsx_runtime14.Fragment, { children: [
           /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("label", { className: "block", children: [
-            /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-[10px] uppercase tracking-wide text-sas-muted", children: "Origin (top)" }),
+            /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("span", { className: "text-[10px] uppercase tracking-wide text-sas-muted", children: [
+              "Origin ",
+              fromLabel ? `(${fromLabel})` : "(top)"
+            ] }),
             /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
               "select",
               {
@@ -2934,7 +2976,7 @@ function CrossfadeModal({
                 onChange: (e) => setOriginDbId(e.target.value),
                 disabled: isCreating,
                 className: "sas-input w-full mt-0.5 text-xs",
-                children: load.origin.map((t) => /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("option", { value: t.dbId, children: [
+                children: originCandidates.map((t) => /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("option", { value: t.dbId, children: [
                   t.name,
                   t.role ? ` \xB7 ${t.role}` : ""
                 ] }, t.dbId))
@@ -2943,13 +2985,13 @@ function CrossfadeModal({
           ] }),
           /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("label", { className: "block", children: [
             /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("span", { className: "text-[10px] uppercase tracking-wide text-sas-muted", children: [
-              "Target (bottom)",
-              originRole ? ` \xB7 ${originRole}` : ""
+              "Target ",
+              toLabel ? `(${toLabel})` : "(bottom)"
             ] }),
             targetCandidates.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { className: "text-xs text-sas-danger mt-0.5", "data-testid": `${testIdPrefix}-empty-target`, children: [
-              "No ",
-              originRole ?? "matching",
-              " track in the target scene to crossfade into."
+              "No available tracks in ",
+              toLabel ?? "the target scene",
+              " to crossfade into."
             ] }) : /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
               "select",
               {
@@ -3868,7 +3910,7 @@ function useTrackReorder({
 }
 
 // src/constants/sdk-version.ts
-var PLUGIN_SDK_VERSION = "2.24.0";
+var PLUGIN_SDK_VERSION = "2.26.0";
 
 // src/utils/format-concurrent-tracks.ts
 function formatConcurrentTracks(ctx) {
@@ -4055,6 +4097,7 @@ function pickTopKWeighted(scored, options = {}) {
   analyzeWavPeak,
   asCrossfadeMeta,
   buildCrossfadeInpaintPrompt,
+  buildCrossfadeVolumeCurves,
   calculateTimeBasedTarget,
   cellToPx,
   centerScrollTop,