@signalsandsorcery/plugin-sdk 2.26.1 → 2.28.1

package/dist/index.d.mts

@@ -1197,6 +1197,10 @@ interface SceneFamilyTrack {
     name: string;
     /** Musical role if set — used to enforce same-role crossfade pairing. */
     role?: string;
+    /** Generation prompt, when the track was AI-generated. The crossfade picker
+     * shows this as the primary label (users recognise tracks by prompt, not id).
+     * @since SDK 2.27.0 */
+    prompt?: string;
 }
 /**
  * One OTHER scene and its candidate tracks (already type-filtered). Scenes with
@@ -2772,6 +2776,215 @@ interface CrossfadeInpaintInput {
  */
 declare function buildCrossfadeInpaintPrompt(input: CrossfadeInpaintInput): string;
 
+/**
+ * Fade metadata — family-agnostic types + parsing for transition orphan fades
+ * (synth / drum / instrument panels).
+ *
+ * A fade is a CROSSFADE WITH ONE EMPTY ENDPOINT: a single generated track that
+ * either fades IN (a target-only track entering — `morph(∅ → target)`) or fades
+ * OUT (an origin-only track leaving — `morph(origin → ∅)`) across the transition
+ * loop. It reuses the same generation pipeline (`buildCrossfadeInpaintPrompt`
+ * with one empty endpoint) and the same volume-automation fader as crossfade.
+ *
+ * Stored in scene plugin_data under `track:<dbId>:fade` (ONE entry per track —
+ * unlike crossfade there is no partner / groupId). Kept as a SEPARATE type from
+ * crossfade so the load-bearing "drop a half-broken pair" guard in
+ * `parseCrossfadePairs` stays intact.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** Which way the lone track fades over the transition. */
+type FadeDirection = 'in' | 'out';
+/**
+ * How the fade is shaped:
+ * - `volume` — a one-sided level ramp does the work (DJ-style). Best for
+ *   textural/sustained material (pads, atmospheres).
+ * - `build` — the MIDI carries the fade (the inpaint grows sparse→full on the way
+ *   in, or dissolves on the way out); the level stays flat. Best for articulated
+ *   material (lead, bass, drums, winds, vocals).
+ */
+type FadeGesture = 'volume' | 'build';
+/** Per-track fade metadata (one scene-data value per fade track). */
+interface FadeMeta {
+    direction: FadeDirection;
+    gesture: FadeGesture;
+    /** DB id of the SOURCE track this fade's preset/sample + pattern was seeded from. */
+    sourceTrackDbId: string;
+    /** DB id of the scene the source track lives in (the from/to scene). */
+    sourceSceneId: string;
+    /** Source track display name (shown in the caption). */
+    sourceName: string;
+    /** Copied preset/sample label (shown in the caption). */
+    soundLabel: string;
+    /** Fade position 0..1 — WHERE in time the fade midpoint sits. */
+    sliderPos: number;
+}
+/** A fade entry resolved from scene data: the fade track's dbId + its metadata. */
+interface FadeEntry {
+    dbId: string;
+    meta: FadeMeta;
+}
+/** Narrow an unknown scene-data value to FadeMeta (defensive — survives partial blobs). */
+declare function asFadeMeta(val: unknown): FadeMeta | null;
+/**
+ * Scan all `track:<dbId>:fade` keys in a scene's plugin_data and return one entry
+ * per valid fade. Unlike crossfade there is no grouping or both-present gate — a
+ * fade is intrinsically a single track.
+ */
+declare function parseFades(sceneData: Record<string, unknown>): FadeEntry[];
+/**
+ * Build a ONE-sided volume-automation curve for a fade over `bars` at `bpm`.
+ *
+ * - `gesture === 'build'` → flat at unity (0 dB). The compositional build in the
+ *   MIDI carries the fade; layering a volume ramp on top would double-fade.
+ * - `gesture === 'volume'` → an equal-power ramp identical to ONE half of
+ *   `buildCrossfadeVolumeCurves`: fade-out ≡ its `origin` curve (unity→floor),
+ *   fade-in ≡ its `target` curve (floor→unity). `sliderPos` sets WHERE the −3 dB
+ *   midpoint sits in time.
+ *
+ * Points span [0, durationSeconds] so the engine re-reads them each loop. Returns
+ * dB points for `host.setTrackVolumeAutomation`.
+ *
+ * @since SDK 2.28.0
+ */
+declare function buildFadeVolumeCurve(bars: number, bpm: number, direction: FadeDirection, sliderPos: number, gesture: FadeGesture, steps?: number): VolumeAutomationPoint[];
+/**
+ * Roles whose fades default to a `volume` (level) ramp — sustained/textural
+ * material that enters/leaves by level in real productions. Everything else
+ * defaults to `build` (the notes carry the fade).
+ *
+ * This is a UI default heuristic over role tokens, NOT the canonical role list
+ * (that lives in the app's instrument-classification + `host.getValidRoles()`).
+ * There is no textural↔articulated axis in the taxonomy, so this small curated
+ * subset lives next to its consumer (the fade modal/panels).
+ *
+ * @since SDK 2.28.0
+ */
+declare const TEXTURAL_ROLES: ReadonlySet<string>;
+/** Pick the default fade gesture for a track's role (textural → volume, else build). */
+declare function defaultFadeGesture(role: string | null | undefined): FadeGesture;
+
+/**
+ * FadeTrackRow — a transition "fade track": a single locked TrackRow with a
+ * direction badge (Fade in / Fade out) and a one-sided fade slider.
+ *
+ * A fade is a crossfade with one empty endpoint — a lone generated track that
+ * either enters (fade in, for a target-only track) or leaves (fade out, for an
+ * origin-only track) across the transition loop. Like a crossfade layer, the
+ * sound/generation controls are omitted (the SDK TrackRow is "controlled by
+ * omission"): no shuffle / Create / preset-pick / FX / drawer / inner-delete.
+ * What remains: per-track volume/pan/mute/solo and a single delete.
+ *
+ * The slider represents WHERE in the loop the fade sits (earlier ↔ later). Omit
+ * `onSliderChange` to render it read-only.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** The single (engine track) layer of a fade. */
+interface FadeLayer {
+    /** Engine track id of this fade's track (also the meter key). */
+    trackId: string;
+    /** Display name of this fade's (newly created) track. */
+    name: string;
+    /** Musical role (drives the auto gesture). */
+    role?: string;
+    /** Name of the SOURCE track this fade was seeded from (origin/target scene). */
+    sourceName?: string;
+    /** Human label of the copied preset/sound, shown in the caption. */
+    soundLabel?: string;
+    /** Playback state for this track. */
+    runtimeState: {
+        muted: boolean;
+        solo: boolean;
+        volume: number;
+        pan: number;
+    };
+}
+interface FadeTrackRowProps {
+    /** The lone fade track. */
+    layer: FadeLayer;
+    /** 'in' (enters across the loop) or 'out' (leaves across the loop). */
+    direction: FadeDirection;
+    /** How the fade is shaped — shown read-only (volume = level ramp, build = notes). */
+    gesture: FadeGesture;
+    /** Fade position 0..1 — WHERE in time the fade sits. Defaults centered. */
+    sliderPos?: number;
+    /** Toggle mute. */
+    onMuteToggle: () => void;
+    /** Toggle solo. */
+    onSoloToggle: () => void;
+    /** Change the track's volume. */
+    onVolumeChange: (volume: number) => void;
+    /** Change the track's pan. */
+    onPanChange: (pan: number) => void;
+    /** Delete the fade. */
+    onDelete: () => void;
+    /** Move the fade point. Omit to render the slider read-only. */
+    onSliderChange?: (pos: number) => void;
+    /** Shared meter handle (welds a peak meter to the track). */
+    levels?: TrackLevelsHandle;
+    /** Left-border accent. Defaults to transition purple. */
+    accentColor?: string;
+}
+declare function FadeTrackRow({ layer, direction, gesture, sliderPos, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onDelete, onSliderChange, levels, accentColor, }: FadeTrackRowProps): React.ReactElement;
+
+/**
+ * FadeModal — "add a fade" picker for a transition scene.
+ *
+ * Shown only inside a `scene_type='transition'` scene. It self-fetches the FROM
+ * (origin) and TO (target) scenes' family tracks and diffs them by role to find
+ * ORPHANS — tracks with no counterpart on the other side:
+ *   - origin-only surplus → "Fade out" candidates (the track leaves)
+ *   - target-only surplus → "Fade in" candidates (the track enters)
+ * Tracks whose role is matched on both sides are crossfade territory and are NOT
+ * shown here. A source already used in a crossfade or a fade is hidden (via
+ * excludeSourceDbIds).
+ *
+ * The fade GESTURE (volume vs build) is auto-selected from the track's role and
+ * shown read-only — the user does not choose it. On confirm the modal hands the
+ * selection + direction + gesture to `onCreate`, which the panel implements
+ * (create one track, generate a chord-conforming part, copy the sound, apply a
+ * one-sided volume curve). `onCreate` should reject on failure so the modal can
+ * show it and stay open.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** A picked orphan track handed to `onCreate`. */
+interface FadeSelection {
+    /** Source track DB id (selector for getTrackSound + seeding the part). */
+    dbId: string;
+    /** Display name (for the row caption). */
+    name: string;
+    /** Musical role of the source track (drives the auto gesture). */
+    role?: string;
+}
+interface FadeModalProps {
+    /** Scoped host — the modal calls listSceneFamilyTracks itself. */
+    host: PluginHost;
+    /** Controls visibility (the panel owns open/closed from its header button). */
+    open: boolean;
+    /** DB id of the transition's FROM (origin) scene. */
+    fromSceneId: string;
+    /** DB id of the transition's TO (target) scene. */
+    toSceneId: string;
+    /** Display name for the origin scene heading (optional). */
+    fromSceneName?: string;
+    /** Display name for the target scene heading (optional). */
+    toSceneName?: string;
+    /** Source-track DB ids already used in a crossfade OR a fade — hidden here. */
+    excludeSourceDbIds?: readonly string[];
+    /** Close handler (Escape, backdrop, Cancel, or after a successful create). */
+    onClose: () => void;
+    /** Build the fade. Should reject on failure so the modal shows it. */
+    onCreate: (selection: FadeSelection, direction: FadeDirection, gesture: FadeGesture) => Promise<void>;
+    /** data-testid prefix. */
+    testIdPrefix?: string;
+}
+declare function FadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: FadeModalProps): React.ReactElement | null;
+
 /**
  * ImportTrackModal — "import a track from another scene" picker (SDK component).
  *
@@ -3609,7 +3822,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.26.0";
+declare const PLUGIN_SDK_VERSION = "2.28.0";
 
 /**
  * FX Preset Definitions
@@ -3757,4 +3970,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, 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 };
+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 FadeDirection, type FadeEntry, type FadeGesture, type FadeLayer, type FadeMeta, FadeModal, type FadeModalProps, type FadeSelection, FadeTrackRow, type FadeTrackRowProps, 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, TEXTURAL_ROLES, 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, asFadeMeta, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildFadeVolumeCurve, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, defaultFadeGesture, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, parseFades, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };

package/dist/index.d.ts

@@ -1197,6 +1197,10 @@ interface SceneFamilyTrack {
     name: string;
     /** Musical role if set — used to enforce same-role crossfade pairing. */
     role?: string;
+    /** Generation prompt, when the track was AI-generated. The crossfade picker
+     * shows this as the primary label (users recognise tracks by prompt, not id).
+     * @since SDK 2.27.0 */
+    prompt?: string;
 }
 /**
  * One OTHER scene and its candidate tracks (already type-filtered). Scenes with
@@ -2772,6 +2776,215 @@ interface CrossfadeInpaintInput {
  */
 declare function buildCrossfadeInpaintPrompt(input: CrossfadeInpaintInput): string;
 
+/**
+ * Fade metadata — family-agnostic types + parsing for transition orphan fades
+ * (synth / drum / instrument panels).
+ *
+ * A fade is a CROSSFADE WITH ONE EMPTY ENDPOINT: a single generated track that
+ * either fades IN (a target-only track entering — `morph(∅ → target)`) or fades
+ * OUT (an origin-only track leaving — `morph(origin → ∅)`) across the transition
+ * loop. It reuses the same generation pipeline (`buildCrossfadeInpaintPrompt`
+ * with one empty endpoint) and the same volume-automation fader as crossfade.
+ *
+ * Stored in scene plugin_data under `track:<dbId>:fade` (ONE entry per track —
+ * unlike crossfade there is no partner / groupId). Kept as a SEPARATE type from
+ * crossfade so the load-bearing "drop a half-broken pair" guard in
+ * `parseCrossfadePairs` stays intact.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** Which way the lone track fades over the transition. */
+type FadeDirection = 'in' | 'out';
+/**
+ * How the fade is shaped:
+ * - `volume` — a one-sided level ramp does the work (DJ-style). Best for
+ *   textural/sustained material (pads, atmospheres).
+ * - `build` — the MIDI carries the fade (the inpaint grows sparse→full on the way
+ *   in, or dissolves on the way out); the level stays flat. Best for articulated
+ *   material (lead, bass, drums, winds, vocals).
+ */
+type FadeGesture = 'volume' | 'build';
+/** Per-track fade metadata (one scene-data value per fade track). */
+interface FadeMeta {
+    direction: FadeDirection;
+    gesture: FadeGesture;
+    /** DB id of the SOURCE track this fade's preset/sample + pattern was seeded from. */
+    sourceTrackDbId: string;
+    /** DB id of the scene the source track lives in (the from/to scene). */
+    sourceSceneId: string;
+    /** Source track display name (shown in the caption). */
+    sourceName: string;
+    /** Copied preset/sample label (shown in the caption). */
+    soundLabel: string;
+    /** Fade position 0..1 — WHERE in time the fade midpoint sits. */
+    sliderPos: number;
+}
+/** A fade entry resolved from scene data: the fade track's dbId + its metadata. */
+interface FadeEntry {
+    dbId: string;
+    meta: FadeMeta;
+}
+/** Narrow an unknown scene-data value to FadeMeta (defensive — survives partial blobs). */
+declare function asFadeMeta(val: unknown): FadeMeta | null;
+/**
+ * Scan all `track:<dbId>:fade` keys in a scene's plugin_data and return one entry
+ * per valid fade. Unlike crossfade there is no grouping or both-present gate — a
+ * fade is intrinsically a single track.
+ */
+declare function parseFades(sceneData: Record<string, unknown>): FadeEntry[];
+/**
+ * Build a ONE-sided volume-automation curve for a fade over `bars` at `bpm`.
+ *
+ * - `gesture === 'build'` → flat at unity (0 dB). The compositional build in the
+ *   MIDI carries the fade; layering a volume ramp on top would double-fade.
+ * - `gesture === 'volume'` → an equal-power ramp identical to ONE half of
+ *   `buildCrossfadeVolumeCurves`: fade-out ≡ its `origin` curve (unity→floor),
+ *   fade-in ≡ its `target` curve (floor→unity). `sliderPos` sets WHERE the −3 dB
+ *   midpoint sits in time.
+ *
+ * Points span [0, durationSeconds] so the engine re-reads them each loop. Returns
+ * dB points for `host.setTrackVolumeAutomation`.
+ *
+ * @since SDK 2.28.0
+ */
+declare function buildFadeVolumeCurve(bars: number, bpm: number, direction: FadeDirection, sliderPos: number, gesture: FadeGesture, steps?: number): VolumeAutomationPoint[];
+/**
+ * Roles whose fades default to a `volume` (level) ramp — sustained/textural
+ * material that enters/leaves by level in real productions. Everything else
+ * defaults to `build` (the notes carry the fade).
+ *
+ * This is a UI default heuristic over role tokens, NOT the canonical role list
+ * (that lives in the app's instrument-classification + `host.getValidRoles()`).
+ * There is no textural↔articulated axis in the taxonomy, so this small curated
+ * subset lives next to its consumer (the fade modal/panels).
+ *
+ * @since SDK 2.28.0
+ */
+declare const TEXTURAL_ROLES: ReadonlySet<string>;
+/** Pick the default fade gesture for a track's role (textural → volume, else build). */
+declare function defaultFadeGesture(role: string | null | undefined): FadeGesture;
+
+/**
+ * FadeTrackRow — a transition "fade track": a single locked TrackRow with a
+ * direction badge (Fade in / Fade out) and a one-sided fade slider.
+ *
+ * A fade is a crossfade with one empty endpoint — a lone generated track that
+ * either enters (fade in, for a target-only track) or leaves (fade out, for an
+ * origin-only track) across the transition loop. Like a crossfade layer, the
+ * sound/generation controls are omitted (the SDK TrackRow is "controlled by
+ * omission"): no shuffle / Create / preset-pick / FX / drawer / inner-delete.
+ * What remains: per-track volume/pan/mute/solo and a single delete.
+ *
+ * The slider represents WHERE in the loop the fade sits (earlier ↔ later). Omit
+ * `onSliderChange` to render it read-only.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** The single (engine track) layer of a fade. */
+interface FadeLayer {
+    /** Engine track id of this fade's track (also the meter key). */
+    trackId: string;
+    /** Display name of this fade's (newly created) track. */
+    name: string;
+    /** Musical role (drives the auto gesture). */
+    role?: string;
+    /** Name of the SOURCE track this fade was seeded from (origin/target scene). */
+    sourceName?: string;
+    /** Human label of the copied preset/sound, shown in the caption. */
+    soundLabel?: string;
+    /** Playback state for this track. */
+    runtimeState: {
+        muted: boolean;
+        solo: boolean;
+        volume: number;
+        pan: number;
+    };
+}
+interface FadeTrackRowProps {
+    /** The lone fade track. */
+    layer: FadeLayer;
+    /** 'in' (enters across the loop) or 'out' (leaves across the loop). */
+    direction: FadeDirection;
+    /** How the fade is shaped — shown read-only (volume = level ramp, build = notes). */
+    gesture: FadeGesture;
+    /** Fade position 0..1 — WHERE in time the fade sits. Defaults centered. */
+    sliderPos?: number;
+    /** Toggle mute. */
+    onMuteToggle: () => void;
+    /** Toggle solo. */
+    onSoloToggle: () => void;
+    /** Change the track's volume. */
+    onVolumeChange: (volume: number) => void;
+    /** Change the track's pan. */
+    onPanChange: (pan: number) => void;
+    /** Delete the fade. */
+    onDelete: () => void;
+    /** Move the fade point. Omit to render the slider read-only. */
+    onSliderChange?: (pos: number) => void;
+    /** Shared meter handle (welds a peak meter to the track). */
+    levels?: TrackLevelsHandle;
+    /** Left-border accent. Defaults to transition purple. */
+    accentColor?: string;
+}
+declare function FadeTrackRow({ layer, direction, gesture, sliderPos, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onDelete, onSliderChange, levels, accentColor, }: FadeTrackRowProps): React.ReactElement;
+
+/**
+ * FadeModal — "add a fade" picker for a transition scene.
+ *
+ * Shown only inside a `scene_type='transition'` scene. It self-fetches the FROM
+ * (origin) and TO (target) scenes' family tracks and diffs them by role to find
+ * ORPHANS — tracks with no counterpart on the other side:
+ *   - origin-only surplus → "Fade out" candidates (the track leaves)
+ *   - target-only surplus → "Fade in" candidates (the track enters)
+ * Tracks whose role is matched on both sides are crossfade territory and are NOT
+ * shown here. A source already used in a crossfade or a fade is hidden (via
+ * excludeSourceDbIds).
+ *
+ * The fade GESTURE (volume vs build) is auto-selected from the track's role and
+ * shown read-only — the user does not choose it. On confirm the modal hands the
+ * selection + direction + gesture to `onCreate`, which the panel implements
+ * (create one track, generate a chord-conforming part, copy the sound, apply a
+ * one-sided volume curve). `onCreate` should reject on failure so the modal can
+ * show it and stay open.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** A picked orphan track handed to `onCreate`. */
+interface FadeSelection {
+    /** Source track DB id (selector for getTrackSound + seeding the part). */
+    dbId: string;
+    /** Display name (for the row caption). */
+    name: string;
+    /** Musical role of the source track (drives the auto gesture). */
+    role?: string;
+}
+interface FadeModalProps {
+    /** Scoped host — the modal calls listSceneFamilyTracks itself. */
+    host: PluginHost;
+    /** Controls visibility (the panel owns open/closed from its header button). */
+    open: boolean;
+    /** DB id of the transition's FROM (origin) scene. */
+    fromSceneId: string;
+    /** DB id of the transition's TO (target) scene. */
+    toSceneId: string;
+    /** Display name for the origin scene heading (optional). */
+    fromSceneName?: string;
+    /** Display name for the target scene heading (optional). */
+    toSceneName?: string;
+    /** Source-track DB ids already used in a crossfade OR a fade — hidden here. */
+    excludeSourceDbIds?: readonly string[];
+    /** Close handler (Escape, backdrop, Cancel, or after a successful create). */
+    onClose: () => void;
+    /** Build the fade. Should reject on failure so the modal shows it. */
+    onCreate: (selection: FadeSelection, direction: FadeDirection, gesture: FadeGesture) => Promise<void>;
+    /** data-testid prefix. */
+    testIdPrefix?: string;
+}
+declare function FadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: FadeModalProps): React.ReactElement | null;
+
 /**
  * ImportTrackModal — "import a track from another scene" picker (SDK component).
  *
@@ -3609,7 +3822,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.26.0";
+declare const PLUGIN_SDK_VERSION = "2.28.0";
 
 /**
  * FX Preset Definitions
@@ -3757,4 +3970,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, 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 };
+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 FadeDirection, type FadeEntry, type FadeGesture, type FadeLayer, type FadeMeta, FadeModal, type FadeModalProps, type FadeSelection, FadeTrackRow, type FadeTrackRowProps, 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, TEXTURAL_ROLES, 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, asFadeMeta, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildFadeVolumeCurve, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, defaultFadeGesture, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, parseFades, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };