@signalsandsorcery/plugin-sdk 2.34.1 → 2.35.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React, { ComponentType, ReactNode, DragEvent, Dispatch, SetStateAction } from 'react';
+import React$1, { ReactNode, ComponentType, DragEvent, Dispatch, SetStateAction } from 'react';
 
 /**
  * Plugin SDK Type Definitions
@@ -2324,7 +2324,7 @@ interface TrackDrawerProps {
     /** Optional single-note preview when the user adds a note. */
     onAuditionNote?: (pitch: number, velocity: number, durationMs: number) => void;
 }
-declare function TrackDrawer({ activeTab, onTabChange, trackId, fxState, onFxToggle, onFxPresetChange, onFxDryWetChange, fxDisabled, instruments, currentPluginId, isLoading, onSelect, onRefresh, editorStage, onShowEditor, onBackToInstruments, selectedInstrumentName, soundHistory, soundHistoryCursor, onRestoreSound, onToggleFavorite, onImportSound, importSoundLabel, editNotes, onNotesChange, editBars, editBpm, editSnap, onAuditionNote, }: TrackDrawerProps): React.ReactElement;
+declare function TrackDrawer({ activeTab, onTabChange, trackId, fxState, onFxToggle, onFxPresetChange, onFxDryWetChange, fxDisabled, instruments, currentPluginId, isLoading, onSelect, onRefresh, editorStage, onShowEditor, onBackToInstruments, selectedInstrumentName, soundHistory, soundHistoryCursor, onRestoreSound, onToggleFavorite, onImportSound, importSoundLabel, editNotes, onNotesChange, editBars, editBpm, editSnap, onAuditionNote, }: TrackDrawerProps): React$1.ReactElement;
 
 /**
  * useTrackLevels — drives the cosmetic per-track strip meters.
@@ -2525,7 +2525,7 @@ interface SDKTrackRowProps {
      *  like CrossfadeTrackRow owns a single delete for the whole pair). */
     onDelete?: () => void;
     /** Custom content replacing the prompt input (e.g., sample info display) */
-    contentSlot?: React.ReactNode;
+    contentSlot?: React$1.ReactNode;
     /** Toggle mute */
     onMuteToggle: () => void;
     /** Toggle solo */
@@ -2599,7 +2599,7 @@ interface SDKTrackRowProps {
      *  a thin peak meter welds to the bottom of the row. Omit to hide it. */
     levels?: TrackLevelsHandle;
 }
-declare function TrackRow({ track, prompt, runtimeState, soloedOut, fxDetailState, drawerOpen, drawerTab, onTabChange, isGenerating, isAuthenticated, error, hasMidi, generationProgress, estimatedGenerationMs, onPromptChange, onGenerate, onShuffle, onCopy, onDelete, contentSlot, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onFxToggle, onFxPresetChange, onFxDryWetChange, onToggleFxDrawer, onProgressChange, accentColor, instrumentName, instrumentMissing, onToggleDrawer, availableInstruments, currentInstrumentPluginId, onInstrumentSelect, instrumentsLoading, onRefreshInstruments, editorStage, onShowEditor, onBackToInstruments, soundHistory, soundHistoryCursor, onRestoreSound, onToggleFavorite, onImportSound, importSoundLabel, editNotes, onNotesChange, editBars, editBpm, editSnap, onAuditionNote, drag, levels, }: SDKTrackRowProps): React.ReactElement;
+declare function TrackRow({ track, prompt, runtimeState, soloedOut, fxDetailState, drawerOpen, drawerTab, onTabChange, isGenerating, isAuthenticated, error, hasMidi, generationProgress, estimatedGenerationMs, onPromptChange, onGenerate, onShuffle, onCopy, onDelete, contentSlot, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onFxToggle, onFxPresetChange, onFxDryWetChange, onToggleFxDrawer, onProgressChange, accentColor, instrumentName, instrumentMissing, onToggleDrawer, availableInstruments, currentInstrumentPluginId, onInstrumentSelect, instrumentsLoading, onRefreshInstruments, editorStage, onShowEditor, onBackToInstruments, soundHistory, soundHistoryCursor, onRestoreSound, onToggleFavorite, onImportSound, importSoundLabel, editNotes, onNotesChange, editBars, editBpm, editSnap, onAuditionNote, drag, levels, }: SDKTrackRowProps): React$1.ReactElement;
 
 /**
  * Crossfade-pair metadata — family-agnostic types + parsing shared by every
@@ -2762,7 +2762,7 @@ interface CrossfadeTrackRowProps {
     /** Left-border accent. Defaults to transition purple. */
     accentColor?: string;
 }
-declare function CrossfadeTrackRow({ origin, target, sliderPos, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onDelete, onSliderChange, levels, accentColor, }: CrossfadeTrackRowProps): React.ReactElement;
+declare function CrossfadeTrackRow({ origin, target, sliderPos, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onDelete, onSliderChange, levels, accentColor, }: CrossfadeTrackRowProps): React$1.ReactElement;
 
 /**
  * Crossfade MIDI inpainting — builds the LLM user-prompt for a bridge that
@@ -2984,7 +2984,7 @@ interface FadeTrackRowProps {
     /** Left-border accent. Defaults to transition purple. */
     accentColor?: string;
 }
-declare function FadeTrackRow({ layer, direction, gesture, effect, sliderPos, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onDelete, onSliderChange, levels, accentColor, }: FadeTrackRowProps): React.ReactElement;
+declare function FadeTrackRow({ layer, direction, gesture, effect, sliderPos, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onDelete, onSliderChange, levels, accentColor, }: FadeTrackRowProps): React$1.ReactElement;
 
 /**
  * FadeModal — "add a fade" picker for a transition scene.
@@ -3039,7 +3039,7 @@ interface FadeModalProps {
     /** data-testid prefix. */
     testIdPrefix?: string;
 }
-declare function FadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: FadeModalProps): React.ReactElement | null;
+declare function FadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: FadeModalProps): React$1.ReactElement | null;
 
 /**
  * ImportTrackModal — "import a track from another scene" picker (SDK component).
@@ -3097,7 +3097,7 @@ interface ImportTrackModalProps {
         role?: string;
     }) => void | Promise<void>;
 }
-declare function ImportTrackModal({ host, open, onClose, onImported, title, testIdPrefix, mode, onPick, onPortTrack, }: ImportTrackModalProps): React.ReactElement | null;
+declare function ImportTrackModal({ host, open, onClose, onImported, title, testIdPrefix, mode, onPick, onPortTrack, }: ImportTrackModalProps): React$1.ReactElement | null;
 
 /**
  * CrossfadeModal — "add a crossfade track" picker for a transition scene.
@@ -3153,7 +3153,7 @@ interface CrossfadeModalProps {
     /** data-testid prefix. */
     testIdPrefix?: string;
 }
-declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
+declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React$1.ReactElement | null;
 
 /**
  * TransitionDesigner — the per-panel transition staging board, rendered INLINE as
@@ -3221,7 +3221,7 @@ interface TransitionDesignerProps {
     /** data-testid prefix. */
     testIdPrefix?: string;
 }
-declare function TransitionDesigner({ host, fromSceneId, toSceneId, transitionSceneId, excludeSourceDbIds, onCreateCrossfade, onCreateFade, onCreateAudioTransition, familyLabel, testIdPrefix, }: TransitionDesignerProps): React.ReactElement;
+declare function TransitionDesigner({ host, fromSceneId, toSceneId, transitionSceneId, excludeSourceDbIds, onCreateCrossfade, onCreateFade, onCreateAudioTransition, familyLabel, testIdPrefix, }: TransitionDesignerProps): React$1.ReactElement;
 
 /**
  * Transition Designer — pure helpers for the per-panel transition staging board.
@@ -3351,7 +3351,7 @@ interface ConfirmDialogProps {
     /** Bold heading line. */
     title: string;
     /** Body copy — a string or richer node. */
-    message: React.ReactNode;
+    message: React$1.ReactNode;
     /** Confirm button label (default "Delete"). */
     confirmLabel?: string;
     /** Cancel button label (default "Cancel"). */
@@ -3365,7 +3365,7 @@ interface ConfirmDialogProps {
     /** data-testid prefix so each dialog is addressable in tests. */
     testIdPrefix?: string;
 }
-declare function ConfirmDialog({ open, title, message, confirmLabel, cancelLabel, destructive, onConfirm, onCancel, testIdPrefix, }: ConfirmDialogProps): React.ReactElement | null;
+declare function ConfirmDialog({ open, title, message, confirmLabel, cancelLabel, destructive, onConfirm, onCancel, testIdPrefix, }: ConfirmDialogProps): React$1.ReactElement | null;
 
 /**
  * Modal — the SDK's one modal-stacking primitive (portal + z-tier + backdrop).
@@ -3392,7 +3392,7 @@ interface ModalProps {
     /** Close handler — fired on Escape and backdrop click. */
     onClose: () => void;
     /** The dialog box. Give it `onClick={e => e.stopPropagation()}`. */
-    children: React.ReactNode;
+    children: React$1.ReactNode;
     /** data-testid prefix; the backdrop is `${testIdPrefix}-overlay`. */
     testIdPrefix?: string;
     /** Close when the backdrop is clicked (default true). */
@@ -3400,9 +3400,9 @@ interface ModalProps {
     /** Close on Escape (default true). */
     closeOnEscape?: boolean;
     /** Focused when the modal opens (e.g. a Cancel button) so a reflexive Enter is safe. */
-    initialFocusRef?: React.RefObject<HTMLElement>;
+    initialFocusRef?: React$1.RefObject<HTMLElement>;
 }
-declare function Modal({ open, onClose, children, testIdPrefix, closeOnBackdrop, closeOnEscape, initialFocusRef, }: ModalProps): React.ReactElement | null;
+declare function Modal({ open, onClose, children, testIdPrefix, closeOnBackdrop, closeOnEscape, initialFocusRef, }: ModalProps): React$1.ReactElement | null;
 
 /**
  * PianoRollEditor — a compact, DOM-based MIDI note editor for the track drawer.
@@ -3507,7 +3507,7 @@ interface PianoRollEditorProps {
     /** Test id for the outer container. Default "sdk-piano-roll". */
     testId?: string;
 }
-declare function PianoRollEditor({ notes, onChange, bars, bpm, beatsPerBar, snap, snapOptions, onSnapChange, minPitch, maxPitch, autoFit, onAuditionNote, defaultVelocity, disabled, className, testId, }: PianoRollEditorProps): React.ReactElement;
+declare function PianoRollEditor({ notes, onChange, bars, bpm, beatsPerBar, snap, snapOptions, onSnapChange, minPitch, maxPitch, autoFit, onAuditionNote, defaultVelocity, disabled, className, testId, }: PianoRollEditorProps): React$1.ReactElement;
 
 /**
  * VolumeSlider Component
@@ -3526,7 +3526,7 @@ interface VolumeSliderProps {
     /** Additional CSS classes */
     className?: string;
 }
-declare const VolumeSlider: React.FC<VolumeSliderProps>;
+declare const VolumeSlider: React$1.FC<VolumeSliderProps>;
 
 /**
  * PanSlider Component
@@ -3546,7 +3546,7 @@ interface PanSliderProps {
     /** Additional CSS classes */
     className?: string;
 }
-declare const PanSlider: React.FC<PanSliderProps>;
+declare const PanSlider: React$1.FC<PanSliderProps>;
 
 /**
  * FxToggleBar Component
@@ -3565,7 +3565,7 @@ interface FxToggleBarProps {
     onDryWetChange: (trackId: string, category: FxCategory, value: number) => void;
     disabled?: boolean;
 }
-declare const FxToggleBar: React.FC<FxToggleBarProps>;
+declare const FxToggleBar: React$1.FC<FxToggleBarProps>;
 
 /**
  * SorceryProgressBar Component
@@ -3620,7 +3620,7 @@ declare function calculateTimeBasedTarget(elapsedMs: number, estimatedDurationMs
 /**
  * SorceryProgressBar - A mystical progress bar for uncertain wait times
  */
-declare function SorceryProgressBar({ isLoading, statusText, completeText, onComplete, heightClass, initialProgress, onProgressChange, estimatedDurationMs, }: SorceryProgressBarProps): React.ReactElement | null;
+declare function SorceryProgressBar({ isLoading, statusText, completeText, onComplete, heightClass, initialProgress, onProgressChange, estimatedDurationMs, }: SorceryProgressBarProps): React$1.ReactElement | null;
 
 /**
  * DownloadPackButton — versioned-pack download trigger (SDK component).
@@ -3647,7 +3647,7 @@ interface DownloadPackButtonProps {
     /** Called once after the install completes (status === 'complete'). */
     onDownloadComplete?: () => void;
 }
-declare const DownloadPackButton: React.FC<DownloadPackButtonProps>;
+declare const DownloadPackButton: React$1.FC<DownloadPackButtonProps>;
 
 /**
  * SamplePackCTACard — empty-state card a generator panel renders when its
@@ -3674,7 +3674,7 @@ interface SamplePackCTACardProps {
     status: SamplePackCTACardStatus;
     onDownloadComplete?: () => void;
 }
-declare const SamplePackCTACard: React.FC<SamplePackCTACardProps>;
+declare const SamplePackCTACard: React$1.FC<SamplePackCTACardProps>;
 
 /**
  * WaveformView — small canvas waveform for an audio file on disk.
@@ -3707,7 +3707,7 @@ interface WaveformViewProps {
      */
     targetSamples?: number;
 }
-declare const WaveformView: React.FC<WaveformViewProps>;
+declare const WaveformView: React$1.FC<WaveformViewProps>;
 
 /**
  * Shared level-meter component.
@@ -3753,7 +3753,7 @@ interface LevelMeterProps {
     /** Inline test id — make multiple instances distinguishable. */
     'data-testid'?: string;
 }
-declare const LevelMeter: React.FC<LevelMeterProps>;
+declare const LevelMeter: React$1.FC<LevelMeterProps>;
 
 /**
  * TrackMeterStrip — the thin per-track peak meter welded to the bottom of a
@@ -3776,7 +3776,7 @@ interface TrackMeterStripProps {
     /** Optional className for layout tweaks on the wrapper. */
     className?: string;
 }
-declare const TrackMeterStrip: React.FC<TrackMeterStripProps>;
+declare const TrackMeterStrip: React$1.FC<TrackMeterStripProps>;
 
 /**
  * ScrollingWaveform — live waveform during recording (Phase 8.10).
@@ -3807,7 +3807,7 @@ interface ScrollingWaveformProps {
     /** Highlight color for the wave. */
     fillStyle?: string;
 }
-declare const ScrollingWaveform: React.FC<ScrollingWaveformProps>;
+declare const ScrollingWaveform: React$1.FC<ScrollingWaveformProps>;
 
 /**
  * OffsetScrubber — manual sample-offset slider for Lyria-generated audio.
@@ -3847,7 +3847,7 @@ interface OffsetScrubberProps {
     /** Disable interaction (e.g., during generation / split). */
     disabled?: boolean;
 }
-declare function OffsetScrubber({ cuePoints, offsetSamples, projectBpm, meter, onChange, disabled, }: OffsetScrubberProps): React.ReactElement;
+declare function OffsetScrubber({ cuePoints, offsetSamples, projectBpm, meter, onChange, disabled, }: OffsetScrubberProps): React$1.ReactElement;
 
 /**
  * Shared waveform peaks + canvas drawer.
@@ -3939,51 +3939,6 @@ interface SynthesizeCuePointsOptions {
 }
 declare function synthesizeCuePoints({ bpm, sampleRate, bars, meter, }: SynthesizeCuePointsOptions): PluginCuePoints;
 
-/**
- * useSceneState — Scene-keyed state hook for plugin developers.
- *
- * Works like `useState`, but maintains separate state per scene.
- * When the user switches scenes, the previous scene's state is preserved
- * and restored when they switch back.
- *
- * Returns `[value, setForCurrentScene, setForScene]`:
- * - `value` — state for the currently active scene
- * - `setForCurrentScene(v)` — updates state for whatever scene is active at call time
- * - `setForScene(sceneId, v)` — updates state for a specific scene (for async callbacks)
- *
- * Both setters support the functional updater pattern: `prev => next`.
- *
- * **Important:** For object/array `initialValue`, hoist to a module-level constant
- * to keep the setter callbacks referentially stable:
- * ```ts
- * const EMPTY: string[] = [];
- * const [items, setItems, setItemsForScene] = useSceneState(activeSceneId, EMPTY);
- * ```
- */
-type SetSceneState<T> = (value: T | ((prev: T) => T)) => void;
-type SetSceneStateForScene<T> = (sceneId: string, value: T | ((prev: T) => T)) => void;
-declare function useSceneState<T>(activeSceneId: string | null, initialValue: T): [T, SetSceneState<T>, SetSceneStateForScene<T>];
-
-/**
- * useAnySolo — reactively reports whether ANY track in the project is soloed.
- *
- * Solo is cross-panel: when the user solos a track in ANY panel, the engine's
- * effective-mute model silences every non-soloed track. A panel uses this flag
- * to DIM its own non-soloed rows without lighting their Mute buttons:
- *
- * ```tsx
- * const anySolo = useAnySolo(host);
- * // ...
- * <TrackRow soloedOut={anySolo && !track.runtimeState.solo} ... />
- * ```
- *
- * Refreshes on mount and on every track-state change. `onTrackStateChange`
- * fires for tracks in ALL panels (not just this plugin's), so a solo toggled in
- * another panel updates this flag too.
- */
-
-declare function useAnySolo(host: Pick<PluginHost, 'isAnySoloActive' | 'onTrackStateChange'>): boolean;
-
 /**
  * useSoundHistory — generic, per-track "what sounds has this track had?" stack.
  *
@@ -4045,6 +4000,656 @@ interface UseSoundHistoryResult {
 }
 declare function useSoundHistory(applySound: (trackId: string, descriptor: unknown) => Promise<void>, opts?: UseSoundHistoryOptions): UseSoundHistoryResult;
 
+/**
+ * Per-track state model shared by every generator panel built on the
+ * panel-core. Verbatim generalization of the synth panel's SynthTrackState
+ * (SynthGeneratorPanel.tsx:67–100) — field names, defaults, and semantics are
+ * frozen by the Phase-0 behavior pin.
+ *
+ * @since SDK 2.35.0
+ */
+
+/** Internal track state combining handle + runtime state + prompt. */
+interface GeneratorTrackState {
+    handle: PluginTrackHandle;
+    prompt: string;
+    role: string;
+    runtimeState: PluginTrackRuntimeState;
+    fxDetailState: TrackFxDetailState;
+    drawerOpen: boolean;
+    drawerTab: DrawerTab;
+    editorStage: boolean;
+    isGenerating: boolean;
+    error: string | null;
+    hasMidi: boolean;
+    generationProgress: number;
+    editNotes: PluginMidiNote[];
+    editBars: number;
+    editBpm: number;
+    instrumentPluginId: string | null;
+    instrumentName: string | null;
+    instrumentMissing: boolean;
+    /**
+     * Per-track shuffle history: sound/preset names already handed back since
+     * the track was created OR since the history was reset (which happens
+     * automatically when the pool is exhausted — the family shuffle adapter
+     * reports "exhausted" and the core wipes the history and retries). Cycle
+     * pattern: cycle through everything before any repeat.
+     */
+    shuffleHistory: Set<string>;
+}
+/**
+ * Fresh track state with the panel defaults (the add-track literal at
+ * SynthGeneratorPanel.tsx:634–654). `overrides` lets loadTracks hydrate
+ * prompt/role/runtime/fx/etc. from fetched state in one construction.
+ */
+declare function newTrackState(handle: PluginTrackHandle, overrides?: Partial<Omit<GeneratorTrackState, 'handle'>>): GeneratorTrackState;
+
+/**
+ * Generic multi-track group seam — the crossfade-pair pattern, family- and
+ * meta-parameterized.
+ *
+ * A "track group" is N normal tracks linked by a shared `groupId` persisted in
+ * scene plugin_data under one key PER MEMBER: `track:<dbId>:<metaKey>`. Groups
+ * are never stored as a group-level record; they are assembled by scanning the
+ * member keys (single source of truth, survives member deletion gracefully).
+ * The panel-core resolves parsed groups against live tracks each render:
+ * complete groups render through a custom group row and their members are
+ * excluded from the normal row list; incomplete groups degrade per the
+ * extension's `isComplete` policy (crossfade: both members required; a bass
+ * voice-group: anchor required).
+ *
+ * This is the seam the crossfade/fade metas established (crossfade-meta.ts);
+ * new group families (e.g. the bass plugin's voice groups) ride it without
+ * panel-core changes.
+ *
+ * @since SDK 2.35.0
+ */
+/** One parsed member: the scene-data key's dbId + its narrowed meta value. */
+interface TrackGroupMember<M> {
+    dbId: string;
+    meta: M;
+}
+/** One parsed group (members in `sortMembers` order when provided). */
+interface TrackGroupMeta<M> {
+    groupId: string;
+    members: TrackGroupMember<M>[];
+}
+/** How to scan + narrow one group family out of scene plugin_data. */
+interface GroupParseSpec<M> {
+    /** Scene-data key suffix: scans `track:<dbId>:<metaKey>`. */
+    metaKey: string;
+    /** Defensive narrow (the `asCrossfadeMeta` pattern) — return null to skip. */
+    asMeta(val: unknown): M | null;
+    /** Extract the shared group id from a member meta. */
+    groupIdOf(meta: M): string;
+    /** Stable member order (e.g. by voiceIndex). Omit = scene-data scan order. */
+    sortMembers?(a: TrackGroupMember<M>, b: TrackGroupMember<M>): number;
+}
+/**
+ * Scan all `track:<dbId>:<metaKey>` keys in a scene's plugin_data and assemble
+ * groups. Pure — no I/O; caller passes the already-fetched scene data map.
+ */
+declare function parseTrackGroups<M>(sceneData: Record<string, unknown>, spec: GroupParseSpec<M>): TrackGroupMeta<M>[];
+/** A group resolved against live tracks (only members whose track exists). */
+interface ResolvedTrackGroup<M, T> {
+    groupId: string;
+    members: Array<{
+        dbId: string;
+        meta: M;
+        track: T;
+    }>;
+}
+interface ResolveGroupsOptions<M, T> {
+    /**
+     * Group completeness policy. A group failing this renders as loose normal
+     * rows instead (its members are NOT excluded). Default: every PARSED member
+     * resolved a live track — the crossfade rule (partner deleted ⇒ degrade).
+     */
+    isComplete?(group: ResolvedTrackGroup<M, T>, parsed: TrackGroupMeta<M>): boolean;
+}
+interface ResolvedGroupsResult<M, T> {
+    /** Complete groups, ready for the group row renderer. */
+    resolved: ResolvedTrackGroup<M, T>[];
+    /** dbIds of members of COMPLETE groups — exclude these from normal rows. */
+    memberDbIds: Set<string>;
+    /**
+     * dbIds whose member key exists but whose track is gone (deleted
+     * out-of-band) — candidates for lazy scene-data cleanup.
+     */
+    staleMemberDbIds: string[];
+}
+/**
+ * Resolve parsed groups against live track state. Pure; call from a useMemo
+ * keyed on [tracks, parsedGroups] (fresh array identities per call are
+ * expected — do NOT key effects on the arrays without a string-key guard,
+ * see the drift-resync `lastResyncKeyRef` pattern).
+ */
+declare function resolveTrackGroups<M, T>(parsedGroups: TrackGroupMeta<M>[], tracks: readonly T[], getDbId: (track: T) => string, opts?: ResolveGroupsOptions<M, T>): ResolvedGroupsResult<M, T>;
+
+/**
+ * Small pure helpers shared by every generator panel — moved verbatim out of
+ * the three panel monoliths (synth/drum/instrument each carried a copy of
+ * pluginFxToToggleFx and an LLM note-response parser).
+ *
+ * @since SDK 2.35.0
+ */
+
+/**
+ * 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
+ * engine id, which changes on project reload. This is the ONLY key builder
+ * panels and generation strategies should use.
+ */
+declare function trackDataKey(dbId: string, suffix: string): string;
+/** Convert SDK PluginTrackFxDetailState to the FxToggleBar's expected TrackFxDetailState. */
+declare function pluginFxToToggleFx(sdkState: PluginTrackFxDetailState): TrackFxDetailState;
+/** Shape of the parsed flat LLM JSON note response. */
+interface LLMNoteResponse {
+    notes: PluginMidiNote[];
+    role?: string;
+}
+/**
+ * Parse the LLM JSON response and extract valid MIDI notes (flat
+ * `{notes:[...], role?}` schema). Handles markdown code fences; silently
+ * filters invalid notes; returns null when nothing parses.
+ */
+declare function parseLLMNoteResponse(content: string): LLMNoteResponse | null;
+
+/**
+ * GeneratorPanelAdapter — the family-specific contract a generator panel
+ * supplies to the shared panel-core (useGeneratorPanelCore + GeneratorPanelShell).
+ *
+ * The core owns everything the three historical panel monoliths duplicated:
+ * track load/reconcile, event subscriptions, prompt persistence, mixer/FX ops,
+ * drawer + piano-roll wiring, shuffle cycling, transition crossfade/fade
+ * machinery, and the render skeleton. The adapter supplies what genuinely
+ * differs per family: sound serialization, the 🎲 resolver, the generation
+ * pipeline body, create-track options, prompts/parsers, identity strings,
+ * feature flags, and (optionally) custom multi-track group rendering.
+ *
+ * Adapter instances MUST be referentially stable across renders — build them
+ * in a `useMemo(() => createXAdapter(host), [host])`. An unstable adapter
+ * re-creates the core's loadTracks callback every render (the historical
+ * useSoundHistory render-loop failure mode).
+ *
+ * @since SDK 2.35.0
+ */
+
+/**
+ * Family identity strings + numeric knobs. All panel test-ids derive from
+ * `familyKey` (`add-<key>-track-button`, `<key>-section`, `<key>-view-toggle`,
+ * `no-scene-placeholder-<key>`, `no-contract-placeholder-<key>`,
+ * `<key>-import`, `<key>-sound-import`, `<key>-transition-designer`) — the
+ * synth panel's historical ids are exactly this derivation with key 'synth'.
+ */
+interface PanelIdentity {
+    /** Test-id + focus-selector stem, e.g. 'synth'. */
+    familyKey: string;
+    /** Human label for the TransitionDesigner header, e.g. 'Synths'. */
+    familyLabel: string;
+    /** New-track name prefix, e.g. 'synth' → `synth-<ts>`. */
+    trackNamePrefix: string;
+    /** Console log tag, e.g. 'SynthGeneratorPanel'. */
+    logTag: string;
+    /** Normal row accent, e.g. '#A78BFA'. */
+    accentColor: string;
+    /** Crossfade/fade row accent, e.g. '#9333EA'. */
+    transitionAccentColor: string;
+    /** Bulk placeholder left-border accent, e.g. '#3B82F6'. */
+    placeholderAccentColor: string;
+    /** Per-plugin per-scene track budget (host enforces 16 too). */
+    maxTracks: number;
+    /** Progress-bar pacing for one generation. */
+    estimatedGenerationMs: number;
+    /** Header button label; default 'Add Track'. */
+    addTrackLabel?: string;
+    /** Header button label; default 'Import Track'. */
+    importTrackLabel?: string;
+    /** Export dialog default filename; default 'midi-tracks'. */
+    exportDefaultName?: string;
+    /**
+     * Plugin id treated as the family's built-in default instrument in the Pick
+     * tab (select it ⇒ close drawer instead of entering the editor stage).
+     * Default 'Surge XT'.
+     */
+    defaultInstrumentPluginId?: string;
+}
+/** Which core surfaces this family mounts. */
+interface PanelFeatureFlags {
+    /** Pick tab + instrument descriptors + editor stage (synth: true). */
+    instrumentPicker: boolean;
+    /** COMPOSING bar + bulk placeholder hybrid phase (synth: true). */
+    bulkComposePlaceholders: boolean;
+    /** "Export Tracks" ZIP button (synth: true). */
+    exportMidi: boolean;
+    /** Transition scene designer + crossfade/fade rows (synth: true). */
+    transitionDesigner: boolean;
+    /** ImportTrackModal + port-track flow + sound-import drawer action (synth: true). */
+    importTracks: boolean;
+}
+/** How this family captures / applies / copies a track's SOUND. */
+interface PanelSoundAdapter {
+    /**
+     * Re-apply an opaque sound-history descriptor (useSoundHistory's applySound).
+     * Synth: `{state, stateType}` through set(Raw)PluginState's dual path.
+     */
+    applySound(trackId: string, descriptor: unknown): Promise<void>;
+    /**
+     * Snapshot the track's current sound as a history descriptor, or null when
+     * the track has no instrument. The CORE records it into soundHistory.
+     */
+    captureSoundDescriptor(trackId: string): Promise<{
+        descriptor: unknown;
+    } | null>;
+    /**
+     * Apply a host.getTrackSound snapshot to a track AND persist it as the
+     * track's durable identity (persistTrackPresetState or family equivalent —
+     * REQUIRED or the transition drift-resync never converges). Returns the
+     * applied label. Used by crossfade/fade copy + drift-resync.
+     */
+    copySnapshot(trackId: string, snap: TrackSoundSnapshot): Promise<string>;
+    /**
+     * Convert a host.getTrackSound snapshot into this family's sound-history
+     * descriptor (synth: `{state, stateType}`). Used by the drawer's sound
+     * import so the imported sound lands in history with the right shape.
+     */
+    descriptorFromSnapshot(snap: TrackSoundSnapshot): unknown;
+    /** Snapshot kind accepted by the drawer's "Import <noun>" (synth: 'preset'). */
+    acceptedSnapshotKind: 'preset' | 'sample' | 'instrument';
+    /** Sound-history cap (synth: 12 — Surge blobs are large). */
+    historyMax: number;
+    /** Drawer action label, e.g. 'Import Preset'. */
+    importSoundLabel: string;
+    /** Noun for import toasts: 'No <noun> to import' / '<Noun> imported'. */
+    importNoun: string;
+    /** History label for the lazily-seeded pre-shuffle sound, e.g. 'Previous preset'. */
+    previousSoundLabel: string;
+}
+/** The 🎲: pick + apply one new sound, honoring the exclusion cycle. */
+interface PanelShuffleAdapter {
+    /**
+     * Pick + apply a sound not in `excludeNames`. Throw when the pool is
+     * exhausted (`isExhaustedError` must recognize it) — the core wipes the
+     * track's history and retries once with an empty exclusion list.
+     */
+    shuffle(track: GeneratorTrackState, excludeNames: string[]): Promise<{
+        appliedName: string;
+    }>;
+    /** Distinguish "pool exhausted" (expected; cycle resets) from real failures. */
+    isExhaustedError(err: unknown): boolean;
+}
+/**
+ * Capabilities the core hands to the generation strategy (and group
+ * renderers). Built fresh per call — do not cache across renders.
+ */
+interface GenerationServices {
+    host: PluginHost;
+    activeSceneId: string | null;
+    /** Live track list snapshot at call time. */
+    tracks: GeneratorTrackState[];
+    /** Patch one track's state (object merge or functional update). */
+    updateTrack(trackId: string, patch: Partial<GeneratorTrackState> | ((t: GeneratorTrackState) => GeneratorTrackState)): void;
+    /** Escape hatch for multi-track updates (reconcile flows). */
+    setTracks: React.Dispatch<React.SetStateAction<GeneratorTrackState[]>>;
+    reloadTracks(incremental?: boolean): Promise<void>;
+    soundHistory: UseSoundHistoryResult;
+    /** Engine id → stable DB UUID (falls back to the input when unknown). */
+    engineToDbId(trackId: string): string;
+    /** The ONLY scene-data key builder (always dbId-based). */
+    trackDataKey(dbId: string, suffix: string): string;
+    /** Latch a track as piano-roll-loaded (post-generation seeding). */
+    markEditLoaded(trackId: string): void;
+    /** Create a family track (adapter options + `<prefix>-<ts><suffix>` name). */
+    createFamilyTrack(nameSuffix?: string): Promise<PluginTrackHandle>;
+    /** Resolved groups for a registered group extension. */
+    resolvedGroups<M>(metaKey: string): ResolvedTrackGroup<M, GeneratorTrackState>[];
+}
+/**
+ * One prompt-driven generation turn. The core owns the wrapper: prompt/auth
+ * gates, `isGenerating: true`, and the catch (error patch + 'Generation
+ * failed' toast). The strategy owns the body — synth: LLM → clip on THIS
+ * track → mute → role persist → shufflePreset → success patch; bass: LLM line
+ * → validate/split → reconcile member tracks → per-voice clips + presets →
+ * metas → reload.
+ */
+interface PanelGenerationStrategy {
+    generate(track: GeneratorTrackState, services: GenerationServices): Promise<void>;
+}
+/** Core per-track handlers, same instances the normal rows use. */
+interface CoreTrackHandlers {
+    promptChange(trackId: string, prompt: string): void;
+    generate(trackId: string): void;
+    shuffle(trackId: string): void;
+    copy(trackId: string): void;
+    delete(trackId: string): void;
+    muteToggle(trackId: string): void;
+    soloToggle(trackId: string): void;
+    volumeChange(trackId: string, volume: number): void;
+    panChange(trackId: string, pan: number): void;
+    tabChange(trackId: string, tab: DrawerTab): void;
+    toggleDrawer(trackId: string): void;
+    toggleFxDrawer(trackId: string): void;
+    notesChange(trackId: string, notes: PluginMidiNote[]): void;
+    progressChange(trackId: string, pct: number): void;
+}
+/** Render-time context handed to a group extension's renderGroup. */
+interface GroupRenderContext {
+    services: GenerationServices;
+    anySolo: boolean;
+    supportsMeters: boolean;
+    levels?: TrackLevelsHandle;
+    handlers: CoreTrackHandlers;
+    /**
+     * Build the shell's default TrackRow for a member with per-row overrides —
+     * group renderers stack these instead of reimplementing the ~50-prop plumbing.
+     */
+    renderDefaultTrackRow(track: GeneratorTrackState, overrides?: Partial<SDKTrackRowProps>, drag?: TrackRowDragProps): ReactNode;
+    /** Optimistic group mute (crossfade group-control pattern). */
+    setGroupMute(trackIds: string[], muted: boolean): void;
+    /** Optimistic group solo. */
+    setGroupSolo(trackIds: string[], solo: boolean): void;
+    /**
+     * Delete all member tracks + their `track:<dbId>:<suffix>` scene-data keys
+     * (per cleanupKeySuffixes) + prune local state. Best-effort per member.
+     */
+    deleteGroup(members: Array<{
+        engineId: string;
+        dbId: string;
+    }>, cleanupKeySuffixes: string[]): Promise<void>;
+}
+/**
+ * A family-registered multi-track group row (the crossfade seam,
+ * parameterized). Members of complete groups render through `renderGroup`
+ * and are excluded from the normal row list; incomplete groups degrade to
+ * normal rows per `isComplete`.
+ */
+interface PanelGroupExtension<M = unknown> extends GroupParseSpec<M> {
+    /**
+     * Completeness policy (default: every parsed member's track is live).
+     * Bass voice-groups: the anchor member (voiceIndex 0) must be live.
+     */
+    isComplete?(group: ResolvedTrackGroup<M, GeneratorTrackState>, parsed: TrackGroupMeta<M>): boolean;
+    renderGroup(group: ResolvedTrackGroup<M, GeneratorTrackState>, ctx: GroupRenderContext): ReactNode;
+}
+interface GeneratorPanelAdapter<M = unknown> {
+    identity: PanelIdentity;
+    features: PanelFeatureFlags;
+    /** Options for host.createTrack (name is core-built). Synth: `{loadSynth:true, synthName:'Surge XT'}`. */
+    createTrackOptions(): Omit<CreateTrackOptions, 'name'>;
+    /**
+     * Port-flow sound step after the MIDI copy (cross-panel Import Track).
+     * Synth: `host.shufflePreset(handle.id)` non-fatal.
+     */
+    applyPortedTrackSound(handle: PluginTrackHandle, role?: string): 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). */
+    parseNotesResponse(content: string): LLMNoteResponse | null;
+    sound: PanelSoundAdapter;
+    shuffle: PanelShuffleAdapter;
+    generation: PanelGenerationStrategy;
+    /** Custom multi-track group rows (bass voice groups). */
+    groupExtensions?: PanelGroupExtension<M>[];
+    /** Patch the default TrackRow props per row (drum's sampleName fallback). */
+    mapTrackRowProps?(track: GeneratorTrackState, props: SDKTrackRowProps): SDKTrackRowProps;
+}
+/** Panel-local render extension points around the shell's row list. */
+interface GeneratorPanelSlots {
+    beforeRows?: ReactNode;
+    afterRows?: ReactNode;
+    /** Extra modals (rendered in the normal phase only). */
+    modals?: ReactNode;
+}
+
+/**
+ * Transition-scene machinery for panel-core panels — crossfade pair + fade
+ * creation, group controls, sliders, drift re-sync, and fade curve re-apply.
+ * Moved VERBATIM from the synth panel (SynthGeneratorPanel.tsx 715–987,
+ * 1148–1235, 1787–1847) with the family-specific pieces routed through the
+ * GeneratorPanelAdapter (sound copy/persist, system prompt, note parsing,
+ * track naming). Semantics are frozen by the Phase-0 behavior pin.
+ *
+ * Deliberately NOT rewritten onto the generic group seam (group-meta.ts) —
+ * that seam is additive for new families (bass voice groups); migrating
+ * crossfades onto it is a contained follow-up.
+ *
+ * @since SDK 2.35.0
+ */
+
+/** A crossfade pair resolved against live track state (both members present). */
+interface ResolvedCrossfadePair extends CrossfadePairMeta {
+    origin: GeneratorTrackState;
+    target: GeneratorTrackState;
+}
+/** A fade (transition orphan) resolved against live track state. */
+interface ResolvedFade extends FadeEntry {
+    track: GeneratorTrackState;
+}
+interface UseTransitionOpsInputs {
+    host: PluginHost;
+    adapter: GeneratorPanelAdapter;
+    activeSceneId: string | null;
+    isConnected: boolean;
+    isAuthenticated: boolean;
+    sceneContext: PluginSceneContext | null | undefined;
+    tracks: GeneratorTrackState[];
+    setTracks: React.Dispatch<React.SetStateAction<GeneratorTrackState[]>>;
+    loadTracks(incremental?: boolean): Promise<void>;
+    setCrossfadePairsMeta: React.Dispatch<React.SetStateAction<CrossfadePairMeta[]>>;
+    setFadesMeta: React.Dispatch<React.SetStateAction<FadeEntry[]>>;
+    resolvedCrossfadePairs: ResolvedCrossfadePair[];
+    resolvedFades: ResolvedFade[];
+}
+interface TransitionOps {
+    isCreatingCrossfade: boolean;
+    isCreatingFade: boolean;
+    handleCreateCrossfade(origin: CrossfadeSelection, target: CrossfadeSelection): Promise<void>;
+    handleCreateFade(selection: FadeSelection, direction: FadeDirection, gesture: FadeGesture): Promise<void>;
+    handleCrossfadeMute(pair: ResolvedCrossfadePair): void;
+    handleCrossfadeSolo(pair: ResolvedCrossfadePair): void;
+    handleCrossfadeDelete(pair: ResolvedCrossfadePair): Promise<void>;
+    handleCrossfadeSlider(pair: ResolvedCrossfadePair, pos: number): void;
+    handleFadeDelete(fade: ResolvedFade): Promise<void>;
+    handleFadeSlider(fade: ResolvedFade, pos: number): void;
+}
+declare function useTransitionOps({ host, adapter, activeSceneId, isConnected, isAuthenticated, sceneContext, tracks, setTracks, loadTracks, setCrossfadePairsMeta, setFadesMeta, resolvedCrossfadePairs, resolvedFades, }: UseTransitionOpsInputs): TransitionOps;
+
+/**
+ * useGeneratorPanelCore — the shared state/effects/handlers engine behind
+ * generator panels (synth today; bass next; drum/instrument candidates).
+ *
+ * Verbatim extraction of the synth panel monolith's family-agnostic ~85%
+ * (SynthGeneratorPanel.tsx), parameterized by a GeneratorPanelAdapter. Every
+ * timing (500ms prompt debounce, 500ms agent-mutation coalesce, 300ms notes
+ * save, 350ms add-focus), every scene-data key (`track:<dbId>:…`), every
+ * toast string, and every host-call sequence is frozen by the Phase-0
+ * behavior pin (sas-app/src/__tests__/synth-panel-behavior.test.tsx).
+ *
+ * The returned `core` object is consumed by GeneratorPanelShell (render) and
+ * closed over by family adapters (generation strategies, group renderers).
+ *
+ * @since SDK 2.35.0
+ */
+
+interface UseGeneratorPanelCoreOptions {
+    /** The panel's PluginUIProps, passed through whole. */
+    ui: PluginUIProps;
+    /** Family adapter — MUST be referentially stable (useMemo on [host]). */
+    adapter: GeneratorPanelAdapter;
+}
+/** Everything GeneratorPanelShell + family extensions consume. */
+interface GeneratorPanelCore {
+    ui: PluginUIProps;
+    adapter: GeneratorPanelAdapter;
+    tracks: GeneratorTrackState[];
+    setTracks: React$1.Dispatch<React$1.SetStateAction<GeneratorTrackState[]>>;
+    isLoadingTracks: boolean;
+    loadTracks(incremental?: boolean): Promise<void>;
+    engineToDbId(trackId: string): string;
+    supportsMeters: boolean;
+    trackLevels: TrackLevelsHandle;
+    anySolo: boolean;
+    reorder: UseTrackReorderResult;
+    soundHistory: ReturnType<typeof useSoundHistory>;
+    isComposing: boolean;
+    placeholders: BulkAddPlaceholderTrack[];
+    isAddingTrack: boolean;
+    isExportingMidi: boolean;
+    designerView: boolean;
+    canCrossfade: boolean;
+    needsContract: boolean;
+    xfFromId: string | null;
+    xfToId: string | null;
+    importOpen: boolean;
+    setImportOpen(open: boolean): void;
+    soundImportTarget: GeneratorTrackState | null;
+    setSoundImportTarget(t: GeneratorTrackState | null): void;
+    handleSoundImportPick(sel: {
+        sourceTrackDbId: string;
+        trackName: string;
+        sceneName: string;
+    }): Promise<void>;
+    handlePortTrack(sel: {
+        sourceTrackDbId: string;
+        trackName: string;
+        role?: string;
+    }): Promise<void>;
+    transition: TransitionOps;
+    crossfadePairsMeta: CrossfadePairMeta[];
+    fadesMeta: FadeEntry[];
+    resolvedCrossfadePairs: ResolvedCrossfadePair[];
+    crossfadeMemberDbIds: Set<string>;
+    resolvedFades: ResolvedFade[];
+    fadeMemberDbIds: Set<string>;
+    resolvedGenericGroups: Record<string, ResolvedGroupsResult<unknown, GeneratorTrackState>>;
+    genericGroupMemberDbIds: Set<string>;
+    availableInstruments: InstrumentDescriptor[];
+    instrumentsLoading: boolean;
+    handlers: CoreTrackHandlers;
+    handleGenerate(trackId: string): Promise<void>;
+    handleShuffle(trackId: string): Promise<void>;
+    handleAddTrack(): Promise<void>;
+    handleDeleteTrack(trackId: string): Promise<void>;
+    handleExportMidi(): Promise<void>;
+    handlePromptChange(trackId: string, prompt: string): void;
+    handleMuteToggle(trackId: string): void;
+    handleSoloToggle(trackId: string): void;
+    handleVolumeChange(trackId: string, volume: number): void;
+    handlePanChange(trackId: string, pan: number): void;
+    handleTabChange(trackId: string, tab: DrawerTab): void;
+    handleToggleDrawer(trackId: string): void;
+    toggleFxDrawer(trackId: string): void;
+    handleNotesChange(trackId: string, notes: PluginMidiNote[]): void;
+    handleProgressChange(trackId: string, pct: number): void;
+    handleCopy(trackId: string): Promise<void>;
+    handleFxToggle(trackId: string, category: FxCategory, enabled: boolean): void;
+    handleFxPresetChange(trackId: string, category: FxCategory, presetIndex: number): void;
+    handleFxDryWetChange(trackId: string, category: FxCategory, value: number): void;
+    handleInstrumentSelect(trackId: string, pluginId: string): Promise<void>;
+    handleShowEditor(trackId: string): Promise<void>;
+    handleBackToInstruments(trackId: string): void;
+    handleRefreshInstruments(): void;
+    onAuditionNote(trackId: string, pitch: number, velocity: number, ms: number): void;
+    makeServices(): GenerationServices;
+    setGroupMute(trackIds: string[], muted: boolean): void;
+    setGroupSolo(trackIds: string[], solo: boolean): void;
+    deleteGroup(members: Array<{
+        engineId: string;
+        dbId: string;
+    }>, cleanupKeySuffixes: string[]): Promise<void>;
+}
+declare function useGeneratorPanelCore({ ui, adapter, }: UseGeneratorPanelCoreOptions): GeneratorPanelCore;
+
+/**
+ * GeneratorPanelShell — the shared render skeleton for panel-core panels.
+ *
+ * Verbatim extraction of the synth panel's render phases
+ * (SynthGeneratorPanel.tsx:1849–2195): no-scene gate → no-contract gate →
+ * COMPOSING → placeholder hybrid → normal (modals, mounted-but-hidden
+ * TransitionDesigner, crossfade/fade rows, generic group rows, normal rows,
+ * export button). The ~50-prop TrackRow plumbing that the monolith duplicated
+ * across the hybrid + normal phases lives here ONCE (`buildRowProps`), pinned
+ * by the Phase-0 props snapshot.
+ *
+ * @since SDK 2.35.0
+ */
+
+interface GeneratorPanelShellProps {
+    core: GeneratorPanelCore;
+    slots?: GeneratorPanelSlots;
+}
+declare function GeneratorPanelShell({ core, slots }: GeneratorPanelShellProps): React$1.ReactElement;
+
+/**
+ * Surge XT sound adapter — the PanelSoundAdapter shared by every family whose
+ * tracks host Surge XT (or a user-picked third-party VST3) as the instrument:
+ * synth and bass today.
+ *
+ * A "sound" is the INSTRUMENT plugin's state: default Surge XT round-trips
+ * through the Tracktion ValueTree (get/setPluginState); third-party
+ * instruments (u-he Diva, Serum, …) need their RAW VST3 state
+ * (get/setRawPluginState), which the ValueTree wrapper does not faithfully
+ * preserve. The instrument is the first non-utility plugin on the track.
+ * Matching only 'Surge' silently broke history for custom-instrument tracks
+ * pre-split — hence the dual path.
+ *
+ * @since SDK 2.35.0
+ */
+
+interface SurgeSoundAdapterOverrides {
+    /** Sound-history cap (default 12 — Surge state blobs are large). */
+    historyMax?: number;
+    /** Drawer action label (default 'Import Preset'). */
+    importSoundLabel?: string;
+}
+declare function createSurgeSoundAdapter(host: PluginHost, overrides?: SurgeSoundAdapterOverrides): PanelSoundAdapter;
+
+/**
+ * useSceneState — Scene-keyed state hook for plugin developers.
+ *
+ * Works like `useState`, but maintains separate state per scene.
+ * When the user switches scenes, the previous scene's state is preserved
+ * and restored when they switch back.
+ *
+ * Returns `[value, setForCurrentScene, setForScene]`:
+ * - `value` — state for the currently active scene
+ * - `setForCurrentScene(v)` — updates state for whatever scene is active at call time
+ * - `setForScene(sceneId, v)` — updates state for a specific scene (for async callbacks)
+ *
+ * Both setters support the functional updater pattern: `prev => next`.
+ *
+ * **Important:** For object/array `initialValue`, hoist to a module-level constant
+ * to keep the setter callbacks referentially stable:
+ * ```ts
+ * const EMPTY: string[] = [];
+ * const [items, setItems, setItemsForScene] = useSceneState(activeSceneId, EMPTY);
+ * ```
+ */
+type SetSceneState<T> = (value: T | ((prev: T) => T)) => void;
+type SetSceneStateForScene<T> = (sceneId: string, value: T | ((prev: T) => T)) => void;
+declare function useSceneState<T>(activeSceneId: string | null, initialValue: T): [T, SetSceneState<T>, SetSceneStateForScene<T>];
+
+/**
+ * useAnySolo — reactively reports whether ANY track in the project is soloed.
+ *
+ * Solo is cross-panel: when the user solos a track in ANY panel, the engine's
+ * effective-mute model silences every non-soloed track. A panel uses this flag
+ * to DIM its own non-soloed rows without lighting their Mute buttons:
+ *
+ * ```tsx
+ * const anySolo = useAnySolo(host);
+ * // ...
+ * <TrackRow soloedOut={anySolo && !track.runtimeState.solo} ... />
+ * ```
+ *
+ * Refreshes on mount and on every track-state change. `onTrackStateChange`
+ * fires for tracks in ALL panels (not just this plugin's), so a solo toggled in
+ * another panel updates this flag too.
+ */
+
+declare function useAnySolo(host: Pick<PluginHost, 'isAnySoloActive' | 'onTrackStateChange'>): boolean;
+
 /**
  * Plugin SDK Version
  *
@@ -4053,7 +4658,7 @@ declare function useSoundHistory(applySound: (trackId: string, descriptor: unkno
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.34.0";
+declare const PLUGIN_SDK_VERSION = "2.35.0";
 
 /**
  * FX Preset Definitions
@@ -4201,4 +4806,4 @@ interface PickTopKOptions {
  */
 declare function pickTopKWeighted<T>(scored: ReadonlyArray<ScoredCandidate<T>>, options?: PickTopKOptions): T | null;
 
-export { AUDIO_EFFECTS, AUDIO_EFFECT_LABEL, type AudioEffect, type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, type CrossfadeVolumeCurves, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, type DesignerRowSlots, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FadeDirection, type FadeEntry, type FadeGesture, type FadeLayer, type FadeMeta, FadeModal, type FadeModalProps, type FadeSelection, FadeTrackRow, type FadeTrackRowProps, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginSkill, type PluginSkillInputSchema, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TEXTURAL_ROLES, TRANSITION_DESIGNER_DRAFT_KEY, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, TransitionDesigner, type TransitionDesignerDraft, type TransitionDesignerProps, type TransitionRowType, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asAudioEffect, asCrossfadeMeta, asFadeMeta, asTransitionDesignerDraft, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildFadeVolumeCurve, buildRowSlots, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbIdsFromKeys, dbToSlider, defaultFadeGesture, drawWaveform, formatConcurrentTracks, hashString, moveItem, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseFades, pickTopKWeighted, pitchToName, pxToCell, reconcileSlots, resizeNoteDuration, rowKey, rowType, scorePromptMatch, sliderToDb, slotsEqual, soundIdentity, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };
+export { AUDIO_EFFECTS, AUDIO_EFFECT_LABEL, 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, EQUAL_POWER_GAIN, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FadeDirection, type FadeEntry, type FadeGesture, type FadeLayer, type FadeMeta, FadeModal, type FadeModalProps, type FadeSelection, FadeTrackRow, type FadeTrackRowProps, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, GUTTER_W, type GenerationServices, type GeneratorPanelAdapter, type GeneratorPanelCore, GeneratorPanelShell, type GeneratorPanelShellProps, type GeneratorPanelSlots, type GeneratorPlugin, type GeneratorTrackState, type GeneratorType, 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, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PanelFeatureFlags, type PanelGenerationStrategy, type PanelGroupExtension, type PanelIdentity, type PanelShuffleAdapter, type PanelSoundAdapter, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginSkill, type PluginSkillInputSchema, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type ResolveGroupsOptions, type ResolvedCrossfadePair, type ResolvedFade, type ResolvedGroupsResult, type ResolvedTrackGroup, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SurgeSoundAdapterOverrides, type SynthesizeCuePointsOptions, TEXTURAL_ROLES, TRANSITION_DESIGNER_DRAFT_KEY, TrackDrawer, type TrackDrawerProps, 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 UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, type UseTransitionOpsInputs, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asAudioEffect, asCrossfadeMeta, asFadeMeta, asTransitionDesignerDraft, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildFadeVolumeCurve, buildRowSlots, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, createSurgeSoundAdapter, dbIdsFromKeys, dbToSlider, defaultFadeGesture, drawWaveform, formatConcurrentTracks, hashString, moveItem, newTrackState, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseFades, parseLLMNoteResponse, parseTrackGroups, pickTopKWeighted, pitchToName, pluginFxToToggleFx, pxToCell, reconcileSlots, resizeNoteDuration, resolveTrackGroups, rowKey, rowType, scorePromptMatch, sliderToDb, slotsEqual, soundIdentity, synthesizeCuePoints, tokenizePrompt, trackDataKey, transposeNotes, useAnySolo, useGeneratorPanelCore, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransitionOps, useTransportPlaying };