@signalsandsorcery/plugin-sdk 2.35.6 → 2.35.8

package/dist/index.d.mts

@@ -348,8 +348,17 @@ interface PluginHost {
      * pool; the current preset is always implicitly excluded. Use this to
      * implement a "no-repeat until full cycle" shuffle: the panel accumulates
      * the history and resets when shufflePreset throws "no presets available".
-     */
-    shufflePreset(trackId: string, excludeNames?: readonly string[]): Promise<ShufflePresetResult>;
+     *
+     * `options.description` (since SDK 2.44.0) is the user's sound description
+     * for semantic retrieval — when the host's patch index is available the pick
+     * is vector-proximity against this text instead of random-within-category.
+     * Pass the live prompt from panel state (host-side stored prompts are
+     * debounced and may lag). Member voices of a group should pass the ANCHOR's
+     * prompt, optionally suffixed with the voice label ("horn section — bass
+     * register"). Omitting it falls back to the prompt stored on the track, and
+     * failing that, the legacy random pick.
+     */
+    shufflePreset(trackId: string, excludeNames?: readonly string[], options?: ShufflePresetOptions): 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>;
     /**
@@ -2014,6 +2023,18 @@ interface PluginPresetData {
     /** Base64-encoded plugin state — pass to setPluginState() */
     state: string;
 }
+/**
+ * Options for shufflePreset().
+ * @since SDK 2.44.0
+ */
+interface ShufflePresetOptions {
+    /**
+     * The user's sound description ("muted trumpet", "warm analog pads").
+     * Enables semantic (vector-proximity) preset retrieval on hosts that ship a
+     * patch index; hosts without one ignore it and pick random-within-category.
+     */
+    description?: string;
+}
 /** Result of shufflePreset() — the new preset that was applied */
 interface ShufflePresetResult {
     presetName: string;
@@ -4922,6 +4943,13 @@ interface PanelTransitionGroupAdapter {
     /** Group-fade row header label, e.g. `Bassline (3 voices)`. Default `Group (N tracks)`. */
     groupRowLabel?(memberCount: number): string;
 }
+/** What `onTrackCreated` gets to work with (Add Track is scene-gated, so the scene is non-null). */
+interface TrackCreatedContext {
+    /** Scene the track was created in. */
+    activeSceneId: string;
+    /** The ONE scene-data key builder (always dbId-based). */
+    trackDataKey: (dbId: string, suffix: string) => string;
+}
 interface GeneratorPanelAdapter<M = unknown> {
     identity: PanelIdentity;
     features: PanelFeatureFlags;
@@ -4932,6 +4960,18 @@ interface GeneratorPanelAdapter<M = unknown> {
      * Synth: `host.shufflePreset(handle.id)` non-fatal.
      */
     applyPortedTrackSound(handle: PluginTrackHandle, role?: string): Promise<void>;
+    /**
+     * Optional hook run right after a track is born (Add Track / Import Track).
+     * Lets a family stamp per-track scene-data on the newborn — e.g. the arp
+     * panel anchors every new track as a voice-group of ONE so the group
+     * header's intent controls (voice count / rate / split) exist BEFORE the
+     * first generation instead of appearing only after it (which wasted a
+     * throwaway generation on defaults). The core reloads tracks after the hook
+     * so stamped group metas resolve immediately. Failures are non-fatal — the
+     * track lands as a plain row.
+     * @since SDK 2.43.0
+     */
+    onTrackCreated?(handle: PluginTrackHandle, ctx: TrackCreatedContext): Promise<void>;
     /** System prompt for the family's LLM calls (incl. core-owned crossfade/fade generation). */
     buildSystemPrompt(validRoles: readonly string[]): string;
     /** Parse the family's LLM note responses (crossfade/fade flows). */
@@ -5476,7 +5516,7 @@ declare function useAnySolo(host: Pick<PluginHost, 'isAnySoloActive' | 'onTrackS
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.42.0";
+declare const PLUGIN_SDK_VERSION = "2.43.0";
 
 /**
  * FX Preset Definitions
@@ -5635,4 +5675,4 @@ interface PickTopKOptions {
  */
 declare function pickTopKWeighted<T>(scored: ReadonlyArray<ScoredCandidate<T>>, options?: PickTopKOptions): T | null;
 
-export { AUDIO_EFFECTS, AUDIO_EFFECT_LABEL, type AdjacentPairAnalysis, type AudioEffect, type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CoreTrackHandlers, 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, type DesignerRowSlots, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, ENSEMBLE_MAX_VOICES, ENSEMBLE_MIN_VOICES, ENSEMBLE_STYLES, EQUAL_POWER_GAIN, type EnforceVoiceOptions, type EnforceVoiceResult, type EnsembleAnalysis, type EnsembleNote, type EnsembleStyle, type EnsembleStyleRules, type EnsembleVoiceSpec, 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 GenerationServices, type GeneratorPanelAdapter, type GeneratorPanelCore, GeneratorPanelShell, type GeneratorPanelShellProps, type GeneratorPanelSlots, type GeneratorPlugin, type GeneratorTrackState, type GeneratorType, type GroupFadeEntry, type GroupFadeEntryOf, type GroupFadeMemberLayer, GroupFadeTrackRow, type GroupFadeTrackRowProps, type GroupParseSpec, type GroupRenderContext, 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 LLMNoteResponse, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, MIN_NOTE_DURATION_BEATS, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MotionKind, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PanelBusFxEntry, type PanelBusLevels, type PanelBusState, type PanelFeatureFlags, type PanelGenerationStrategy, type PanelGroupExtension, type PanelIdentity, PanelMasterStrip, type PanelMasterStripProps, type PanelShuffleAdapter, type PanelSoundAdapter, type PanelTransitionGroupAdapter, type ParsedEnsemble, 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 PluginGenerationContextOptions, 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 ResolveGroupsOptions, type ResolvedCrossfadePair, type ResolvedFade, type ResolvedGroupFade, type ResolvedGroupsResult, type ResolvedTrackGroup, type SDKTrackRowProps, SLIDER_UNITY, STYLE_RULES, SUBMIT_ENSEMBLE_TOOL_NAME, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type SceneTrackSummary, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SurgeSoundAdapterOverrides, type SynthesizeCuePointsOptions, TEXTURAL_ROLES, TRANSITION_DESIGNER_DRAFT_KEY, TrackDrawer, type TrackDrawerProps, type TrackExternalFxEntry, TrackExternalFxSection, type TrackExternalFxSectionProps, type TrackFxDetailState, type TrackFxState, type TrackGroupMember, type TrackGroupMeta, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, TransitionDesigner, type TransitionDesignerDraft, type TransitionDesignerProps, type TransitionOps, type TransitionRowType, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseGeneratorPanelCoreOptions, type UsePanelBusResult, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackExternalFxResult, type UseTrackReorderOptions, type UseTrackReorderResult, type UseTransitionOpsInputs, type VerbatimFadeMember, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeEnsemble, analyzeWavPeak, asAudioEffect, asCrossfadeMeta, asFadeMeta, asTransitionDesignerDraft, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildEnsembleSystemPrompt, buildFadeVolumeCurve, buildRowSlots, buildSubmitEnsembleParameters, buildViolationRetrySuffix, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, createSurgeSoundAdapter, dbIdsFromKeys, dbToSlider, defaultFadeGesture, defaultVoiceSpecs, describeViolations, drawWaveform, enforceVoice, foldPitchToRegister, formatConcurrentTracks, hashString, moveItem, nearestPitchWithPc, newTrackState, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseEnsembleArgs, parseFades, parseLLMNoteResponse, parseTrackGroups, pickTopKWeighted, pitchToName, pluginFxToToggleFx, pxToCell, reconcileSlots, resizeNoteDuration, resolveTrackGroups, rowKey, rowType, scorePromptMatch, sliderToDb, slotsEqual, soundIdentity, splitFadeEntries, synthesizeCuePoints, tokenizePrompt, trackDataKey, transposeNotes, useAnySolo, useGeneratorPanelCore, usePanelBus, useSceneState, useSoundHistory, useTrackExternalFx, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransitionOps, useTransportPlaying };
+export { AUDIO_EFFECTS, AUDIO_EFFECT_LABEL, type AdjacentPairAnalysis, type AudioEffect, type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CoreTrackHandlers, 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, type DesignerRowSlots, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, ENSEMBLE_MAX_VOICES, ENSEMBLE_MIN_VOICES, ENSEMBLE_STYLES, EQUAL_POWER_GAIN, type EnforceVoiceOptions, type EnforceVoiceResult, type EnsembleAnalysis, type EnsembleNote, type EnsembleStyle, type EnsembleStyleRules, type EnsembleVoiceSpec, 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 GenerationServices, type GeneratorPanelAdapter, type GeneratorPanelCore, GeneratorPanelShell, type GeneratorPanelShellProps, type GeneratorPanelSlots, type GeneratorPlugin, type GeneratorTrackState, type GeneratorType, type GroupFadeEntry, type GroupFadeEntryOf, type GroupFadeMemberLayer, GroupFadeTrackRow, type GroupFadeTrackRowProps, type GroupParseSpec, type GroupRenderContext, 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 LLMNoteResponse, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, MIN_NOTE_DURATION_BEATS, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MotionKind, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PanelBusFxEntry, type PanelBusLevels, type PanelBusState, type PanelFeatureFlags, type PanelGenerationStrategy, type PanelGroupExtension, type PanelIdentity, PanelMasterStrip, type PanelMasterStripProps, type PanelShuffleAdapter, type PanelSoundAdapter, type PanelTransitionGroupAdapter, type ParsedEnsemble, 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 PluginGenerationContextOptions, 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 ResolveGroupsOptions, type ResolvedCrossfadePair, type ResolvedFade, type ResolvedGroupFade, type ResolvedGroupsResult, type ResolvedTrackGroup, type SDKTrackRowProps, SLIDER_UNITY, STYLE_RULES, SUBMIT_ENSEMBLE_TOOL_NAME, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type SceneTrackSummary, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetOptions, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SurgeSoundAdapterOverrides, type SynthesizeCuePointsOptions, TEXTURAL_ROLES, TRANSITION_DESIGNER_DRAFT_KEY, TrackDrawer, type TrackDrawerProps, type TrackExternalFxEntry, TrackExternalFxSection, type TrackExternalFxSectionProps, type TrackFxDetailState, type TrackFxState, type TrackGroupMember, type TrackGroupMeta, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, TransitionDesigner, type TransitionDesignerDraft, type TransitionDesignerProps, type TransitionOps, type TransitionRowType, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseGeneratorPanelCoreOptions, type UsePanelBusResult, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackExternalFxResult, type UseTrackReorderOptions, type UseTrackReorderResult, type UseTransitionOpsInputs, type VerbatimFadeMember, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeEnsemble, analyzeWavPeak, asAudioEffect, asCrossfadeMeta, asFadeMeta, asTransitionDesignerDraft, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildEnsembleSystemPrompt, buildFadeVolumeCurve, buildRowSlots, buildSubmitEnsembleParameters, buildViolationRetrySuffix, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, createSurgeSoundAdapter, dbIdsFromKeys, dbToSlider, defaultFadeGesture, defaultVoiceSpecs, describeViolations, drawWaveform, enforceVoice, foldPitchToRegister, formatConcurrentTracks, hashString, moveItem, nearestPitchWithPc, newTrackState, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseEnsembleArgs, parseFades, parseLLMNoteResponse, parseTrackGroups, pickTopKWeighted, pitchToName, pluginFxToToggleFx, pxToCell, reconcileSlots, resizeNoteDuration, resolveTrackGroups, rowKey, rowType, scorePromptMatch, sliderToDb, slotsEqual, soundIdentity, splitFadeEntries, synthesizeCuePoints, tokenizePrompt, trackDataKey, transposeNotes, useAnySolo, useGeneratorPanelCore, usePanelBus, useSceneState, useSoundHistory, useTrackExternalFx, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransitionOps, useTransportPlaying };

package/dist/index.d.ts

@@ -348,8 +348,17 @@ interface PluginHost {
      * pool; the current preset is always implicitly excluded. Use this to
      * implement a "no-repeat until full cycle" shuffle: the panel accumulates
      * the history and resets when shufflePreset throws "no presets available".
-     */
-    shufflePreset(trackId: string, excludeNames?: readonly string[]): Promise<ShufflePresetResult>;
+     *
+     * `options.description` (since SDK 2.44.0) is the user's sound description
+     * for semantic retrieval — when the host's patch index is available the pick
+     * is vector-proximity against this text instead of random-within-category.
+     * Pass the live prompt from panel state (host-side stored prompts are
+     * debounced and may lag). Member voices of a group should pass the ANCHOR's
+     * prompt, optionally suffixed with the voice label ("horn section — bass
+     * register"). Omitting it falls back to the prompt stored on the track, and
+     * failing that, the legacy random pick.
+     */
+    shufflePreset(trackId: string, excludeNames?: readonly string[], options?: ShufflePresetOptions): 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>;
     /**
@@ -2014,6 +2023,18 @@ interface PluginPresetData {
     /** Base64-encoded plugin state — pass to setPluginState() */
     state: string;
 }
+/**
+ * Options for shufflePreset().
+ * @since SDK 2.44.0
+ */
+interface ShufflePresetOptions {
+    /**
+     * The user's sound description ("muted trumpet", "warm analog pads").
+     * Enables semantic (vector-proximity) preset retrieval on hosts that ship a
+     * patch index; hosts without one ignore it and pick random-within-category.
+     */
+    description?: string;
+}
 /** Result of shufflePreset() — the new preset that was applied */
 interface ShufflePresetResult {
     presetName: string;
@@ -4922,6 +4943,13 @@ interface PanelTransitionGroupAdapter {
     /** Group-fade row header label, e.g. `Bassline (3 voices)`. Default `Group (N tracks)`. */
     groupRowLabel?(memberCount: number): string;
 }
+/** What `onTrackCreated` gets to work with (Add Track is scene-gated, so the scene is non-null). */
+interface TrackCreatedContext {
+    /** Scene the track was created in. */
+    activeSceneId: string;
+    /** The ONE scene-data key builder (always dbId-based). */
+    trackDataKey: (dbId: string, suffix: string) => string;
+}
 interface GeneratorPanelAdapter<M = unknown> {
     identity: PanelIdentity;
     features: PanelFeatureFlags;
@@ -4932,6 +4960,18 @@ interface GeneratorPanelAdapter<M = unknown> {
      * Synth: `host.shufflePreset(handle.id)` non-fatal.
      */
     applyPortedTrackSound(handle: PluginTrackHandle, role?: string): Promise<void>;
+    /**
+     * Optional hook run right after a track is born (Add Track / Import Track).
+     * Lets a family stamp per-track scene-data on the newborn — e.g. the arp
+     * panel anchors every new track as a voice-group of ONE so the group
+     * header's intent controls (voice count / rate / split) exist BEFORE the
+     * first generation instead of appearing only after it (which wasted a
+     * throwaway generation on defaults). The core reloads tracks after the hook
+     * so stamped group metas resolve immediately. Failures are non-fatal — the
+     * track lands as a plain row.
+     * @since SDK 2.43.0
+     */
+    onTrackCreated?(handle: PluginTrackHandle, ctx: TrackCreatedContext): Promise<void>;
     /** System prompt for the family's LLM calls (incl. core-owned crossfade/fade generation). */
     buildSystemPrompt(validRoles: readonly string[]): string;
     /** Parse the family's LLM note responses (crossfade/fade flows). */
@@ -5476,7 +5516,7 @@ declare function useAnySolo(host: Pick<PluginHost, 'isAnySoloActive' | 'onTrackS
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.42.0";
+declare const PLUGIN_SDK_VERSION = "2.43.0";
 
 /**
  * FX Preset Definitions
@@ -5635,4 +5675,4 @@ interface PickTopKOptions {
  */
 declare function pickTopKWeighted<T>(scored: ReadonlyArray<ScoredCandidate<T>>, options?: PickTopKOptions): T | null;
 
-export { AUDIO_EFFECTS, AUDIO_EFFECT_LABEL, type AdjacentPairAnalysis, type AudioEffect, type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CoreTrackHandlers, 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, type DesignerRowSlots, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, ENSEMBLE_MAX_VOICES, ENSEMBLE_MIN_VOICES, ENSEMBLE_STYLES, EQUAL_POWER_GAIN, type EnforceVoiceOptions, type EnforceVoiceResult, type EnsembleAnalysis, type EnsembleNote, type EnsembleStyle, type EnsembleStyleRules, type EnsembleVoiceSpec, 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 GenerationServices, type GeneratorPanelAdapter, type GeneratorPanelCore, GeneratorPanelShell, type GeneratorPanelShellProps, type GeneratorPanelSlots, type GeneratorPlugin, type GeneratorTrackState, type GeneratorType, type GroupFadeEntry, type GroupFadeEntryOf, type GroupFadeMemberLayer, GroupFadeTrackRow, type GroupFadeTrackRowProps, type GroupParseSpec, type GroupRenderContext, 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 LLMNoteResponse, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, MIN_NOTE_DURATION_BEATS, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MotionKind, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PanelBusFxEntry, type PanelBusLevels, type PanelBusState, type PanelFeatureFlags, type PanelGenerationStrategy, type PanelGroupExtension, type PanelIdentity, PanelMasterStrip, type PanelMasterStripProps, type PanelShuffleAdapter, type PanelSoundAdapter, type PanelTransitionGroupAdapter, type ParsedEnsemble, 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 PluginGenerationContextOptions, 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 ResolveGroupsOptions, type ResolvedCrossfadePair, type ResolvedFade, type ResolvedGroupFade, type ResolvedGroupsResult, type ResolvedTrackGroup, type SDKTrackRowProps, SLIDER_UNITY, STYLE_RULES, SUBMIT_ENSEMBLE_TOOL_NAME, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type SceneTrackSummary, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SurgeSoundAdapterOverrides, type SynthesizeCuePointsOptions, TEXTURAL_ROLES, TRANSITION_DESIGNER_DRAFT_KEY, TrackDrawer, type TrackDrawerProps, type TrackExternalFxEntry, TrackExternalFxSection, type TrackExternalFxSectionProps, type TrackFxDetailState, type TrackFxState, type TrackGroupMember, type TrackGroupMeta, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, TransitionDesigner, type TransitionDesignerDraft, type TransitionDesignerProps, type TransitionOps, type TransitionRowType, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseGeneratorPanelCoreOptions, type UsePanelBusResult, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackExternalFxResult, type UseTrackReorderOptions, type UseTrackReorderResult, type UseTransitionOpsInputs, type VerbatimFadeMember, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeEnsemble, analyzeWavPeak, asAudioEffect, asCrossfadeMeta, asFadeMeta, asTransitionDesignerDraft, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildEnsembleSystemPrompt, buildFadeVolumeCurve, buildRowSlots, buildSubmitEnsembleParameters, buildViolationRetrySuffix, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, createSurgeSoundAdapter, dbIdsFromKeys, dbToSlider, defaultFadeGesture, defaultVoiceSpecs, describeViolations, drawWaveform, enforceVoice, foldPitchToRegister, formatConcurrentTracks, hashString, moveItem, nearestPitchWithPc, newTrackState, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseEnsembleArgs, parseFades, parseLLMNoteResponse, parseTrackGroups, pickTopKWeighted, pitchToName, pluginFxToToggleFx, pxToCell, reconcileSlots, resizeNoteDuration, resolveTrackGroups, rowKey, rowType, scorePromptMatch, sliderToDb, slotsEqual, soundIdentity, splitFadeEntries, synthesizeCuePoints, tokenizePrompt, trackDataKey, transposeNotes, useAnySolo, useGeneratorPanelCore, usePanelBus, useSceneState, useSoundHistory, useTrackExternalFx, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransitionOps, useTransportPlaying };
+export { AUDIO_EFFECTS, AUDIO_EFFECT_LABEL, type AdjacentPairAnalysis, type AudioEffect, type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CoreTrackHandlers, 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, type DesignerRowSlots, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, ENSEMBLE_MAX_VOICES, ENSEMBLE_MIN_VOICES, ENSEMBLE_STYLES, EQUAL_POWER_GAIN, type EnforceVoiceOptions, type EnforceVoiceResult, type EnsembleAnalysis, type EnsembleNote, type EnsembleStyle, type EnsembleStyleRules, type EnsembleVoiceSpec, 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 GenerationServices, type GeneratorPanelAdapter, type GeneratorPanelCore, GeneratorPanelShell, type GeneratorPanelShellProps, type GeneratorPanelSlots, type GeneratorPlugin, type GeneratorTrackState, type GeneratorType, type GroupFadeEntry, type GroupFadeEntryOf, type GroupFadeMemberLayer, GroupFadeTrackRow, type GroupFadeTrackRowProps, type GroupParseSpec, type GroupRenderContext, 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 LLMNoteResponse, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, MIN_NOTE_DURATION_BEATS, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MotionKind, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PanelBusFxEntry, type PanelBusLevels, type PanelBusState, type PanelFeatureFlags, type PanelGenerationStrategy, type PanelGroupExtension, type PanelIdentity, PanelMasterStrip, type PanelMasterStripProps, type PanelShuffleAdapter, type PanelSoundAdapter, type PanelTransitionGroupAdapter, type ParsedEnsemble, 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 PluginGenerationContextOptions, 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 ResolveGroupsOptions, type ResolvedCrossfadePair, type ResolvedFade, type ResolvedGroupFade, type ResolvedGroupsResult, type ResolvedTrackGroup, type SDKTrackRowProps, SLIDER_UNITY, STYLE_RULES, SUBMIT_ENSEMBLE_TOOL_NAME, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type SceneTrackSummary, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetOptions, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SurgeSoundAdapterOverrides, type SynthesizeCuePointsOptions, TEXTURAL_ROLES, TRANSITION_DESIGNER_DRAFT_KEY, TrackDrawer, type TrackDrawerProps, type TrackExternalFxEntry, TrackExternalFxSection, type TrackExternalFxSectionProps, type TrackFxDetailState, type TrackFxState, type TrackGroupMember, type TrackGroupMeta, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, TransitionDesigner, type TransitionDesignerDraft, type TransitionDesignerProps, type TransitionOps, type TransitionRowType, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseGeneratorPanelCoreOptions, type UsePanelBusResult, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackExternalFxResult, type UseTrackReorderOptions, type UseTrackReorderResult, type UseTransitionOpsInputs, type VerbatimFadeMember, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeEnsemble, analyzeWavPeak, asAudioEffect, asCrossfadeMeta, asFadeMeta, asTransitionDesignerDraft, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildEnsembleSystemPrompt, buildFadeVolumeCurve, buildRowSlots, buildSubmitEnsembleParameters, buildViolationRetrySuffix, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, createSurgeSoundAdapter, dbIdsFromKeys, dbToSlider, defaultFadeGesture, defaultVoiceSpecs, describeViolations, drawWaveform, enforceVoice, foldPitchToRegister, formatConcurrentTracks, hashString, moveItem, nearestPitchWithPc, newTrackState, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseEnsembleArgs, parseFades, parseLLMNoteResponse, parseTrackGroups, pickTopKWeighted, pitchToName, pluginFxToToggleFx, pxToCell, reconcileSlots, resizeNoteDuration, resolveTrackGroups, rowKey, rowType, scorePromptMatch, sliderToDb, slotsEqual, soundIdentity, splitFadeEntries, synthesizeCuePoints, tokenizePrompt, trackDataKey, transposeNotes, useAnySolo, useGeneratorPanelCore, usePanelBus, useSceneState, useSoundHistory, useTrackExternalFx, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransitionOps, useTransportPlaying };

package/dist/index.js

@@ -7178,6 +7178,14 @@ function useGeneratorPanelCore({
         ...adapter.createTrackOptions()
       });
       setTracks((prev) => [...prev, newTrackState(handle)]);
+      if (adapter.onTrackCreated) {
+        try {
+          await adapter.onTrackCreated(handle, { activeSceneId, trackDataKey });
+        } catch (err) {
+          console.warn(`[${logTag}] onTrackCreated failed (non-fatal):`, err);
+        }
+        await loadTracks(true);
+      }
       onExpandSelf?.();
       setTimeout(() => {
         const inputs = document.querySelectorAll(
@@ -7194,7 +7202,7 @@ function useGeneratorPanelCore({
       isAddingTrackRef.current = false;
       setIsAddingTrack(false);
     }
-  }, [host, adapter, identity, activeSceneId, isConnected, isAuthenticated, tracks.length, onExpandSelf]);
+  }, [host, adapter, identity, activeSceneId, isConnected, isAuthenticated, tracks.length, onExpandSelf, loadTracks, logTag]);
   const handlePortTrack = (0, import_react30.useCallback)(
     async (sel) => {
       if (!activeSceneId) {
@@ -7234,6 +7242,12 @@ function useGeneratorPanelCore({
           });
         }
         await adapter.applyPortedTrackSound(handle, sel.role);
+        if (adapter.onTrackCreated) {
+          try {
+            await adapter.onTrackCreated(handle, { activeSceneId, trackDataKey });
+          } catch {
+          }
+        }
         host.showToast(
           "success",
           `Imported to ${identity.familyKey}`,
@@ -9034,7 +9048,7 @@ Your previous ensemble had these problems \u2014 fix them while keeping everythi
 }
 
 // src/constants/sdk-version.ts
-var PLUGIN_SDK_VERSION = "2.42.0";
+var PLUGIN_SDK_VERSION = "2.43.0";
 
 // src/utils/format-concurrent-tracks.ts
 function formatConcurrentTracks(ctx) {