@signalsandsorcery/plugin-sdk 2.35.7 → 2.36.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import React$1, { ReactNode, ComponentType, DragEvent, Dispatch, SetStateAction } from 'react';
+import React$1, { ReactNode, ComponentType, DragEvent, Dispatch, SetStateAction, KeyboardEvent } from 'react';
 
 /**
  * Plugin SDK Type Definitions
@@ -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;
@@ -3758,13 +3779,21 @@ declare function Modal({ open, onClose, children, testIdPrefix, closeOnBackdrop,
  *
  * Coordinate spaces:
  *   pitch (0-127)  ── row = hi - pitch ──  top px  = row * ROW_HEIGHT
- *   beat (¼ notes) ─────────────────────── left px = beat * PX_PER_BEAT
+ *   beat (¼ notes) ─────────────────────── left px = beat * pxPerBeat
+ * where pxPerBeat is the EFFECTIVE horizontal scale: at least PX_PER_BEAT
+ * (long clips overflow into a horizontal scroll), stretched up so short clips
+ * fill the viewport width (see effectivePxPerBeat).
  *
  * The pure helpers (`cellToPx` / `pxToCell` / `transposeNotes`) and layout
  * constants are exported so coordinate math can be unit-tested without a DOM.
  */
 
-/** Horizontal pixels per quarter-note beat. */
+/**
+ * MINIMUM horizontal pixels per quarter-note beat. The grid never renders
+ * tighter than this (long clips overflow into a horizontal scroll), but it
+ * stretches beyond it to fill the container when the clip is short — see
+ * {@link effectivePxPerBeat}.
+ */
 declare const PX_PER_BEAT = 24;
 /** Vertical pixels per semitone row. */
 declare const ROW_HEIGHT = 12;
@@ -3774,13 +3803,22 @@ declare const GUTTER_W = 28;
 declare const DRAG_DEAD_ZONE = 4;
 /** Width (px) of the right-edge grab handle that resizes a note's length. */
 declare const RESIZE_HANDLE_PX = 6;
+/**
+ * Pixels per beat for a grid of `totalBeats` inside a `containerWidth`-px
+ * scroll viewport (which also holds the {@link GUTTER_W} keyboard gutter).
+ * Fills the available width when the clip is short; never drops below
+ * {@link PX_PER_BEAT}, so long clips overflow into a horizontal scroll.
+ * An unknown/unmeasured container (≤ gutter width) yields the minimum.
+ */
+declare function effectivePxPerBeat(containerWidth: number, totalBeats: number): number;
 /** MIDI pitch → scientific note name (60 = C4). */
 declare function pitchToName(pitch: number): string;
 /**
  * Cell (pitch, startBeat) → top-left pixel offset within the grid.
- * `hi` is the highest (top) visible pitch.
+ * `hi` is the highest (top) visible pitch. `pxPerBeat` is the effective
+ * (possibly stretched) horizontal scale; defaults to the minimum.
  */
-declare function cellToPx(pitch: number, startBeat: number, hi: number): {
+declare function cellToPx(pitch: number, startBeat: number, hi: number, pxPerBeat?: number): {
     left: number;
     top: number;
 };
@@ -3789,7 +3827,7 @@ declare function cellToPx(pitch: number, startBeat: number, hi: number): {
  * snaps to the nearest `snap` step and clamps to `[0, totalBeats - snap]`;
  * pitch clamps to `[0, 127]`.
  */
-declare function pxToCell(localX: number, localY: number, hi: number, snap: number, bars: number, beatsPerBar: number): {
+declare function pxToCell(localX: number, localY: number, hi: number, snap: number, bars: number, beatsPerBar: number, pxPerBeat?: number): {
     pitch: number;
     startBeat: number;
 };
@@ -3799,7 +3837,7 @@ declare function pxToCell(localX: number, localY: number, hi: number, snap: numb
  * step past `startBeat`, and never extends beyond the grid's right edge
  * (`bars * beatsPerBar`). `startBeat` and `pitch` are untouched.
  */
-declare function resizeNoteDuration(startBeat: number, localX: number, snap: number, bars: number, beatsPerBar: number): number;
+declare function resizeNoteDuration(startBeat: number, localX: number, snap: number, bars: number, beatsPerBar: number, pxPerBeat?: number): number;
 /**
  * `scrollTop` that vertically centers the bulk of the notes in a `viewportH`-px
  * window. Targets the MEDIAN pitch (robust to a stray high/low outlier — keeps
@@ -3815,7 +3853,7 @@ interface PianoRollEditorProps {
     notes: readonly PluginMidiNote[];
     /** Emitted on every edit (add / delete / move / transpose) with the full next array. */
     onChange: (next: PluginMidiNote[]) => void;
-    /** Scene length in bars → grid width = bars * beatsPerBar * PX_PER_BEAT. */
+    /** Scene length in bars → grid width = bars * beatsPerBar * pxPerBeat (min PX_PER_BEAT, stretched to fill). */
     bars: number;
     /** BPM — used only for audition timing in v1. */
     bpm: number;
@@ -4619,6 +4657,16 @@ declare function resolveTrackGroups<M, T>(parsedGroups: TrackGroupMeta<M>[], tra
  * @since SDK 2.35.0
  */
 
+/**
+ * Default prompt-field keyboard behavior: Enter (without Shift) fires the
+ * Generate action, exactly like clicking the Generate button. The SDK
+ * TrackRow's own prompt input uses this; group headers that render their OWN
+ * prompt input (bass / ensemble / arp / pad stacks) must attach it too so
+ * Enter is never a dead key while the button sits right next to the field.
+ *
+ * @since SDK 2.36.0
+ */
+declare function promptEnterToGenerate(generate: () => void, disabled?: boolean): (e: KeyboardEvent<HTMLInputElement>) => void;
 /**
  * Build a scene plugin_data key for a track-scoped value. Scene-data keys are
  * ALWAYS constructed from the stable DB UUID (`handle.dbId`) — never the
@@ -5654,4 +5702,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, effectivePxPerBeat, enforceVoice, foldPitchToRegister, formatConcurrentTracks, hashString, moveItem, nearestPitchWithPc, newTrackState, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseEnsembleArgs, parseFades, parseLLMNoteResponse, parseTrackGroups, pickTopKWeighted, pitchToName, pluginFxToToggleFx, promptEnterToGenerate, 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

@@ -1,4 +1,4 @@
-import React$1, { ReactNode, ComponentType, DragEvent, Dispatch, SetStateAction } from 'react';
+import React$1, { ReactNode, ComponentType, DragEvent, Dispatch, SetStateAction, KeyboardEvent } from 'react';
 
 /**
  * Plugin SDK Type Definitions
@@ -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;
@@ -3758,13 +3779,21 @@ declare function Modal({ open, onClose, children, testIdPrefix, closeOnBackdrop,
  *
  * Coordinate spaces:
  *   pitch (0-127)  ── row = hi - pitch ──  top px  = row * ROW_HEIGHT
- *   beat (¼ notes) ─────────────────────── left px = beat * PX_PER_BEAT
+ *   beat (¼ notes) ─────────────────────── left px = beat * pxPerBeat
+ * where pxPerBeat is the EFFECTIVE horizontal scale: at least PX_PER_BEAT
+ * (long clips overflow into a horizontal scroll), stretched up so short clips
+ * fill the viewport width (see effectivePxPerBeat).
  *
  * The pure helpers (`cellToPx` / `pxToCell` / `transposeNotes`) and layout
  * constants are exported so coordinate math can be unit-tested without a DOM.
  */
 
-/** Horizontal pixels per quarter-note beat. */
+/**
+ * MINIMUM horizontal pixels per quarter-note beat. The grid never renders
+ * tighter than this (long clips overflow into a horizontal scroll), but it
+ * stretches beyond it to fill the container when the clip is short — see
+ * {@link effectivePxPerBeat}.
+ */
 declare const PX_PER_BEAT = 24;
 /** Vertical pixels per semitone row. */
 declare const ROW_HEIGHT = 12;
@@ -3774,13 +3803,22 @@ declare const GUTTER_W = 28;
 declare const DRAG_DEAD_ZONE = 4;
 /** Width (px) of the right-edge grab handle that resizes a note's length. */
 declare const RESIZE_HANDLE_PX = 6;
+/**
+ * Pixels per beat for a grid of `totalBeats` inside a `containerWidth`-px
+ * scroll viewport (which also holds the {@link GUTTER_W} keyboard gutter).
+ * Fills the available width when the clip is short; never drops below
+ * {@link PX_PER_BEAT}, so long clips overflow into a horizontal scroll.
+ * An unknown/unmeasured container (≤ gutter width) yields the minimum.
+ */
+declare function effectivePxPerBeat(containerWidth: number, totalBeats: number): number;
 /** MIDI pitch → scientific note name (60 = C4). */
 declare function pitchToName(pitch: number): string;
 /**
  * Cell (pitch, startBeat) → top-left pixel offset within the grid.
- * `hi` is the highest (top) visible pitch.
+ * `hi` is the highest (top) visible pitch. `pxPerBeat` is the effective
+ * (possibly stretched) horizontal scale; defaults to the minimum.
  */
-declare function cellToPx(pitch: number, startBeat: number, hi: number): {
+declare function cellToPx(pitch: number, startBeat: number, hi: number, pxPerBeat?: number): {
     left: number;
     top: number;
 };
@@ -3789,7 +3827,7 @@ declare function cellToPx(pitch: number, startBeat: number, hi: number): {
  * snaps to the nearest `snap` step and clamps to `[0, totalBeats - snap]`;
  * pitch clamps to `[0, 127]`.
  */
-declare function pxToCell(localX: number, localY: number, hi: number, snap: number, bars: number, beatsPerBar: number): {
+declare function pxToCell(localX: number, localY: number, hi: number, snap: number, bars: number, beatsPerBar: number, pxPerBeat?: number): {
     pitch: number;
     startBeat: number;
 };
@@ -3799,7 +3837,7 @@ declare function pxToCell(localX: number, localY: number, hi: number, snap: numb
  * step past `startBeat`, and never extends beyond the grid's right edge
  * (`bars * beatsPerBar`). `startBeat` and `pitch` are untouched.
  */
-declare function resizeNoteDuration(startBeat: number, localX: number, snap: number, bars: number, beatsPerBar: number): number;
+declare function resizeNoteDuration(startBeat: number, localX: number, snap: number, bars: number, beatsPerBar: number, pxPerBeat?: number): number;
 /**
  * `scrollTop` that vertically centers the bulk of the notes in a `viewportH`-px
  * window. Targets the MEDIAN pitch (robust to a stray high/low outlier — keeps
@@ -3815,7 +3853,7 @@ interface PianoRollEditorProps {
     notes: readonly PluginMidiNote[];
     /** Emitted on every edit (add / delete / move / transpose) with the full next array. */
     onChange: (next: PluginMidiNote[]) => void;
-    /** Scene length in bars → grid width = bars * beatsPerBar * PX_PER_BEAT. */
+    /** Scene length in bars → grid width = bars * beatsPerBar * pxPerBeat (min PX_PER_BEAT, stretched to fill). */
     bars: number;
     /** BPM — used only for audition timing in v1. */
     bpm: number;
@@ -4619,6 +4657,16 @@ declare function resolveTrackGroups<M, T>(parsedGroups: TrackGroupMeta<M>[], tra
  * @since SDK 2.35.0
  */
 
+/**
+ * Default prompt-field keyboard behavior: Enter (without Shift) fires the
+ * Generate action, exactly like clicking the Generate button. The SDK
+ * TrackRow's own prompt input uses this; group headers that render their OWN
+ * prompt input (bass / ensemble / arp / pad stacks) must attach it too so
+ * Enter is never a dead key while the button sits right next to the field.
+ *
+ * @since SDK 2.36.0
+ */
+declare function promptEnterToGenerate(generate: () => void, disabled?: boolean): (e: KeyboardEvent<HTMLInputElement>) => void;
 /**
  * Build a scene plugin_data key for a track-scoped value. Scene-data keys are
  * ALWAYS constructed from the stable DB UUID (`handle.dbId`) — never the
@@ -5654,4 +5702,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, effectivePxPerBeat, enforceVoice, foldPitchToRegister, formatConcurrentTracks, hashString, moveItem, nearestPitchWithPc, newTrackState, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseEnsembleArgs, parseFades, parseLLMNoteResponse, parseTrackGroups, pickTopKWeighted, pitchToName, pluginFxToToggleFx, promptEnterToGenerate, 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

@@ -111,6 +111,7 @@ __export(index_exports, {
   defaultVoiceSpecs: () => defaultVoiceSpecs,
   describeViolations: () => describeViolations,
   drawWaveform: () => drawWaveform,
+  effectivePxPerBeat: () => effectivePxPerBeat,
   enforceVoice: () => enforceVoice,
   foldPitchToRegister: () => foldPitchToRegister,
   formatConcurrentTracks: () => formatConcurrentTracks,
@@ -129,6 +130,7 @@ __export(index_exports, {
   pickTopKWeighted: () => pickTopKWeighted,
   pitchToName: () => pitchToName,
   pluginFxToToggleFx: () => pluginFxToToggleFx,
+  promptEnterToGenerate: () => promptEnterToGenerate,
   pxToCell: () => pxToCell,
   reconcileSlots: () => reconcileSlots,
   resizeNoteDuration: () => resizeNoteDuration,
@@ -604,25 +606,31 @@ function clamp(v, lo, hi) {
 function snapLabel(s) {
   return SNAP_LABELS[String(s)] ?? `${s}`;
 }
+function effectivePxPerBeat(containerWidth, totalBeats) {
+  if (totalBeats <= 0) return PX_PER_BEAT;
+  const available = containerWidth - GUTTER_W;
+  if (available <= 0) return PX_PER_BEAT;
+  return Math.max(PX_PER_BEAT, available / totalBeats);
+}
 function pitchToName(pitch) {
   const name = NOTE_NAMES[(pitch % 12 + 12) % 12];
   const octave = Math.floor(pitch / 12) - 1;
   return `${name}${octave}`;
 }
-function cellToPx(pitch, startBeat, hi) {
-  return { left: startBeat * PX_PER_BEAT, top: (hi - pitch) * ROW_HEIGHT };
+function cellToPx(pitch, startBeat, hi, pxPerBeat = PX_PER_BEAT) {
+  return { left: startBeat * pxPerBeat, top: (hi - pitch) * ROW_HEIGHT };
 }
-function pxToCell(localX, localY, hi, snap, bars, beatsPerBar) {
+function pxToCell(localX, localY, hi, snap, bars, beatsPerBar, pxPerBeat = PX_PER_BEAT) {
   const totalBeats = bars * beatsPerBar;
   const pitch = clamp(hi - Math.floor(localY / ROW_HEIGHT), 0, 127);
-  const rawBeat = localX / PX_PER_BEAT;
+  const rawBeat = localX / pxPerBeat;
   const snapped = Math.round(rawBeat / snap) * snap;
   const startBeat = clamp(snapped, 0, Math.max(0, totalBeats - snap));
   return { pitch, startBeat };
 }
-function resizeNoteDuration(startBeat, localX, snap, bars, beatsPerBar) {
+function resizeNoteDuration(startBeat, localX, snap, bars, beatsPerBar, pxPerBeat = PX_PER_BEAT) {
   const totalBeats = bars * beatsPerBar;
-  const snappedEnd = Math.round(localX / PX_PER_BEAT / snap) * snap;
+  const snappedEnd = Math.round(localX / pxPerBeat / snap) * snap;
   const end = clamp(snappedEnd, startBeat + snap, totalBeats);
   return end - startBeat;
 }
@@ -673,7 +681,19 @@ function PianoRollEditor({
   }, [autoFit, notes, minPitch, maxPitch]);
   const rowCount = hi - lo + 1;
   const totalBeats = bars * beatsPerBar;
-  const gridWidth = totalBeats * PX_PER_BEAT;
+  const [containerW, setContainerW] = (0, import_react.useState)(0);
+  (0, import_react.useLayoutEffect)(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const measure = () => setContainerW(el.clientWidth);
+    measure();
+    if (typeof ResizeObserver === "undefined") return void 0;
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  const pxPerBeat = effectivePxPerBeat(containerW, totalBeats);
+  const gridWidth = totalBeats * pxPerBeat;
   const gridHeight = rowCount * ROW_HEIGHT;
   const stateRef = (0, import_react.useRef)({
     notes,
@@ -685,7 +705,8 @@ function PianoRollEditor({
     defaultVelocity,
     bpm,
     onAuditionNote,
-    disabled
+    disabled,
+    pxPerBeat
   });
   stateRef.current = {
     notes,
@@ -697,7 +718,8 @@ function PianoRollEditor({
     defaultVelocity,
     bpm,
     onAuditionNote,
-    disabled
+    disabled,
+    pxPerBeat
   };
   const localCoords = (0, import_react.useCallback)((clientX, clientY) => {
     const rect = gridRef.current?.getBoundingClientRect();
@@ -733,14 +755,14 @@ function PianoRollEditor({
     if (drag.mode === "resize") {
       const note = s.notes[drag.index];
       if (!note) return;
-      const durationBeats = resizeNoteDuration(note.startBeat, x, s.snapState, s.bars, s.beatsPerBar);
+      const durationBeats = resizeNoteDuration(note.startBeat, x, s.snapState, s.bars, s.beatsPerBar, s.pxPerBeat);
       if (durationBeats === note.durationBeats) return;
       const next2 = s.notes.map((n, i) => i === drag.index ? { ...n, durationBeats } : n);
       s.onChange(next2);
       return;
     }
     if (drag.mode !== "drag") return;
-    const { pitch, startBeat } = pxToCell(x, y, s.hi, s.snapState, s.bars, s.beatsPerBar);
+    const { pitch, startBeat } = pxToCell(x, y, s.hi, s.snapState, s.bars, s.beatsPerBar, s.pxPerBeat);
     const next = s.notes.map((n, i) => i === drag.index ? { ...n, pitch, startBeat } : n);
     s.onChange(next);
   }, [localCoords]);
@@ -756,7 +778,7 @@ function PianoRollEditor({
     }
     if (drag.mode === "pending-add") {
       const { x, y } = localCoords(e.clientX, e.clientY);
-      const { pitch, startBeat } = pxToCell(x, y, s.hi, s.snapState, s.bars, s.beatsPerBar);
+      const { pitch, startBeat } = pxToCell(x, y, s.hi, s.snapState, s.bars, s.beatsPerBar, s.pxPerBeat);
       const note = {
         pitch,
         startBeat,
@@ -805,14 +827,14 @@ function PianoRollEditor({
     return out;
   }, [hi, lo]);
   const gridBg = (0, import_react.useMemo)(() => {
-    const beatPx = PX_PER_BEAT;
-    const barPx = PX_PER_BEAT * beatsPerBar;
+    const beatPx = pxPerBeat;
+    const barPx = pxPerBeat * beatsPerBar;
     return [
       `repeating-linear-gradient(to right, transparent 0 ${beatPx - 1}px, rgba(255,255,255,0.06) ${beatPx - 1}px ${beatPx}px)`,
       `repeating-linear-gradient(to right, transparent 0 ${barPx - 1}px, rgba(255,255,255,0.16) ${barPx - 1}px ${barPx}px)`,
       `repeating-linear-gradient(to bottom, transparent 0 ${ROW_HEIGHT - 1}px, rgba(255,255,255,0.04) ${ROW_HEIGHT - 1}px ${ROW_HEIGHT}px)`
     ].join(", ");
-  }, [beatsPerBar]);
+  }, [beatsPerBar, pxPerBeat]);
   const octaveDisabled = disabled || notes.length === 0;
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: `flex flex-col gap-1 ${className ?? ""}`, "data-testid": testId, children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "flex items-center gap-1", "data-testid": "sdk-pr-toolbar", children: [
@@ -906,8 +928,8 @@ function PianoRollEditor({
               onPointerCancel: handlePointerCancel,
               children: [
                 notes.map((n, i) => {
-                  const { left, top } = cellToPx(n.pitch, n.startBeat, hi);
-                  const width = Math.max(3, n.durationBeats * PX_PER_BEAT);
+                  const { left, top } = cellToPx(n.pitch, n.startBeat, hi, pxPerBeat);
+                  const width = Math.max(3, n.durationBeats * pxPerBeat);
                   const handleW = Math.min(RESIZE_HANDLE_PX, width / 2);
                   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
                     "div",
@@ -2385,6 +2407,71 @@ function SorceryProgressBar({
   );
 }
 
+// src/panel-core/panel-helpers.ts
+function promptEnterToGenerate(generate, disabled = false) {
+  return (e) => {
+    if (e.key === "Enter" && !e.shiftKey && !disabled) {
+      e.preventDefault();
+      generate();
+    }
+  };
+}
+function trackDataKey(dbId, suffix) {
+  return `track:${dbId}:${suffix}`;
+}
+function pluginFxToToggleFx(sdkState) {
+  const result = { ...EMPTY_FX_DETAIL_STATE };
+  for (const category of ["eq", "compressor", "chorus", "phaser", "delay", "reverb"]) {
+    const sdkCat = sdkState[category];
+    if (sdkCat) {
+      result[category] = {
+        enabled: sdkCat.enabled,
+        presetIndex: sdkCat.presetIndex,
+        dryWet: sdkCat.dryWet
+      };
+    }
+  }
+  return result;
+}
+function parseLLMNoteResponse(content) {
+  try {
+    let jsonStr = content.trim();
+    const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+    if (fenceMatch) {
+      jsonStr = fenceMatch[1].trim();
+    }
+    const parsed = JSON.parse(jsonStr);
+    if (typeof parsed !== "object" || parsed === null || !("notes" in parsed)) {
+      return null;
+    }
+    const obj = parsed;
+    if (!Array.isArray(obj.notes)) {
+      return null;
+    }
+    const validNotes = [];
+    for (const raw of obj.notes) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const note = raw;
+      const pitch = typeof note.pitch === "number" ? note.pitch : NaN;
+      const startBeat = typeof note.startBeat === "number" ? note.startBeat : NaN;
+      const durationBeats = typeof note.durationBeats === "number" ? note.durationBeats : NaN;
+      const velocity = typeof note.velocity === "number" ? note.velocity : NaN;
+      if (!isNaN(pitch) && pitch >= 0 && pitch <= 127 && !isNaN(startBeat) && startBeat >= 0 && !isNaN(durationBeats) && durationBeats > 0 && !isNaN(velocity) && velocity >= 1 && velocity <= 127) {
+        validNotes.push({
+          pitch: Math.round(pitch),
+          startBeat,
+          durationBeats,
+          velocity: Math.round(velocity)
+        });
+      }
+    }
+    const role = typeof obj.role === "string" ? obj.role : void 0;
+    return { notes: validNotes, role };
+  } catch {
+    return null;
+  }
+}
+
 // src/components/TrackRow.tsx
 var import_jsx_runtime12 = require("react/jsx-runtime");
 function TrackRow({
@@ -2453,12 +2540,7 @@ function TrackRow({
   );
   const fxTabOpen = drawerOpen && drawerTab === "fx";
   const soundTabOpen = drawerOpen && drawerTab !== "fx";
-  const handleKeyDown = (e) => {
-    if (e.key === "Enter" && !e.shiftKey && onGenerate) {
-      e.preventDefault();
-      onGenerate();
-    }
-  };
+  const handleKeyDown = promptEnterToGenerate(() => onGenerate?.(), !onGenerate);
   const borderColorStyle = needsGeneration ? void 0 : accentColor;
   const borderClass = needsGeneration ? "border-amber-400 animate-pulse" : "border-sas-border";
   return /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("div", { "data-testid": "sdk-track-row-wrapper", className: "w-full", ...drag?.rowProps ?? {}, children: [
@@ -6046,63 +6128,6 @@ function newTrackState(handle, overrides = {}) {
   };
 }
 
-// src/panel-core/panel-helpers.ts
-function trackDataKey(dbId, suffix) {
-  return `track:${dbId}:${suffix}`;
-}
-function pluginFxToToggleFx(sdkState) {
-  const result = { ...EMPTY_FX_DETAIL_STATE };
-  for (const category of ["eq", "compressor", "chorus", "phaser", "delay", "reverb"]) {
-    const sdkCat = sdkState[category];
-    if (sdkCat) {
-      result[category] = {
-        enabled: sdkCat.enabled,
-        presetIndex: sdkCat.presetIndex,
-        dryWet: sdkCat.dryWet
-      };
-    }
-  }
-  return result;
-}
-function parseLLMNoteResponse(content) {
-  try {
-    let jsonStr = content.trim();
-    const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
-    if (fenceMatch) {
-      jsonStr = fenceMatch[1].trim();
-    }
-    const parsed = JSON.parse(jsonStr);
-    if (typeof parsed !== "object" || parsed === null || !("notes" in parsed)) {
-      return null;
-    }
-    const obj = parsed;
-    if (!Array.isArray(obj.notes)) {
-      return null;
-    }
-    const validNotes = [];
-    for (const raw of obj.notes) {
-      if (typeof raw !== "object" || raw === null) continue;
-      const note = raw;
-      const pitch = typeof note.pitch === "number" ? note.pitch : NaN;
-      const startBeat = typeof note.startBeat === "number" ? note.startBeat : NaN;
-      const durationBeats = typeof note.durationBeats === "number" ? note.durationBeats : NaN;
-      const velocity = typeof note.velocity === "number" ? note.velocity : NaN;
-      if (!isNaN(pitch) && pitch >= 0 && pitch <= 127 && !isNaN(startBeat) && startBeat >= 0 && !isNaN(durationBeats) && durationBeats > 0 && !isNaN(velocity) && velocity >= 1 && velocity <= 127) {
-        validNotes.push({
-          pitch: Math.round(pitch),
-          startBeat,
-          durationBeats,
-          velocity: Math.round(velocity)
-        });
-      }
-    }
-    const role = typeof obj.role === "string" ? obj.role : void 0;
-    return { notes: validNotes, role };
-  } catch {
-    return null;
-  }
-}
-
 // src/panel-core/group-meta.ts
 function parseTrackGroups(sceneData, spec) {
   const pattern = new RegExp(`^track:(.+):${spec.metaKey}$`);
@@ -9286,6 +9311,7 @@ function pickTopKWeighted(scored, options = {}) {
   defaultVoiceSpecs,
   describeViolations,
   drawWaveform,
+  effectivePxPerBeat,
   enforceVoice,
   foldPitchToRegister,
   formatConcurrentTracks,
@@ -9304,6 +9330,7 @@ function pickTopKWeighted(scored, options = {}) {
   pickTopKWeighted,
   pitchToName,
   pluginFxToToggleFx,
+  promptEnterToGenerate,
   pxToCell,
   reconcileSlots,
   resizeNoteDuration,