@signalsandsorcery/plugin-sdk 2.3.1 → 2.25.1

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import React, { ComponentType, ReactNode } from 'react';
+import React, { ComponentType, ReactNode, DragEvent, Dispatch, SetStateAction } from 'react';
 
 /**
  * Plugin SDK Type Definitions
@@ -10,6 +10,67 @@ import React, { ComponentType, ReactNode } from 'react';
 
 /** What kind of Tracktion content this plugin creates */
 type GeneratorType = 'midi' | 'audio' | 'sample' | 'hybrid';
+/**
+ * Drum-kit configuration for `host.setTrackDrumKit`. Prototype shape carries
+ * a single sample; future multi-slot kits will extend this with a `notes`
+ * map (`Record<midiNote, samplePath>`) for GM-style drum maps.
+ */
+interface DrumKit {
+    /** Absolute path to the sample (WAV, AIFF, FLAC). Triggered on every note-on. */
+    samplePath: string;
+}
+/**
+ * One key-mapped sample zone in a pitched, polyphonic instrument.
+ * Used by `host.setTrackInstrumentSampler`.
+ *
+ * Zones in an InstrumentSampler MUST be disjoint and ordered low to
+ * high by rootKey — the engine rejects overlap because Tracktion would
+ * otherwise double-trigger every matching sound on each note-on.
+ */
+interface InstrumentZone {
+    /** Absolute path to the zone's sample (WAV, FLAC, AIFF). */
+    samplePath: string;
+    /** MIDI note this sample sounds at unshifted (0-127). */
+    rootKey: number;
+    /** Inclusive low end of the key range that triggers this zone (0-127). */
+    minKey: number;
+    /** Inclusive high end of the key range that triggers this zone (0-127). */
+    maxKey: number;
+    /**
+     * If true, the sampler plays the sample for the duration the note is
+     * held and stops on note-off (good for sustaining pads, organs, etc.,
+     * whose source has been pre-trimmed to a steady-state region).
+     * If false, the sampler plays the sample through to its end ignoring
+     * note-off (good for plucks, mallets, percussion).
+     */
+    openEnded: boolean;
+}
+/**
+ * Pitched instrument configuration for `host.setTrackInstrumentSampler`.
+ * Parallel to `DrumKit` but multi-zone and pitch-aware. A manifest
+ * authored by the pitched-sample pipeline reduces to one of these.
+ *
+ * NOTE: This is distinct from `host.setTrackInstrument(trackId, pluginId)`
+ * which loads a VST3/AU synth plugin. `setTrackInstrumentSampler` loads
+ * the built-in Tracktion sampler with N pre-rendered zones.
+ */
+interface InstrumentSampler {
+    /** Display name (e.g. "Bright Warm Pluck"). Used for diagnostics. */
+    name: string;
+    /** Disjoint zones, ordered low->high by rootKey. At least one required. */
+    zones: ReadonlyArray<InstrumentZone>;
+}
+/** Options for `host.listAudioFiles`. */
+interface ListAudioFilesOptions {
+    /**
+     * File extensions to include (dot-prefixed, lowercase). Defaults to
+     * `['.wav']`. Other audio formats (`.aif`, `.flac`, `.mp3`) are passed
+     * through verbatim; the host does not transcode.
+     */
+    extensions?: string[];
+    /** Walk subdirectories. Defaults to `false`. */
+    recursive?: boolean;
+}
 /** Describes an available instrument plugin (VST3/AU synth) on the system. */
 interface InstrumentDescriptor {
     /** Stable plugin identifier for loading (VST3 TUID or AU component ID) */
@@ -122,6 +183,33 @@ interface PluginUIProps {
     onOpenContract?: (() => void) | null;
     /** Callback to expand this plugin's own accordion section. */
     onExpandSelf?: (() => void) | null;
+    /**
+     * Whether the host's accordion section for this plugin is currently expanded.
+     * Plugin UIs can watch transitions to take focus, refresh data, etc. The host
+     * keeps the plugin mounted across collapse/expand to preserve state, so this
+     * prop (not mount/unmount) is the signal that the user is actively viewing.
+     */
+    isExpanded?: boolean;
+}
+/**
+ * Canonical display metadata for a distributable sample pack, sourced from the
+ * HOST's pack registry (the same source it uses to download + version-check the
+ * bundle). Returned by `host.getSamplePackInfo` so a plugin's download CTA can
+ * show the live name / description / size instead of a hardcoded copy that
+ * drifts when a new pack version ships. Structurally compatible with
+ * `SamplePackCardInfo` (the CTA card prop).
+ *
+ * @since SDK 2.12.0
+ */
+interface SamplePackPublicInfo {
+    /** Stable pack identifier, e.g. `'sas-instrument-pack'`. */
+    packId: string;
+    /** Human-readable pack name for the CTA headline. */
+    displayName: string;
+    /** One-line description of the pack's contents. */
+    description: string;
+    /** Size in bytes of the default download variant. */
+    sizeBytes: number;
 }
 /** Scoped API surface that plugins interact with. Plugins NEVER get direct TracktionEngine access. */
 interface PluginHost {
@@ -139,10 +227,24 @@ interface PluginHost {
     setTrackMute(trackId: string, muted: boolean): Promise<void>;
     /** Set track volume (linear 0.0 - 1.0). Only works on owned tracks. */
     setTrackVolume(trackId: string, volume: number): Promise<void>;
+    /**
+     * Set/replace a time-based volume automation curve (a fade envelope) on a track,
+     * or clear it with an empty array. Points are {time: seconds, db}; linear between
+     * points. Used by crossfade tracks to fade origin↔target across the looped
+     * transition. Optional — callers MUST null-check. @since SDK 2.25.0
+     */
+    setTrackVolumeAutomation?(trackId: string, points: Array<{
+        time: number;
+        db: number;
+    }>): Promise<void>;
     /** Set track pan (-1.0 left to 1.0 right). Only works on owned tracks. */
     setTrackPan(trackId: string, pan: number): Promise<void>;
     /** Set track solo state. Only works on owned tracks. */
     setTrackSolo(trackId: string, solo: boolean): Promise<void>;
+    /** Whether ANY track in the project is currently soloed (across all panels).
+     *  Lets a panel dim its non-soloed rows (the engine silences them via the
+     *  effective-mute model). Read-only; not ownership-scoped. */
+    isAnySoloActive(): Promise<boolean>;
     /** Rename a track. Only works on owned tracks. */
     setTrackName(trackId: string, name: string): Promise<void>;
     /**
@@ -160,9 +262,31 @@ interface PluginHost {
      */
     setTrackRole(trackId: string, role: string): Promise<void>;
     /** Shuffle preset: keep MIDI, apply a random preset from the same category. Only works on owned tracks. */
-    shufflePreset(trackId: string): Promise<ShufflePresetResult>;
+    /**
+     * Shuffle preset: keep MIDI, apply a random preset from the same category.
+     * `excludeNames` (since SDK 1.5.0) filters preset names out of the random
+     * 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>;
     /** Duplicate track: copy MIDI + role to a new track with a different preset. Only works on owned tracks. */
     duplicateTrack(trackId: string): Promise<PluginTrackHandle>;
+    /**
+     * Persist this plugin's track row order for the active scene. Pass the stable
+     * track dbIds ({@link PluginTrackHandle.dbId}) in the desired top-to-bottom
+     * order. Reload-safe — {@link getPluginTracks} returns tracks in this order
+     * across scene switches and project reopen.
+     *
+     * Per-panel and decoupled from the engine-synced global track order, so
+     * reordering one panel never disturbs other plugins' tracks. Tracks omitted
+     * from the list (e.g. newly added or duplicated) keep their natural order at
+     * the end. Pairs with the {@link useTrackReorder} hook, which drives the
+     * drag-and-drop UI and calls this on drop.
+     *
+     * @since SDK 2.16.0
+     */
+    reorderTracks(orderedTrackIds: readonly string[]): Promise<void>;
     /**
      * Return the canonical list of valid role tokens that the host's
      * classifier and UI understand. Plugins should use this list when
@@ -208,6 +332,18 @@ interface PluginHost {
      * Wraps MidiProcessor: quantize -> swing -> scale -> register -> overlaps -> humanize.
      */
     postProcessMidi(notes: PluginMidiNote[], options: PostProcessOptions): Promise<PluginMidiNote[]>;
+    /**
+     * Read a track's current MIDI notes for in-place editing (e.g. a piano
+     * roll). Returns the track's clips with beat-based notes; an empty `clips`
+     * array means the track has no MIDI. Reads LIVE engine state (NOT the DB),
+     * so it reflects unsaved generator output too and needs no project_id
+     * scoping — do not "fix" this into a DB query.
+     *
+     * Ownership-gated like {@link writeMidiClip}. Optional so a plugin built
+     * against this SDK still loads on an older host — callers MUST null-check.
+     * @since SDK 2.15.0
+     */
+    readMidiNotes?(trackId: string): Promise<ReadMidiResult>;
     /** Place an audio file on a track this plugin owns. */
     writeAudioClip(trackId: string, filePath: string, position?: number): Promise<void>;
     /**
@@ -237,6 +373,16 @@ interface PluginHost {
     setPluginState(trackId: string, pluginIndex: number, stateBase64: string): Promise<void>;
     /** Get current plugin state (base64-encoded). */
     getPluginState(trackId: string, pluginIndex: number): Promise<string>;
+    /**
+     * Set a plugin's RAW VST3/AU state — the plugin's own getStateInformation
+     * format, bypassing Tracktion's ValueTree wrapper. Use for third-party
+     * instruments (u-he Diva, Serum, …) whose patches the ValueTree round-trip
+     * does not faithfully preserve. Default Surge XT presets use setPluginState.
+     * @since SDK 2.15.0
+     */
+    setRawPluginState(trackId: string, pluginIndex: number, stateBase64: string): Promise<void>;
+    /** Get a plugin's RAW VST3/AU state (see setRawPluginState). @since SDK 2.15.0 */
+    getRawPluginState(trackId: string, pluginIndex: number): Promise<string>;
     /** List plugins currently loaded on a track. */
     getTrackPlugins(trackId: string): Promise<PluginSynthInfo[]>;
     /** Remove a plugin from a track. */
@@ -253,14 +399,154 @@ interface PluginHost {
     showInstrumentEditor(trackId: string): Promise<void>;
     /** Close the instrument plugin's editor window. */
     hideInstrumentEditor(trackId: string): Promise<void>;
+    /**
+     * Load the engine's built-in sampler on the track (if not already
+     * present) and configure it with a single one-shot sound. Every MIDI
+     * note triggers the loaded sample regardless of pitch — used by the
+     * drum-generator plugin where the LLM's emitted pitch is advisory.
+     *
+     * Idempotent: calling repeatedly on the same track swaps the loaded
+     * sample without stacking more sampler instances. The sampler counts
+     * as the track's instrument; mixing it with `setTrackInstrument` on
+     * the same track is undefined behaviour for now.
+     *
+     * @since SDK 1.2.0
+     */
+    setTrackDrumKit(trackId: string, kit: DrumKit): Promise<void>;
+    /**
+     * Load the engine's built-in sampler on the track (if not already
+     * present) and configure it with a pitched, polyphonic, multi-zone
+     * instrument. Each MIDI note triggers the zone whose [minKey,maxKey]
+     * range contains it; the zone is played back pitch-shifted relative
+     * to its rootKey. Polyphony is handled by the Tracktion sampler's
+     * voice allocator.
+     *
+     * Used by the instrument-generator plugin to load a pre-rendered
+     * pitched-sample manifest. Mutually exclusive with `setTrackDrumKit`
+     * on the same track (both occupy the sampler slot) and with
+     * `setTrackInstrument(pluginId)` (which loads a VST synth instead).
+     *
+     * Idempotent: calling repeatedly on the same track swaps the loaded
+     * zones without stacking sampler instances.
+     *
+     * @since SDK 1.3.0
+     */
+    setTrackInstrumentSampler(trackId: string, instrument: InstrumentSampler): Promise<void>;
+    /**
+     * List audio files (by default `.wav`) under `rootPath`. Returns
+     * absolute file paths. `recursive` defaults to false; pass `true` to
+     * walk subdirectories. The drum-generator plugin uses this to
+     * lazily discover available samples without round-tripping each
+     * folder through `getSamples`.
+     *
+     * Plugins MUST NOT use this to read paths outside their declared
+     * sample roots — the host may add path validation in a later release.
+     *
+     * @since SDK 1.2.0
+     */
+    listAudioFiles(rootPath: string, options?: ListAudioFilesOptions): Promise<string[]>;
+    /**
+     * Read a text file's contents from the host filesystem (UTF-8). Returns
+     * `null` on any read error (missing file, permission, etc.) — the
+     * caller does not need to wrap the call in try/catch.
+     *
+     * Intended for plugin sample-library metadata: instrument manifest
+     * JSON (`<instrument-id>/manifest.json`) and prompt-sibling text
+     * (`<id>.txt`). Plugins parse the returned string themselves so the
+     * host stays content-agnostic.
+     *
+     * Plugins MUST NOT use this to read paths outside their declared
+     * sample roots — the host may add path validation in a later release.
+     *
+     * @since SDK 1.4.0
+     */
+    readTextFile(absolutePath: string): Promise<string | null>;
     /** Get the FULL generation context for the active scene. */
     getGenerationContext(excludeTrackId?: string): Promise<PluginGenerationContext>;
     /** Get lightweight musical context (no concurrent track MIDI data). */
     getMusicalContext(): Promise<MusicalContext>;
     /** Get the active scene ID. Null if no scene is active. */
     getActiveSceneId(): string | null;
+    /**
+     * Get the bound project's DB id. Null when no project is bound.
+     * Optional — older hosts and the renderer-side host proxy may omit it;
+     * callers MUST feature-check. Used e.g. to detect project switches for
+     * per-project conversation persistence.
+     * @since SDK 2.18.0
+     */
+    getProjectId?(): string | null;
     /** Get list of all scenes in the project. */
     getSceneList(): Promise<PluginSceneInfo[]>;
+    /**
+     * Enumerate importable track candidates from OTHER scenes, scoped to this
+     * plugin's track type (derived from the plugin id). Each candidate is
+     * annotated with `importable` + `disabledReason` — the host computes the
+     * harmonic/length/tempo gate so the UI only renders it. By default the active
+     * scene is excluded; pass `includeSameScene` to also surface the active
+     * scene's MIDI tracks owned by OTHER panels (the cross-panel re-sound source).
+     * Scenes with no candidate of this type are omitted.
+     *
+     * Optional so a plugin built against this SDK still loads on an older host —
+     * callers MUST null-check and hide the affordance when absent.
+     * @since SDK 2.13.0
+     */
+    listImportableTracks?(opts?: ListImportableTracksOptions): Promise<ImportCandidateScene[]>;
+    /**
+     * Import a source track (from another scene) into the active scene as a
+     * faithful, independent copy, delegating to the `import_track_from_scene`
+     * tool. Returns the new track's handle so the panel can append a row.
+     * Throws on a gate violation — call only for candidates with `importable`.
+     * Optional — callers MUST null-check (see `listImportableTracks`).
+     * @since SDK 2.13.0
+     */
+    importTrack?(opts: {
+        sourceSceneId: string;
+        sourceTrackId: string;
+    }): Promise<PluginTrackHandle>;
+    /**
+     * Read a source track's CURRENT sound — sample path (drums), sampler zones
+     * (instruments), or Surge preset state (synths) — so a panel can copy just
+     * the sound onto another track, IGNORING the contract gate that `importTrack`
+     * enforces ("different contract, same preset"). Read-only: applies nothing.
+     * The selector is the source track's DB row id (`ImportCandidateTrack.dbId`).
+     * Returns null when the track has no stored sound. Optional — callers MUST
+     * null-check (see `listImportableTracks`).
+     * @since SDK 2.14.0
+     */
+    getTrackSound?(sourceTrackDbId: string): Promise<TrackSoundSnapshot | null>;
+    /**
+     * Read a source track's persisted MIDI by its DB row id — the cross-panel
+     * READ half of "re-sound a part on a different instrument". Unlike
+     * `readMidiNotes` (engine-read, ownership-gated), this reads the DB and is
+     * NOT ownership-gated, so a panel can pull a part out of a track owned by a
+     * DIFFERENT panel in the same scene (the selector is
+     * `ImportCandidateTrack.dbId`, e.g. a `sameScene` candidate). Notes are
+     * beat-based, identical shape to `readMidiNotes`; the loop span comes from the
+     * source scene. Returns `{ clips: [] }` when the track has no MIDI. Optional —
+     * callers MUST null-check (see `listImportableTracks`).
+     * @since SDK 2.20.0
+     */
+    readImportableTrackMidi?(sourceTrackDbId: string): Promise<ReadMidiResult>;
+    /**
+     * List THIS panel's family tracks in a specific scene (by DB id), WITHOUT the
+     * import key/length/tempo gate that `listImportableTracks` applies. Powers the
+     * crossfade picker: the origin (from) and target (to) scenes of a transition
+     * deliberately differ in key, so gating would wrongly hide valid candidates.
+     * Project-scoped, read-only. Returns [] for an unknown/empty scene. Optional —
+     * callers MUST null-check (see `listImportableTracks`).
+     * @since SDK 2.22.0
+     */
+    listSceneFamilyTracks?(sceneDbId: string): Promise<SceneFamilyTrack[]>;
+    /**
+     * Read a specific scene's musical key (tonic + mode) by db id. Labels the
+     * SOURCE keys of a crossfade's origin/target patterns — the active-scene
+     * musical context only carries the transition scene's key. Optional — callers
+     * MUST null-check. @since SDK 2.24.0
+     */
+    getSceneKey?(sceneDbId: string): Promise<{
+        key: string;
+        mode: string;
+    } | null>;
     /** Subscribe to transport state changes. Returns unsubscribe function. */
     onTransportEvent(listener: TransportEventListener): UnsubscribeFn;
     /** Subscribe to deck boundary events. Returns unsubscribe function. */
@@ -269,8 +555,59 @@ interface PluginHost {
     onSceneChange(listener: SceneChangeListener): UnsubscribeFn;
     /** Get current transport state (one-shot). */
     getTransportState(): Promise<PluginTransportState>;
+    /**
+     * One-shot mono peak level for every track this plugin owns. Drives the
+     * cosmetic per-track strip meters; poll at ~30Hz while the transport is
+     * playing. The host scopes the result to this plugin's tracks and coalesces
+     * the underlying engine read, so a busy engine yields a STALE meter rather
+     * than a backlog (playback always wins over the GUI). Optional: guard with
+     * `typeof host.getTrackLevels === 'function'` for older hosts.
+     * @since SDK 2.21.0
+     */
+    getTrackLevels?(): Promise<PluginTrackLevel[]>;
     /** Generate text/JSON via the host's authenticated LLM service. */
     generateWithLLM(request: LLMGenerationRequest): Promise<LLMGenerationResult>;
+    /**
+     * Generate with native tool-use (function calling). Used by agentic plugins
+     * (chat panel, etc.) to drive an iterative loop where the model calls tools,
+     * observes results, and decides next steps — same loop class as Claude Code
+     * or VS Code agent mode.
+     *
+     * Shape mirrors Gemini's `generateContent` REST surface; the host forwards
+     * verbatim to the gateway's Gemini-native passthrough endpoint, which adds
+     * the central Google API key. Plugins never see provider credentials.
+     *
+     * Available since SDK 2.4.0.
+     */
+    generateWithLLMTools(request: LLMToolUseRequest): Promise<LLMToolUseResponse>;
+    /**
+     * Resolve absolute paths for spawning the bundled `sas` CLI as a subprocess.
+     * Used by agentic plugins that drive the CLI as their tool surface (chat
+     * panel, etc.). Returns `null` when called from a renderer-side host or
+     * when the CLI isn't accessible.
+     *
+     * Available since SDK 2.4.0.
+     */
+    getCliPaths(): {
+        appExe: string;
+        cliEntry: string;
+    } | null;
+    /**
+     * Resolve the absolute path to a bundled resource directory shipped with
+     * the app via `extraResources` (e.g. `'drum-samples'`,
+     * `'tracktion-presets'`). In dev, resolves to
+     * `<projectRoot>/resources/<name>`. In packaged builds, resolves to
+     * `<process.resourcesPath>/<name>`.
+     *
+     * Returns `null` if the host cannot resolve paths in this context
+     * (e.g. Electron mocked out in unit tests). Plugins MUST null-check and
+     * either degrade gracefully or fall back to a known dev path.
+     *
+     * Async by design: the renderer-side host proxy round-trips through IPC.
+     *
+     * @since SDK 2.7.0
+     */
+    getBundledResourcePath(name: string): Promise<string | null>;
     /** Check if LLM access is available (user authenticated + gateway reachable). */
     isLLMAvailable(): Promise<boolean>;
     /**
@@ -281,23 +618,59 @@ interface PluginHost {
      * `'scene'` to hide project-level tools they shouldn't call. When omitted,
      * every tool regardless of scope is returned.
      *
+     * `opts.includeDeferred` (since SDK 2.18.0) opts in to tools flagged with
+     * `deferLoading` (progressive disclosure). Default `false` mirrors
+     * `/api/v1/actions` — the curated core surface. Used by curation layers
+     * that promote specific deferred/project tools onto an agent's default
+     * declaration set.
+     *
      * @since SDK 1.2.0
      */
     listAppTools(opts?: {
         scope?: 'scene' | 'project';
+        includeDeferred?: boolean;
     }): Promise<PluginAppTool[]>;
     /**
      * Execute a host app tool by name. Delegates to the in-process
-     * ToolRegistry — every mutation broadcasts to the UI automatically.
+     * ToolRegistry — every call (including this one) broadcasts to the
+     * UI's `mutations:tool-executed` channel so renderer state stays
+     * fresh whether the call mutates or is read-only. Read-only callers
+     * pay zero extra cost since the renderer debounces and skips
+     * redundant reloads.
      *
      * For scene-scoped tools tagged with `autoBindSceneId`, the host
      * overrides the caller's `sceneId` param with the currently-active
      * scene. That keeps a scene-bound caller from accidentally targeting
      * another scene.
      *
+     * `opts.provenance` (since SDK 2.18.0) stamps the originating actor onto
+     * every domain event this call emits — pass `'agent'` from autonomous
+     * agent loops so the UI orchestrator can gate auto-navigation, `'user'`
+     * when proxying a direct user gesture. Omitted = `'system'`.
+     *
      * @since SDK 1.2.0
      */
-    executeAppTool(name: string, params: Record<string, unknown>): Promise<PluginAppToolResult>;
+    executeAppTool(name: string, params: Record<string, unknown>, opts?: {
+        provenance?: 'agent' | 'user';
+    }): Promise<PluginAppToolResult>;
+    /**
+     * Monotonic counter that increments on every state mutation
+     * (`broadcastMutation('tool-executed', ...)`). Use as a cache key for
+     * derived state that depends on the project: when the counter changes,
+     * something mutated; when it doesn't, your cache is still valid.
+     *
+     * Mostly aimed at performance-sensitive callers like ambient-context
+     * builders that want to skip re-querying state when nothing has
+     * changed. The counter is process-local — it resets on app restart
+     * and is not durable across sessions.
+     *
+     * Implementation detail: the counter is bumped by `mutation-broadcaster`
+     * before the broadcaster fires, so a synchronous `getMutationSeq()`
+     * call from inside a mutation listener will see the post-bump value.
+     *
+     * @since SDK 2.6.0
+     */
+    getMutationSeq(): number;
     /** Get available preset categories for a synth plugin. */
     getPresetCategories(pluginName: string): Promise<string[]>;
     /** Get a random preset from a category. */
@@ -310,6 +683,150 @@ interface PluginHost {
     getDataDirectory(): string;
     /** Persisted key-value settings store. */
     settings: PluginSettingsStore;
+    /**
+     * Return the absolute path to an installed sample pack's root directory,
+     * or `null` if the pack is missing OR its installed version doesn't match
+     * what the current app build expects.
+     *
+     * Plugins should treat `null` as "show the download CTA"; do NOT fall back
+     * to a hardcoded path. The host owns where samples live (currently
+     * `<userData>/samples/<installSubdir>/`).
+     *
+     * Stable packIds: `'sas-drum-pack'`, `'sas-instrument-pack'`. Both packs
+     * are downloaded on demand via the host's pack-download flow; see
+     * `host.isSamplePackCurrent` and the renderer-side `DownloadPackButton`.
+     *
+     * @since SDK 2.7.0
+     */
+    getSamplePackRoot(packId: string): Promise<string | null>;
+    /**
+     * True if the installed version of `packId` matches the version this app
+     * build expects. False if the pack is missing OR the installed version
+     * differs (older or newer).
+     *
+     * Plugins call this on activate to decide between rendering their normal
+     * UI vs the "Sample library not installed / Update available" CTA.
+     *
+     * @since SDK 2.7.0
+     */
+    isSamplePackCurrent(packId: string): Promise<boolean>;
+    /**
+     * Return the currently-installed version string for `packId` (e.g. `'1'`,
+     * `'2'`), or `null` if the pack is not installed at all. Reads the
+     * `_pack-version.json` marker inside the pack's install dir.
+     *
+     * Useful for distinguishing the "missing" CTA from the "stale, update
+     * available" CTA — plugins can call this when `isSamplePackCurrent`
+     * returns false to pick the right empty-state message.
+     *
+     * @since SDK 2.7.0
+     */
+    getSamplePackInstalledVersion(packId: string): Promise<string | null>;
+    /**
+     * Trigger a download + install of `packId` via the host's pack system (the
+     * same flow `getSamplePackRoot` / `isSamplePackCurrent` report on). Resolves
+     * when the install completes or fails. Plugins call this from a "download
+     * library" CTA instead of reaching into the app's IPC (`window.electronAPI`)
+     * directly.
+     *
+     * @since SDK 2.8.0
+     */
+    startSamplePackDownload(packId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Subscribe to download/install progress for `packId`. Returns an unsubscribe
+     * fn. `status` mirrors the host's pack-download states (e.g. `'downloading' |
+     * 'extracting' | 'installing' | 'complete' | 'error'`); `progress` is 0-100.
+     *
+     * @since SDK 2.8.0
+     */
+    onSamplePackProgress(packId: string, listener: (progress: {
+        packId?: string;
+        status: string;
+        progress: number;
+        message?: string;
+    }) => void): UnsubscribeFn;
+    /**
+     * Return the canonical display metadata (`displayName`, `description`,
+     * `sizeBytes`) for `packId` from the host's pack registry — the SAME source
+     * the host uses to download + version-check the pack. A plugin's download CTA
+     * should prefer this over a hardcoded copy so the size/description stay in
+     * sync with whatever bundle the host actually ships (no per-version drift).
+     * Resolves `null` for an unknown packId.
+     *
+     * Optional so a plugin built against this SDK still runs on an older host:
+     * callers should fall back to their own static copy when it is absent or
+     * returns `null`.
+     *
+     * @since SDK 2.12.0
+     */
+    getSamplePackInfo?(packId: string): Promise<SamplePackPublicInfo | null>;
+    /**
+     * Per-pack roots of the USER's imported sample packs for `kind`. Each root
+     * is laid out exactly like the corresponding stock pack (drums:
+     * `<root>/<role>/<file>.wav` + `.txt` sidecars; instruments:
+     * `<root>/<category>/<id>/manifest.json`), so resolvers scan them as
+     * additional roots alongside `getSamplePackRoot`. `[]` when nothing is
+     * imported. User content lives under `<userData>/user-samples/` — strictly
+     * separate on disk; stock pack installs never touch it.
+     *
+     * Optional for older-host compat: feature-check
+     * (`host.getUserSampleRoots?.(...)`) and treat absence as `[]`.
+     *
+     * @since SDK 2.20.0
+     */
+    getUserSampleRoots?(kind: 'drums' | 'instruments'): Promise<string[]>;
+    /**
+     * Ask the host app to open its sample-import wizard targeting `kind`.
+     * Fire-and-forget; renderer-hosted plugins only (the wizard is an app-level
+     * modal — the main-process host no-ops). Library changes land as
+     * `onSamplePackProgress` events with packId `user:<kind>` and
+     * `status: 'complete'`, so subscribe to that to refresh.
+     *
+     * @since SDK 2.20.0
+     */
+    openSampleImportWizard?(kind: 'drums' | 'instruments'): void;
+    /**
+     * Start a deck playing the given scene/transition. Mirrors the workstation's
+     * transport play. `contentType` defaults to `'scene'`.
+     *
+     * @since SDK 2.9.0
+     */
+    deckPlay(deckId: string, contentId?: string, contentType?: 'scene' | 'transition'): Promise<{
+        success: boolean;
+        error?: string;
+        code?: string;
+    }>;
+    /**
+     * Stop a deck.
+     *
+     * @since SDK 2.9.0
+     */
+    deckStop(deckId: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Subscribe to per-deck state changes. Each event carries the `deckId`, the
+     * `property` that changed (e.g. `'playing'`), and its new `value`. Returns an
+     * unsubscribe fn.
+     *
+     * @since SDK 2.9.0
+     */
+    onDeckStateChanged(listener: (event: {
+        deckId: string;
+        property: string;
+        value: unknown;
+    }) => void): UnsubscribeFn;
+    /**
+     * Subscribe to the "all decks stopped" engine event (e.g. global transport
+     * stop). Returns an unsubscribe fn.
+     *
+     * @since SDK 2.9.0
+     */
+    onAllDecksStopped(listener: () => void): UnsubscribeFn;
     /** Get a value from scene-scoped plugin data. */
     getSceneData<T = unknown>(sceneId: string, key: string): Promise<T | null>;
     /** Set a value in scene-scoped plugin data. */
@@ -449,6 +966,18 @@ interface PluginHost {
     onComposeProgress(listener: ComposeProgressListener): UnsubscribeFn;
     /** Subscribe to engine ready events (fires when the engine finishes loading tracks after a scene change). */
     onEngineReady(listener: () => void): UnsubscribeFn;
+    /**
+     * Subscribe to external state mutations (CLI, MCP, or HTTP-API tool calls
+     * that bypass plugin-host methods). Fires after such a tool finishes,
+     * signalling that scene/track DB state may have changed underneath the
+     * plugin's local cache. Use it to refresh state that the plugin doesn't
+     * own — e.g. re-running adoptSceneTracks() so AI-created tracks become
+     * visible without requiring the user to switch scenes.
+     *
+     * Optional: only the renderer-side host implements this. Main-side
+     * plugins should subscribe to the typed domain-event bus instead.
+     */
+    onAfterAgentMutation?(listener: () => void): UnsubscribeFn;
     /** Audition a single note on a track (fire-and-forget preview). */
     auditionNote(trackId: string, pitch: number, velocity: number, durationMs: number): Promise<void>;
     /** Get presets for this plugin, optionally filtered by category. */
@@ -539,6 +1068,14 @@ interface PluginHost {
      * @since SDK 2.2.0
      */
     getCurrentInputDevice(): Promise<AudioInputDevice | null>;
+    /**
+     * Subscribe to input-device changes (user picks a new mic in the
+     * Audio Routing panel). Listeners should refetch via
+     * `getCurrentInputDevice()`. Returns an unsubscribe fn.
+     *
+     * @since SDK 2.4.0
+     */
+    onInputDeviceChange(listener: () => void): UnsubscribeFn;
     /**
      * Get the platform's mic-to-output round-trip latency offset in
      * samples. 0 = uncalibrated. Plugins recording audio apply this via
@@ -623,6 +1160,105 @@ interface PluginTrackHandle {
     /** Custom instrument display name (null = Surge XT) */
     instrumentName?: string | null;
 }
+/**
+ * One source track offered by `listImportableTracks`, already filtered to the
+ * calling panel's type. The host computes the gate; the UI only renders it.
+ * @since SDK 2.13.0
+ */
+interface ImportCandidateTrack {
+    /** Source track's engine track id (the selector passed back to importTrack). */
+    trackId: string;
+    /** Source track's DB row id (globally unique; good React key). */
+    dbId: string;
+    /** Display name shown in the modal row. */
+    name: string;
+    /** Musical role if set (drives the row icon). */
+    role?: string;
+    /** True when this track can be copied into the active scene as-is. */
+    importable: boolean;
+    /** Why the track is disabled (shown as a tooltip). Present iff `!importable`. */
+    disabledReason?: string;
+}
+/**
+ * One track in a specific scene, returned by `host.listSceneFamilyTracks`,
+ * already narrowed to the calling panel's family. Unlike `ImportCandidateTrack`
+ * it carries NO import gate — the crossfade picker lists every same-family track
+ * in the origin/target scene regardless of key/length. @since SDK 2.22.0
+ */
+interface SceneFamilyTrack {
+    /** Track's DB row id — the selector for getTrackSound + crossfade metadata. */
+    dbId: string;
+    /** Display name shown in the picker. */
+    name: string;
+    /** Musical role if set — used to enforce same-role crossfade pairing. */
+    role?: string;
+}
+/**
+ * One OTHER scene and its candidate tracks (already type-filtered). Scenes with
+ * zero candidates of the panel's type are omitted by the host.
+ * @since SDK 2.13.0
+ */
+interface ImportCandidateScene {
+    /** Source scene's engine scene id. */
+    sceneId: string;
+    /** Source scene's display name. */
+    sceneName: string;
+    /** Candidate tracks of this panel's type (may include disabled ones). */
+    tracks: ImportCandidateTrack[];
+    /**
+     * True for the synthetic "this scene — other panels" entry: the ACTIVE
+     * scene's MIDI tracks owned by OTHER panels. Importing one re-sounds the part
+     * on the calling panel's instrument (via `readImportableTrackMidi` +
+     * `writeMidiClip`) rather than faithfully copying it. Absent/false for
+     * ordinary cross-scene entries. @since SDK 2.20.0
+     */
+    sameScene?: boolean;
+}
+/**
+ * A source track's current sound, as returned by `host.getTrackSound`. The
+ * discriminant matches the panel that reads it: drums → 'sample', instruments →
+ * 'instrument', synths → 'preset'. `label` is the human name for the History row.
+ * @since SDK 2.14.0
+ */
+/**
+ * How a synth `state` blob is serialized. `valuetree` is Tracktion's wrapped
+ * format (default Surge XT presets); `raw` is the plugin's own
+ * getStateInformation format (third-party instruments). Absent ⇒ `valuetree`,
+ * for backward compatibility with history recorded before SDK 2.15.0.
+ * @since SDK 2.15.0
+ */
+type SynthStateType = 'raw' | 'valuetree';
+type TrackSoundSnapshot = {
+    kind: 'sample';
+    samplePath: string;
+    label: string;
+} | {
+    kind: 'instrument';
+    displayName: string;
+    instrumentId: string | null;
+    zones: InstrumentZone[];
+    label: string;
+} | {
+    kind: 'preset';
+    state: string;
+    label: string;
+    stateType?: SynthStateType;
+};
+/** Options for `PluginHost.listImportableTracks`. @since SDK 2.13.0 */
+interface ListImportableTracksOptions {
+    /**
+     * Coarse content family. 'midi' = synth/drum/instrument, 'audio' = stems,
+     * 'sample' = loops. Defaults are derived from the calling plugin id, so
+     * panels normally pass nothing.
+     */
+    family?: 'midi' | 'audio' | 'sample';
+    /**
+     * When true, prepend the active scene's MIDI tracks owned by OTHER panels as a
+     * `sameScene` entry (the cross-panel re-sound source). Off by default so the
+     * plain cross-scene import is unchanged. MIDI panels only. @since SDK 2.20.0
+     */
+    includeSameScene?: boolean;
+}
 interface PluginTrackInfo extends PluginTrackHandle {
     /** Is track muted? */
     muted: boolean;
@@ -691,6 +1327,29 @@ interface MidiWriteResult {
     /** Actual bars covered */
     bars: number;
 }
+/**
+ * One clip returned by {@link PluginHost.readMidiNotes}. `endTime - startTime`
+ * (seconds) is the clip's loop span; round-trip it back into
+ * {@link MidiClipData} on save so an edit never changes the clip length.
+ * @since SDK 2.15.0
+ */
+interface ReadMidiClip {
+    /** Clip start in seconds (engine timeline). */
+    startTime: number;
+    /** Clip end in seconds. Loop span = endTime - startTime. */
+    endTime: number;
+    /** Beat-based notes, identical shape to {@link MidiClipData.notes}. */
+    notes: PluginMidiNote[];
+}
+/**
+ * Result of {@link PluginHost.readMidiNotes}: every clip on the track. Drum /
+ * instrument / synth tracks are single-clip, so callers normally use
+ * `clips[0]`; the array form mirrors the engine and is future-proof.
+ * @since SDK 2.15.0
+ */
+interface ReadMidiResult {
+    clips: ReadMidiClip[];
+}
 /**
  * Options for {@link PluginHost.exportTracksAsMidiBundle}.
  * @since SDK 1.1.0
@@ -805,6 +1464,15 @@ interface MusicalContext {
     genre: string | null;
     timeSignature: string;
     chordProgression: PluginChordTiming[];
+    /**
+     * The scene's natural-language contract prompt (e.g. "dark psytrance,
+     * driving 130 BPM, claustrophobic"). Null when the scene has no
+     * contract set yet. Auto-prefixed to the LLM by `host.generateWithLLM`
+     * so every per-track generation sees the scene-level intent without
+     * each plugin having to plumb it through manually.
+     * @since SDK 1.2.0
+     */
+    contractPrompt: string | null;
 }
 interface PluginChordTiming {
     /** Chord symbol: 'Cm7', 'G', 'Fmaj7', etc. */
@@ -825,6 +1493,15 @@ interface PluginGenerationContext {
         genre: string | null;
     };
     concurrentTracks: PluginConcurrentTrackInfo[];
+    /**
+     * Count of tracks the host had to drop entirely from `concurrentTracks`
+     * because their notes pushed the running total past the cross-track
+     * budget. Panels should disclose this to the LLM (e.g. "… N additional
+     * tracks omitted to fit token budget") so the model knows it is
+     * working with partial context.
+     * @since SDK 1.2.0
+     */
+    truncatedTrackCount?: number;
 }
 interface PluginConcurrentTrackInfo {
     trackId: string;
@@ -832,6 +1509,22 @@ interface PluginConcurrentTrackInfo {
     presetCategory: string | null;
     /** Notes organized by which chord they fall under */
     notesByChord: PluginChordSegment[];
+    /**
+     * The user-typed prompt that produced this track's MIDI (from
+     * `tracks.prompt`). Lets the LLM see *intent* alongside the notes —
+     * "punchy 909 kick" carries more meaning than the kick MIDI alone.
+     * @since SDK 1.2.0
+     */
+    prompt?: string;
+    /**
+     * True when the host capped this track's notes (per-track budget).
+     * The `notesByChord` payload is a prefix of the real content; the
+     * total dropped count is `originalNoteCount - sum(notesByChord.notes.length)`.
+     * @since SDK 1.2.0
+     */
+    truncated?: boolean;
+    /** The track's full note count before per-track truncation. */
+    originalNoteCount?: number;
 }
 interface PluginChordSegment {
     chord: string;
@@ -871,6 +1564,20 @@ interface PluginTransportState {
     position: number;
     timeSignature: string;
 }
+/**
+ * Mono peak level for a single track, as reported by `getTrackLevels()`.
+ * Drives the cosmetic per-track strip meters. `peakDb` is the max of the
+ * L/R channels, floored at -120 (the "no signal" sentinel).
+ * @since SDK 2.21.0
+ */
+interface PluginTrackLevel {
+    /** Tracktion engine track id — matches `PluginTrackHandle.id`. */
+    trackId: string;
+    /** Mono peak in dBFS (max of L/R), floored at -120. */
+    peakDb: number;
+    /** Latched overload since the last poll. */
+    clipped: boolean;
+}
 interface PluginSceneInfo {
     id: string;
     name: string;
@@ -899,6 +1606,17 @@ interface PluginSceneContext {
     hasTracks: boolean;
     /** Whether bulk generation is currently in progress */
     isBulkGenerating: boolean;
+    /**
+     * Scene kind. A 'transition' scene bridges two other scenes (the
+     * transition-as-scene feature) and unlocks the crossfade-track UI in the
+     * instrument panels; ordinary scenes are 'scene'. Absent on older hosts.
+     * @since SDK 2.22.0
+     */
+    sceneType?: 'scene' | 'transition';
+    /** For a transition scene, the DB id of the scene it bridges FROM (origin). Null otherwise. @since SDK 2.22.0 */
+    transitionFromSceneId?: string | null;
+    /** For a transition scene, the DB id of the scene it bridges TO (target). Null otherwise. @since SDK 2.22.0 */
+    transitionToSceneId?: string | null;
 }
 /** Placeholder track state for the progressive bulk-add UX */
 interface BulkAddPlaceholderTrack {
@@ -937,6 +1655,90 @@ interface LLMGenerationResult {
     /** Model that generated the response */
     model: string;
 }
+/** A single part of a Gemini-style content block. */
+interface LLMPart {
+    /** Plain text. Mutually exclusive with functionCall / functionResponse. */
+    text?: string;
+    /** A tool/function the model is asking the host to invoke. */
+    functionCall?: {
+        name: string;
+        args: Record<string, unknown>;
+        /**
+         * Opaque signature returned by Gemini 3+ tool-use models. Must be echoed
+         * verbatim when the assistant turn is replayed on a later iteration, or
+         * the API rejects the request with a 400 ("Function call is missing a
+         * thought_signature in functionCall parts."). Pre-Gemini-3 models leave
+         * this undefined; preserving it round-trip is safe across families.
+         */
+        thoughtSignature?: string;
+    };
+    /** The result of a tool call, fed back into the loop on the next turn. */
+    functionResponse?: {
+        name: string;
+        response: Record<string, unknown>;
+    };
+}
+interface LLMContent {
+    /** 'user' = user/tool-result; 'model' = assistant. */
+    role: 'user' | 'model';
+    parts: LLMPart[];
+}
+interface LLMFunctionDeclaration {
+    name: string;
+    description: string;
+    /** JSON Schema. Use `type: 'object'` with `properties` for any tool. */
+    parameters: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+}
+interface LLMTool {
+    functionDeclarations: LLMFunctionDeclaration[];
+}
+interface LLMGenerationConfig {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    maxOutputTokens?: number;
+}
+interface LLMSystemInstruction {
+    parts: {
+        text: string;
+    }[];
+}
+interface LLMToolUseRequest {
+    /** Gemini model id (e.g. 'gemini-2.5-flash'). */
+    model: string;
+    /** Conversation so far, including any tool-result turns. */
+    contents: LLMContent[];
+    /** System prompt as Gemini-native systemInstruction. */
+    systemInstruction?: LLMSystemInstruction;
+    /** Tool declarations the model may call. */
+    tools?: LLMTool[];
+    /** Optional tool-call mode override. */
+    toolConfig?: {
+        functionCallingConfig?: {
+            mode?: 'AUTO' | 'ANY' | 'NONE';
+            allowedFunctionNames?: string[];
+        };
+    };
+    generationConfig?: LLMGenerationConfig;
+}
+interface LLMUsageMetadata {
+    promptTokenCount: number;
+    candidatesTokenCount: number;
+    totalTokenCount: number;
+}
+interface LLMCandidate {
+    content: LLMContent;
+    finishReason?: string;
+    index?: number;
+}
+interface LLMToolUseResponse {
+    candidates: LLMCandidate[];
+    usageMetadata?: LLMUsageMetadata;
+}
 interface PluginPresetData {
     name: string;
     category: string;
@@ -948,6 +1750,23 @@ interface ShufflePresetResult {
     presetName: string;
     presetCategory: string;
 }
+/**
+ * One entry in a track's in-session "sound history" — the data behind the
+ * TrackRow ↩ back-arrow and the drawer "History" tab (see `useSoundHistory`).
+ *
+ * `descriptor` is opaque to the SDK: each generator plugin defines its own shape
+ * (a drum sample path string, an instrument `{ displayName, zones }`, a synth
+ * `{ pluginIndex, stateBase64 }`) and is the value handed back to the plugin's
+ * `applySound` callback to re-apply the sound.
+ */
+interface SoundHistoryEntry {
+    /** Human-readable label shown in the History list (filename, preset/instrument name). */
+    label: string;
+    /** Opaque, plugin-defined value used to re-apply this sound. */
+    descriptor: unknown;
+    /** User-starred. Favorited entries are never auto-evicted by the history cap. */
+    favorite?: boolean;
+}
 interface PluginSettingsSchema {
     type: 'object';
     properties: Record<string, SettingDefinition>;
@@ -1170,7 +1989,7 @@ interface PluginAudioTextureResult {
      */
     cuePoints: PluginCuePoints | null;
     /**
-     * Path to the un-trimmed (raw) Lyria output. Used by the audio-texture
+     * Path to the un-trimmed (raw) Lyria output. Used by the stems
      * trim editor to draw the full waveform. Persist via
      * `host.setRawAudioFilePath`. Null when no raw file is available.
      */
@@ -1187,7 +2006,7 @@ interface PluginAudioTextureResult {
  * Cue-points sidecar surfaced by the audio-processor `trim` command —
  * sample positions for each detected beat inside the generated WAV.
  * Mirrors the canonical `CuePoints` shape from the assistant; duplicated
- * here so external plugins don't reach into sas-assistant internals.
+ * here so external plugins don't reach into sas-app internals.
  */
 interface PluginCuePoints {
     /** Schema version (currently 1). */
@@ -1266,6 +2085,14 @@ interface PluginAppTool {
     inputSchema: PluginAppToolInputSchema;
     /** `'scene'` = safe for scene-scoped callers. `'project'` = cross-scene. */
     scope?: 'scene' | 'project';
+    /**
+     * `true` = the operation cannot be undone via the host's checkpoint/undo
+     * system (project delete, disk overwrite, external export, …). The host
+     * gates such calls behind a user-approval flow when invoked with agent
+     * provenance; agent UIs may also surface the flag (e.g. ⚠ in a tool list).
+     * @since SDK 2.18.0
+     */
+    irreversible?: boolean;
 }
 /** Result shape returned by `PluginHost.executeAppTool`. */
 interface PluginAppToolResult {
@@ -1377,26 +2204,237 @@ interface FxPresetDataEntry {
 type FxPresetData = Partial<Record<FxCategory, FxPresetDataEntry>>;
 
 /**
- * SDK TrackRow — Reusable track row component for generator plugins.
+ * TrackDrawer — the unified per-track drawer body.
  *
- * Renders a complete track UI with prompt input, generation controls,
- * shuffle/copy, volume/pan, mute/solo, FX drawer, and visual states
- * (amber pulse for "needs generation", progress overlay, error indicator).
+ * ONE drawer with a flat contextual tab strip. Which tabs appear is computed
+ * from which callbacks the host panel provides:
+ *   - FX      (onFxToggle)     — the 6-category FX toggle bar
+ *   - Pick    (onSelect)       — instrument-plugin picker (+ native editor stage)
+ *   - History (onRestoreSound) — sounds this track has had (restore / favorite)
+ *   - Import  (onImportSound)  — copy a sound from a matching track in another scene
  *
- * Layout matches TrackInput (main branch) for visual parity.
+ * The active tab is CONTROLLED by the host (activeTab / onTabChange) so the
+ * track row's FX button and ▾ button can open the SAME drawer to a chosen tab.
+ * When only one tab is enabled (e.g. loops = FX only) the strip is hidden and
+ * that single view renders directly.
  *
- * Depends only on PluginHost types + existing shared renderer components.
+ * (Was `InstrumentDrawer` — renamed once it grew an FX tab + Import tab. A
+ * `TrackDrawer as InstrumentDrawer` alias is exported from the barrel for
+ * backwards compatibility.)
  */
 
-interface SDKTrackRowProps {
-    /** Track identity */
-    track: {
-        id: string;
-        name: string;
-        role?: string;
-    };
-    /** Current prompt text (optional — omit when using contentSlot) */
-    prompt?: string;
+/** The contextual tabs a track drawer can show, in display order. */
+type DrawerTab = 'fx' | 'pick' | 'history' | 'import' | 'edit';
+interface TrackDrawerProps {
+    /** Which tab is active (controlled by the host TrackRow). */
+    activeTab: DrawerTab;
+    /** Switch tabs (strip clicks). */
+    onTabChange?: (tab: DrawerTab) => void;
+    trackId: string;
+    fxState: TrackFxDetailState;
+    onFxToggle?: (category: FxCategory, enabled: boolean) => void;
+    onFxPresetChange?: (category: FxCategory, presetIndex: number) => void;
+    onFxDryWetChange?: (category: FxCategory, value: number) => void;
+    /** Disable FX controls (e.g. while the track is generating). */
+    fxDisabled?: boolean;
+    /** Available instrument plugins from engine scan. */
+    instruments?: InstrumentDescriptor[];
+    /** Currently loaded instrument plugin ID (null = default Surge XT). */
+    currentPluginId?: string | null;
+    /** Whether the instrument scan is still in progress. */
+    isLoading?: boolean;
+    /** Called when user selects an instrument (presence enables the Pick tab). */
+    onSelect?: (pluginId: string) => void;
+    /** Re-scan plugins. */
+    onRefresh?: () => void;
+    /** Pick-tab sub-view: show the native plugin editor instead of the grid. */
+    editorStage?: boolean;
+    /** Called when user clicks "Open Plugin Editor". */
+    onShowEditor?: () => void;
+    /** Called when user goes back from the editor to the instrument grid. */
+    onBackToInstruments?: () => void;
+    /** Name of the selected instrument (shown in the editor header). */
+    selectedInstrumentName?: string | null;
+    soundHistory?: readonly SoundHistoryEntry[];
+    soundHistoryCursor?: number;
+    /** Restore a sound by index; presence enables the History tab. */
+    onRestoreSound?: (index: number) => void;
+    /** Toggle the favorite (⭐) flag on a history entry; omit to hide the star. */
+    onToggleFavorite?: (index: number) => void;
+    /** Open the sound-import picker; presence enables the Import tab. */
+    onImportSound?: () => void;
+    /** Button label, e.g. "Import Sample" (drums/instruments) or "Import Preset" (synths). */
+    importSoundLabel?: string;
+    /** Current MIDI notes for the piano-roll editor. */
+    editNotes?: readonly PluginMidiNote[];
+    /** Persist edited notes; PRESENCE of this callback enables the Edit tab. */
+    onNotesChange?: (notes: PluginMidiNote[]) => void;
+    /** Scene length in bars (piano-roll grid width). Default 4. */
+    editBars?: number;
+    /** Scene BPM (piano-roll audition timing). Default 120. */
+    editBpm?: number;
+    /** Snap step in quarter notes for the piano roll (default 0.25). */
+    editSnap?: number;
+    /** 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;
+
+/**
+ * useTrackLevels — drives the cosmetic per-track strip meters.
+ *
+ * The hard constraint for this feature is "playback ALWAYS wins over the GUI;
+ * NO blocking threads." This hook is built around that:
+ *
+ *  - It polls `host.getTrackLevels()` at ~30Hz with a recursive setTimeout that
+ *    only schedules the NEXT tick AFTER the previous await resolves. That is
+ *    automatic backpressure: a slow/stalled engine simply slows the meter, it
+ *    can never queue a backlog of requests. (The host + bridge also coalesce,
+ *    so a busy engine yields a STALE snapshot, never a pile-up.)
+ *  - It writes into a ref-held Map and notifies row subscribers, so the OWNING
+ *    panel never re-renders at 30Hz. Each row reads its own value via
+ *    `useTrackLevel` and re-renders only itself.
+ *  - It polls while the panel is mounted and the window is visible, and pauses
+ *    when the window is hidden. It deliberately does NOT gate on transport
+ *    "is playing": this app drives playback through decks / the clip launcher,
+ *    and the linear-transport play flag does not track that reliably. When
+ *    audio is stopped the engine simply returns floor levels, so the bars are
+ *    empty anyway — no need (and no reliable signal) to stop polling.
+ *
+ * Usage (panel):
+ *   const levels = useTrackLevels(host);
+ *   ...<TrackRow levels={levels} ... />   // row calls useTrackLevel(levels, id)
+ */
+
+/**
+ * Stable handle returned by {@link useTrackLevels}. Rows read their own level
+ * and subscribe to per-tick notifications through it; its identity is stable
+ * across renders so a row's subscription is set up once.
+ */
+interface TrackLevelsHandle {
+    /** Current level for a track, or null when idle/absent (renders an empty bar). */
+    getLevel(trackId: string): PluginTrackLevel | null;
+    /** Subscribe to per-tick updates. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Poll every owned track's level while mounted + visible. Returns a stable
+ * handle; the owning component does NOT re-render per tick. Pass `enabled =
+ * false` to turn it off entirely (e.g. a panel that wants no meters). Safe to
+ * call even when the host predates `getTrackLevels` (older SDK) — it stays idle.
+ */
+declare function useTrackLevels(host: PluginHost | null | undefined, enabled?: boolean): TrackLevelsHandle;
+/**
+ * Per-row selector. Subscribes to the shared scheduler and re-renders ONLY the
+ * calling component when this track's level changes. Returns null when idle
+ * (transport stopped, window hidden, or the track has no meter yet).
+ */
+declare function useTrackLevel(handle: TrackLevelsHandle | null | undefined, trackId: string): PluginTrackLevel | null;
+/**
+ * Per-row meter view-model: the current level plus a held peak for the meter UI.
+ */
+interface TrackMeterView {
+    /** Current mono peak in dBFS (floored at -120). */
+    peakDb: number;
+    /** Held peak in dBFS — stays at the recent maximum for ~PEAK_HOLD_MS, then falls. */
+    peakHoldDb: number;
+    /** Latched clip flag for the last poll window. */
+    clipped: boolean;
+    /** True when the track currently has a live meter row. */
+    active: boolean;
+}
+/**
+ * Per-row meter selector WITH PEAK-HOLD. Like {@link useTrackLevel} it subscribes
+ * to the shared ~30Hz scheduler and re-renders only the calling component, but it
+ * also tracks a held peak that stays at the recent maximum for ~PEAK_HOLD_MS then
+ * decays — so the eye can register where the signal peaked while the bar itself
+ * moves fast. No extra timers or rAF: the held value is recomputed on each
+ * scheduler notify, using performance.now() for hold/decay timing.
+ */
+declare function useTrackMeter(handle: TrackLevelsHandle | null | undefined, trackId: string): TrackMeterView;
+/**
+ * Track the transport's play/stop state for a plugin. Seeds from
+ * `getTransportState()` and follows `onTransportEvent`. Use its result as the
+ * `active` arg to {@link useTrackLevels} so meters animate only during playback.
+ */
+declare function useTransportPlaying(host: PluginHost | null | undefined): boolean;
+
+/**
+ * Props the reorder machinery hands to a single row. Spread `handleProps` on the
+ * drag grip and `rowProps` on the row's outer element; `isDragging` /
+ * `isDragTarget` drive the visual state.
+ */
+interface TrackRowDragProps {
+    handleProps: {
+        draggable: true;
+        onDragStart: (e: DragEvent<HTMLElement>) => void;
+        onDragEnd: (e: DragEvent<HTMLElement>) => void;
+    };
+    rowProps: {
+        onDragEnter: (e: DragEvent<HTMLElement>) => void;
+        onDragOver: (e: DragEvent<HTMLElement>) => void;
+        onDragLeave: (e: DragEvent<HTMLElement>) => void;
+        onDrop: (e: DragEvent<HTMLElement>) => void;
+    };
+    /** This row is the one currently being dragged (dim it). */
+    isDragging: boolean;
+    /** This row is the current drop target (show an insertion accent). */
+    isDragTarget: boolean;
+}
+/**
+ * Pure helper: return a NEW array with the item at `from` moved to `to`.
+ * Out-of-range or no-op moves return a shallow copy unchanged. Exported for
+ * unit testing the index math without a DOM.
+ */
+declare function moveItem<T>(arr: readonly T[], from: number, to: number): T[];
+interface UseTrackReorderOptions<T> {
+    /** Host (only {@link PluginHost.reorderTracks} is used). */
+    host: Pick<PluginHost, 'reorderTracks'>;
+    /** The panel's current track array (also the render order). */
+    items: T[];
+    /** The panel's state setter for `items` (used for optimistic update + revert). */
+    setItems: Dispatch<SetStateAction<T[]>>;
+    /** Stable id for persistence — use the track's dbId, not its engine id. */
+    getId: (item: T) => string;
+    /** Called if persistence fails, after the optimistic update is reverted. */
+    onError?: (err: unknown) => void;
+}
+interface UseTrackReorderResult {
+    /** Build the drag props for the row at `index`; spread onto its TrackRow. */
+    dragPropsFor: (index: number) => TrackRowDragProps;
+    /** Index of the row being dragged, or null. */
+    draggingIndex: number | null;
+    /** Index of the current drop-target row, or null. */
+    dragOverIndex: number | null;
+}
+/**
+ * Drag-and-drop reordering for a panel's track list. Dropping a row onto another
+ * row moves it into that row's position (everything between shifts); the top and
+ * bottom are reachable by dropping on the first/last row.
+ */
+declare function useTrackReorder<T>({ host, items, setItems, getId, onError, }: UseTrackReorderOptions<T>): UseTrackReorderResult;
+
+/**
+ * SDK TrackRow — Reusable track row component for generator plugins.
+ *
+ * Renders a complete track UI with prompt input, generation controls,
+ * shuffle/copy, volume/pan, mute/solo, FX drawer, and visual states
+ * (amber pulse for "needs generation", progress overlay, error indicator).
+ *
+ * Layout matches TrackInput (main branch) for visual parity.
+ *
+ * Depends only on PluginHost types + existing shared renderer components.
+ */
+
+interface SDKTrackRowProps {
+    /** Track identity */
+    track: {
+        id: string;
+        name: string;
+        role?: string;
+    };
+    /** Current prompt text (optional — omit when using contentSlot) */
+    prompt?: string;
     /** Playback state */
     runtimeState: {
         muted: boolean;
@@ -1404,10 +2442,19 @@ interface SDKTrackRowProps {
         volume: number;
         pan: number;
     };
+    /** True when ANOTHER track is soloed, so this (non-soloed) track is currently
+     *  silenced. Renders the row dimmed while leaving its Mute button UNLIT — the
+     *  engine's effective-mute model silences it without touching user-mute. Purely
+     *  visual; does not change mute/solo state. */
+    soloedOut?: boolean;
     /** FX category states */
     fxDetailState: TrackFxDetailState;
-    /** FX panel visibility */
-    fxDrawerOpen: boolean;
+    /** Whether the unified track drawer is open. */
+    drawerOpen: boolean;
+    /** Which tab the drawer is showing. */
+    drawerTab: DrawerTab;
+    /** Switch the active drawer tab (tab-strip clicks). Omit for single-tab panels (e.g. loops = FX only). */
+    onTabChange?: (tab: DrawerTab) => void;
     /** Generation in progress */
     isGenerating?: boolean;
     /** Auth state */
@@ -1428,8 +2475,9 @@ interface SDKTrackRowProps {
     onShuffle?: () => void;
     /** Duplicate track (optional — omit to hide Copy button) */
     onCopy?: () => void;
-    /** Delete track */
-    onDelete: () => void;
+    /** Delete track. Optional — omit to hide the delete button (e.g. a composite
+     *  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;
     /** Toggle mute */
@@ -1456,10 +2504,8 @@ interface SDKTrackRowProps {
     instrumentName?: string | null;
     /** Whether the current instrument plugin is missing from the system */
     instrumentMissing?: boolean;
-    /** Whether the instrument drawer is open */
-    instrumentDrawerOpen?: boolean;
-    /** Toggle the instrument drawer */
-    onToggleInstrumentDrawer?: () => void;
+    /** Open/close the drawer to a non-FX tab (the ▾ button). Omit to hide it. */
+    onToggleDrawer?: () => void;
     /** Available instrument plugins for the drawer */
     availableInstruments?: InstrumentDescriptor[];
     /** Currently loaded instrument plugin ID */
@@ -1470,43 +2516,538 @@ interface SDKTrackRowProps {
     instrumentsLoading?: boolean;
     /** Re-scan for instruments */
     onRefreshInstruments?: () => void;
-    /** Which stage the instrument drawer is in */
-    instrumentDrawerStage?: 'instruments' | 'editor';
+    /** Pick-tab sub-view: native plugin editor instead of the instrument grid. */
+    editorStage?: boolean;
     /** Called when user clicks "Open Editor" */
     onShowEditor?: () => void;
     /** Called when user wants to go back from editor view */
     onBackToInstruments?: () => void;
+    /** Ordered list of sounds this track has had this session. */
+    soundHistory?: readonly SoundHistoryEntry[];
+    /** Index into soundHistory of the currently-applied sound. */
+    soundHistoryCursor?: number;
+    /** Restore a sound from the History tab by index. */
+    onRestoreSound?: (index: number) => void;
+    /** Toggle the favorite (⭐) flag on a history entry. */
+    onToggleFavorite?: (index: number) => void;
+    /** Open the drawer's sound-import picker; omit to hide the button. */
+    onImportSound?: () => void;
+    /** Sound-import button label ("Import Sample" / "Import Preset"). */
+    importSoundLabel?: string;
+    /** Current MIDI notes for the piano-roll editor (the 'edit' tab). */
+    editNotes?: readonly PluginMidiNote[];
+    /** Persist edited notes; PRESENCE of this callback enables the Edit tab. */
+    onNotesChange?: (notes: PluginMidiNote[]) => void;
+    /** Scene length in bars (piano-roll grid width). */
+    editBars?: number;
+    /** Scene BPM (piano-roll audition timing). */
+    editBpm?: number;
+    /** Snap step in quarter notes for the piano roll (default 0.25). */
+    editSnap?: number;
+    /** Optional single-note preview when the user adds a note. */
+    onAuditionNote?: (pitch: number, velocity: number, durationMs: number) => void;
+    /** Drag props from {@link useTrackReorder}. When present, renders the grip
+     *  handle and makes the row a drop target. Omit for non-reorderable lists. */
+    drag?: TrackRowDragProps;
+    /** Shared meter handle from `useTrackLevels(host, isPlaying)`. When present,
+     *  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;
+
+/**
+ * Crossfade-pair metadata — family-agnostic types + parsing shared by every
+ * generator panel that supports transition crossfades (synth / drum / instrument).
+ *
+ * A crossfade pair is two normal tracks linked by a shared `groupId`, persisted
+ * in scene plugin_data under `track:<dbId>:crossfade`. Both members play the
+ * same MIDI; one wears the origin preset, the other the target preset. The panel
+ * owns the family-specific create flow (how a preset/sample is copied) and the
+ * render; this module owns only the shape + the scene-data → pairs parse so the
+ * logic can't drift across the three panels.
+ *
+ * @since SDK 2.23.0
+ */
+/** Which half of the pair a per-layer control / member targets. */
+type CrossfadeSlot = 'origin' | 'target';
+/**
+ * Equal-power center gain (~-3 dB, 1/√2) applied to BOTH crossfade layers so a
+ * centered, non-functional slider already sounds like a midpoint blend. The
+ * per-layer volume sliders start here; a later phase's fader drives them.
+ */
+declare const EQUAL_POWER_GAIN = 0.707;
+/**
+ * Per-member crossfade metadata (one scene-data value per member track). The two
+ * members (origin/target) of a pair share a `groupId`.
+ */
+interface CrossfadeMeta {
+    groupId: string;
+    slot: CrossfadeSlot;
+    /** DB id of the partner member track. */
+    partnerDbId: string;
+    /** DB id of the SOURCE track this layer's preset/sample was copied from. */
+    sourceTrackDbId: string;
+    /** DB id of the scene the source track lives in (the from/to scene). */
+    sourceSceneId: string;
+    /** Source track display name (shown in the caption). */
+    sourceName: string;
+    /** Copied preset/sample label (shown in the caption). */
+    soundLabel: string;
+    /** Crossfade position 0..1 (kept identical on both members). */
+    sliderPos: number;
+}
+/** A complete crossfade pair (both members present), keyed by groupId. */
+interface CrossfadePairMeta {
+    groupId: string;
+    sliderPos: number;
+    originDbId: string;
+    targetDbId: string;
+    originSourceName: string;
+    originSoundLabel: string;
+    targetSourceName: string;
+    targetSoundLabel: string;
+}
+/** Narrow an unknown scene-data value to CrossfadeMeta (defensive — survives partial blobs). */
+declare function asCrossfadeMeta(val: unknown): CrossfadeMeta | null;
+/**
+ * Scan all `track:<dbId>:crossfade` keys in a scene's plugin_data and assemble
+ * COMPLETE pairs (both origin + target present). A half-broken group (partner
+ * deleted underneath) is omitted, so its surviving member falls back to a normal
+ * row instead of vanishing.
+ */
+declare function parseCrossfadePairs(sceneData: Record<string, unknown>): CrossfadePairMeta[];
+/** One volume-automation point: a dB value at a time offset (seconds from clip start). */
+interface VolumeAutomationPoint {
+    time: number;
+    db: number;
+}
+/** Origin + target volume curves for one crossfade pair. */
+interface CrossfadeVolumeCurves {
+    origin: VolumeAutomationPoint[];
+    target: VolumeAutomationPoint[];
 }
-declare function TrackRow({ track, prompt, runtimeState, fxDetailState, fxDrawerOpen, isGenerating, isAuthenticated, error, hasMidi, generationProgress, estimatedGenerationMs, onPromptChange, onGenerate, onShuffle, onCopy, onDelete, contentSlot, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onFxToggle, onFxPresetChange, onFxDryWetChange, onToggleFxDrawer, onProgressChange, accentColor, instrumentName, instrumentMissing, instrumentDrawerOpen, onToggleInstrumentDrawer, availableInstruments, currentInstrumentPluginId, onInstrumentSelect, instrumentsLoading, onRefreshInstruments, instrumentDrawerStage, onShowEditor, onBackToInstruments, }: SDKTrackRowProps): React.ReactElement;
+/**
+ * Equal-power crossfade volume curves over a transition of `bars` at `bpm`.
+ * The ORIGIN layer fades OUT and the TARGET fades IN; `sliderPos` (0..1) sets
+ * WHERE in time the equal-power (-3 dB) crossover sits — 0 = hand off near the
+ * start, 1 = hold the origin until near the end. Points span the clip window
+ * [0, durationSeconds] so the engine re-reads them each loop (re-fade per loop).
+ * `steps`+1 points with linear interpolation approximate the cos/sin curve.
+ *
+ * Returns dB point arrays for `host.setTrackVolumeAutomation` — origin on the top
+ * layer, target on the bottom. @since SDK 2.25.0
+ */
+declare function buildCrossfadeVolumeCurves(bars: number, bpm: number, sliderPos: number, steps?: number): CrossfadeVolumeCurves;
 
 /**
- * InstrumentDrawer — Two-stage nested menu for instrument selection + editor access.
+ * CrossfadeTrackRow — a transition "crossfade track": two stacked TrackRows
+ * (origin on top, target on bottom) joined by a horizontal crossfade slider.
  *
- * Stage 1 (instruments): Searchable grid of available VST3/AU instrument plugins.
- * Stage 2 (editor): Shows "Open Editor" button for the selected plugin's native GUI.
+ * Both layers play the SAME generated MIDI; the top wears the ORIGIN scene
+ * track's preset and the bottom wears the TARGET scene track's preset. The user
+ * cannot regenerate, shuffle, or change the preset/sample on either layer —
+ * those controls are simply not wired into the inner TrackRows (the SDK
+ * TrackRow is "controlled by omission"). What remains: per-layer volume/pan,
+ * GROUP mute/solo (both layers toggle together), and a single delete that
+ * removes the whole pair.
+ *
+ * The slider represents WHERE the crossfade happens. In this phase it is
+ * centered and non-functional (omit `onSliderChange` → it renders disabled); a
+ * later phase wires it to fade origin→target across the bars.
+ *
+ * @since SDK 2.22.0
  */
 
-interface InstrumentDrawerProps {
-    /** Available instrument plugins from engine scan */
-    instruments: InstrumentDescriptor[];
-    /** Currently loaded instrument plugin ID (null = default Surge XT) */
-    currentPluginId: string | null;
-    /** Whether the scan is still in progress */
-    isLoading: boolean;
-    /** Called when user selects an instrument */
-    onSelect: (pluginId: string) => void;
-    /** Called when user clicks refresh to re-scan plugins */
-    onRefresh: () => void;
-    /** Which stage the drawer is in */
-    stage?: 'instruments' | 'editor';
-    /** Called when user clicks "Open Editor" */
-    onShowEditor?: () => void;
-    /** Called when user wants to go back from editor view to instrument list */
-    onBackToInstruments?: () => void;
-    /** Name of the selected instrument (for display in editor header) */
-    selectedInstrumentName?: string | null;
+/** One layer (engine track) of a crossfade pair. */
+interface CrossfadeLayer {
+    /** Engine track id of this layer's track (also the meter key). */
+    trackId: string;
+    /** Display name of this layer's (newly created) track. */
+    name: string;
+    /** Musical role (same for both layers — crossfades are same-role). */
+    role?: string;
+    /** Name of the SOURCE track this layer was cloned from (origin/target scene). */
+    sourceName?: string;
+    /** Human label of the copied preset/sound, shown in the caption. */
+    soundLabel?: string;
+    /** Playback state for this layer. */
+    runtimeState: {
+        muted: boolean;
+        solo: boolean;
+        volume: number;
+        pan: number;
+    };
+}
+interface CrossfadeTrackRowProps {
+    /** Top layer — wears the origin (from) scene track's preset. */
+    origin: CrossfadeLayer;
+    /** Bottom layer — wears the target (to) scene track's preset. */
+    target: CrossfadeLayer;
+    /** Crossfade position 0..1 (0 = all origin, 1 = all target). Defaults centered. */
+    sliderPos?: number;
+    /** Toggle mute on BOTH layers together (group mute). */
+    onMuteToggle: () => void;
+    /** Toggle solo on BOTH layers together (group solo). */
+    onSoloToggle: () => void;
+    /** Change one layer's volume (per-layer). */
+    onVolumeChange: (slot: CrossfadeSlot, volume: number) => void;
+    /** Change one layer's pan (per-layer). */
+    onPanChange: (slot: CrossfadeSlot, pan: number) => void;
+    /** Delete the whole pair. */
+    onDelete: () => void;
+    /** Move the crossfade point. Omit to render the slider read-only (phase 1). */
+    onSliderChange?: (pos: number) => void;
+    /** Shared meter handle (welds a peak meter to each layer). */
+    levels?: TrackLevelsHandle;
+    /** 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;
+
+/**
+ * Crossfade MIDI inpainting — builds the LLM user-prompt for a bridge that
+ * MORPHS the ORIGIN part into the TARGET part.
+ *
+ * A normal scene generation composes a part standalone from the scene's chords.
+ * A crossfade bridge is different: it is INPAINTING between two fixed endpoints.
+ * The generated part must begin feeling continuous with the origin pattern and
+ * end feeling continuous with the target pattern, transforming between them
+ * across the transition's bars.
+ *
+ * The harmonic frame — Key / mode / BPM / bars / the transition chord
+ * progression (with beat timing) / scene contract — is injected AUTOMATICALLY by
+ * `host.generateWithLLM` (it prepends the active scene's "Musical Context" block
+ * unless `skipContextPrefix` is set). So this prompt does NOT restate key/bpm/
+ * chords — it adds only the two endpoint patterns + the morph instructions, and
+ * references the harmonic frame as "given above".
+ *
+ * REPRESENTATION (researched for Gemini): ABC notation is the LLM-native format
+ * for melodic generation, but it's weak for percussion, would need a separate
+ * output parser (our output is JSON note-events, already proven with Gemini),
+ * and an inpainting task wants input/output FORMAT SYMMETRY. So each endpoint is
+ * given as the exact JSON note-events PLUS a pitch-named, bar-structured "gloss"
+ * — the transferable wins from the research (pitch NAMES over raw MIDI numbers,
+ * explicit bar/beat structure) layered on the precise, symmetric JSON. Drums
+ * (uniform pitch) get a rhythmic gloss instead of pitch names.
+ *
+ * This changes only the LLM INPUT framing: the OUTPUT schema is unchanged, so the
+ * calling panel keeps its system prompt + parser (and, for drums, its flatten step).
+ *
+ * @since SDK 2.24.0
+ */
+
+interface CrossfadeInpaintInput {
+    /** Musical role of the bridge part (e.g. 'bass'). '' falls back to "melodic". */
+    role: string;
+    /** Transition length in bars (the morph timeline). */
+    bars: number;
+    /** Display name of the ORIGIN source track (the part the bridge begins from). */
+    originName: string;
+    /** Display name of the TARGET source track (the part the bridge arrives at). */
+    targetName: string;
+    /** ORIGIN source scene's key label (e.g. "G minor"). Null/omitted = unknown. */
+    originKey?: string | null;
+    /** TARGET source scene's key label. Null/omitted = unknown. */
+    targetKey?: string | null;
+    /** ORIGIN pattern notes (beat-based; from the FROM scene). May be empty. */
+    originNotes: readonly PluginMidiNote[];
+    /** TARGET pattern notes (beat-based; from the TO scene). May be empty. */
+    targetNotes: readonly PluginMidiNote[];
+    /** Drums: pitch is uniform (flattened), so gloss RHYTHM instead of pitch names. */
+    percussive?: boolean;
 }
-declare function InstrumentDrawer({ instruments, currentPluginId, isLoading, onSelect, onRefresh, stage, onShowEditor, onBackToInstruments, selectedInstrumentName, }: InstrumentDrawerProps): React.ReactElement;
+/**
+ * Build the inpainting user-prompt. The result is the prompt BODY only — pass it
+ * as `request.user` to `host.generateWithLLM` with the panel's normal system
+ * prompt and `responseFormat: 'json'`; the harmonic context auto-prefixes.
+ */
+declare function buildCrossfadeInpaintPrompt(input: CrossfadeInpaintInput): string;
+
+/**
+ * ImportTrackModal — "import a track from another scene" picker (SDK component).
+ *
+ * Shared by all five generator panels (drums / instruments / synths / loops /
+ * stems). Self-fetching: given the scoped `host`, it calls
+ * `host.listImportableTracks()` to enumerate candidates (already filtered to
+ * the calling panel's type and gate-annotated by the host) and
+ * `host.importTrack()` to perform the copy. The UI only renders `importable` +
+ * `disabledReason` — it never computes the harmonic/length/tempo gate itself.
+ *
+ * Two-step picker: choose a source scene, then a track in it. Incompatible
+ * tracks render disabled with a reason tooltip (never hidden), per product
+ * decision.
+ *
+ * @since SDK 2.13.0
+ */
+
+interface ImportTrackModalProps {
+    /** Scoped host — the modal calls listImportableTracks / importTrack itself. */
+    host: PluginHost;
+    /** Controls visibility (the panel owns open/closed from its header button). */
+    open: boolean;
+    /** Close handler (Escape, backdrop, Cancel, or after a successful import). */
+    onClose: () => void;
+    /** Fired after a successful import with the new track handle. */
+    onImported: (handle: PluginTrackHandle) => void;
+    /** Optional modal title (default names the whole-track import). */
+    title?: string;
+    /** data-testid prefix so each panel's modal is addressable in tests. */
+    testIdPrefix?: string;
+    /**
+     * 'track' (default) imports a whole track via `importTrack`. 'sound' copies
+     * ONLY the sound onto an existing track: every candidate is selectable (the
+     * contract gate is ignored) and the chosen track is handed back via `onPick`
+     * instead of being imported — the panel applies it via `host.getTrackSound`.
+     */
+    mode?: 'track' | 'sound';
+    /** Sound-mode pick handler — required when `mode='sound'`. */
+    onPick?: (sel: {
+        sourceTrackDbId: string;
+        trackName: string;
+        sceneName: string;
+    }) => void | Promise<void>;
+    /**
+     * Cross-panel port handler (track mode). When provided, the modal also lists
+     * the ACTIVE scene's tracks owned by OTHER panels as a `sameScene` group —
+     * shown first and selected by default — and routes a pick there to this
+     * callback instead of `importTrack`. The panel re-sounds the part on its own
+     * instrument (create track → copy MIDI → load native sound). @since SDK 2.20.0
+     */
+    onPortTrack?: (sel: {
+        sourceTrackDbId: string;
+        trackName: string;
+        role?: string;
+    }) => void | Promise<void>;
+}
+declare function ImportTrackModal({ host, open, onClose, onImported, title, testIdPrefix, mode, onPick, onPortTrack, }: ImportTrackModalProps): React.ReactElement | null;
+
+/**
+ * CrossfadeModal — "add a crossfade track" picker for a transition scene.
+ *
+ * Shown only inside a `scene_type='transition'` scene. The user picks an ORIGIN
+ * track (from the transition's FROM scene) and a TARGET track (from its TO
+ * scene). Crossfades are same-role: once an origin is chosen, the target
+ * dropdown is filtered to the origin's role.
+ *
+ * Self-fetching: given the scoped `host`, it calls `host.listSceneFamilyTracks`
+ * for both scenes (ungated — a transition deliberately bridges different keys).
+ * It does NOT build the pair itself; it hands the two selections to `onCreate`,
+ * which the panel implements (create two tracks, generate one shared MIDI clip,
+ * copy each preset). `onCreate` should reject on failure so the modal can show
+ * it and stay open.
+ *
+ * @since SDK 2.22.0
+ */
+
+/** A picked source track handed to `onCreate`. */
+interface CrossfadeSelection {
+    /** Source track DB id (selector for getTrackSound + crossfade metadata). */
+    dbId: string;
+    /** Display name (for the row caption). */
+    name: string;
+    /** Musical role (same for both — enforced by the picker). */
+    role?: string;
+}
+interface CrossfadeModalProps {
+    /** Scoped host — the modal calls listSceneFamilyTracks itself. */
+    host: PluginHost;
+    /** Controls visibility (the panel owns open/closed from its header button). */
+    open: boolean;
+    /** DB id of the transition's FROM (origin) scene. */
+    fromSceneId: string;
+    /** DB id of the transition's TO (target) scene. */
+    toSceneId: string;
+    /** Display name for the origin scene heading (optional). */
+    fromSceneName?: string;
+    /** Display name for the target scene heading (optional). */
+    toSceneName?: string;
+    /** Close handler (Escape, backdrop, Cancel, or after a successful create). */
+    onClose: () => void;
+    /** Build the crossfade pair. Should reject on failure so the modal shows it. */
+    onCreate: (origin: CrossfadeSelection, target: CrossfadeSelection) => Promise<void>;
+    /** data-testid prefix. */
+    testIdPrefix?: string;
+}
+declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
+
+/**
+ * ConfirmDialog — styled in-app confirmation modal (SDK component).
+ *
+ * A small, reusable "are you sure?" dialog matching the app's dark theme
+ * (mirrors ImportTrackModal chrome: sas-panel / sas-border / shadow-xl). It
+ * guards destructive actions; the first consumer is track deletion, which was
+ * one stray click away from losing a track's MIDI + sound.
+ *
+ * Controlled component — the caller owns `open` and the confirm/cancel
+ * handlers. Escape and a backdrop click both cancel, and the Cancel button is
+ * auto-focused on open so a reflexive Enter dismisses rather than deletes.
+ *
+ * @since SDK 2.17.0
+ */
+
+interface ConfirmDialogProps {
+    /** Controls visibility (the caller owns open/closed). */
+    open: boolean;
+    /** Bold heading line. */
+    title: string;
+    /** Body copy — a string or richer node. */
+    message: React.ReactNode;
+    /** Confirm button label (default "Delete"). */
+    confirmLabel?: string;
+    /** Cancel button label (default "Cancel"). */
+    cancelLabel?: string;
+    /** When true (default), the confirm button reads as a destructive (red) action. */
+    destructive?: boolean;
+    /** Fired when the user confirms. */
+    onConfirm: () => void;
+    /** Fired on Cancel, Escape, or backdrop click. */
+    onCancel: () => void;
+    /** 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;
+
+/**
+ * Modal — the SDK's one modal-stacking primitive (portal + z-tier + backdrop).
+ *
+ * Every SDK modal renders INSIDE a plugin's accordion section, whose animated
+ * `overflow-hidden` + `transition-all` wrapper establishes a stacking context.
+ * An inline `position: fixed` overlay is therefore scoped to that section and
+ * can be painted UNDER a neighbouring panel (the "import modal invisible on a
+ * later open" bug). This component solves that once: it portals the overlay to
+ * <body> — out of every panel's stacking context — at a z-tier above all the
+ * app's `z-50` dropdowns/banners but below the toast tier (`z-[9999]`), so
+ * toasts still float over modals.
+ *
+ * Controlled: the caller owns `open` and `onClose`. The caller renders its own
+ * dialog box as `children` (keep the box's `onClick={e => e.stopPropagation()}`
+ * so inside-clicks don't dismiss). Escape and a backdrop click both close.
+ *
+ * @since SDK 2.21.0
+ */
+
+interface ModalProps {
+    /** Controls visibility (the caller owns open/closed). */
+    open: boolean;
+    /** Close handler — fired on Escape and backdrop click. */
+    onClose: () => void;
+    /** The dialog box. Give it `onClick={e => e.stopPropagation()}`. */
+    children: React.ReactNode;
+    /** data-testid prefix; the backdrop is `${testIdPrefix}-overlay`. */
+    testIdPrefix?: string;
+    /** Close when the backdrop is clicked (default true). */
+    closeOnBackdrop?: boolean;
+    /** 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>;
+}
+declare function Modal({ open, onClose, children, testIdPrefix, closeOnBackdrop, closeOnEscape, initialFocusRef, }: ModalProps): React.ReactElement | null;
+
+/**
+ * PianoRollEditor — a compact, DOM-based MIDI note editor for the track drawer.
+ *
+ * Controlled: `notes` in, `onChange(next)` out. Notes render as absolutely-
+ * positioned divs over a beat/pitch grid (DOM, not canvas — so it themes with
+ * sas-* tokens and is fully driveable by React Testing Library). Supports:
+ *   - add     : click an empty grid cell
+ *   - delete  : click an existing note (no drag)
+ *   - move    : drag a note's body (snap-quantised)
+ *   - resize  : drag a note's right-edge handle (snap-quantised, ≥ one step)
+ *   - octave  : shift the whole clip ±12 (toolbar) — no velocity lane
+ *               / marquee yet.
+ * On load the viewport auto-scrolls to vertically center the note cluster, so a
+ * low melody isn't stranded off-screen at the bottom of the pitch range.
+ *
+ * Coordinate spaces:
+ *   pitch (0-127)  ── row = hi - pitch ──  top px  = row * ROW_HEIGHT
+ *   beat (¼ notes) ─────────────────────── left px = beat * PX_PER_BEAT
+ *
+ * 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. */
+declare const PX_PER_BEAT = 24;
+/** Vertical pixels per semitone row. */
+declare const ROW_HEIGHT = 12;
+/** Left keyboard-gutter width (px). */
+declare const GUTTER_W = 28;
+/** Pointer travel (px) before a press on a note becomes a drag instead of a click. */
+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;
+/** 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.
+ */
+declare function cellToPx(pitch: number, startBeat: number, hi: number): {
+    left: number;
+    top: number;
+};
+/**
+ * Grid-local pixel → snapped cell. `hi` is the highest visible pitch; the beat
+ * 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): {
+    pitch: number;
+    startBeat: number;
+};
+/**
+ * New `durationBeats` for a note whose right edge is dragged to grid-local pixel
+ * `localX`. The end snaps to the nearest `snap` step, is clamped to at least one
+ * 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;
+/**
+ * `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
+ * "where the majority of notes are" framed) and clamps to the valid scroll
+ * range. `hi` is the top visible pitch; `rowCount` the total rows in the grid.
+ * Returns 0 when there are no notes.
+ */
+declare function centerScrollTop(pitches: readonly number[], hi: number, rowCount: number, viewportH: number): number;
+/** Transpose every note by `semitones`, clamping pitch to [0,127] (never drops a note). */
+declare function transposeNotes(notes: readonly PluginMidiNote[], semitones: number): PluginMidiNote[];
+interface PianoRollEditorProps {
+    /** Controlled note list (quarter-note beats). The editor never mutates this. */
+    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. */
+    bars: number;
+    /** BPM — used only for audition timing in v1. */
+    bpm: number;
+    /** Beats per bar (time-signature numerator). Default 4. */
+    beatsPerBar?: number;
+    /** Snap step in quarter notes (1 = ¼ note, 0.25 = 1/16). Default 0.25. */
+    snap?: number;
+    /** Snap steps the toolbar selector offers. Default [1, 0.5, 0.25]. */
+    snapOptions?: number[];
+    /** Notified when the user changes snap (the editor still tracks it internally). */
+    onSnapChange?: (snap: number) => void;
+    /** Lowest pitch always visible. Default C2 (36). */
+    minPitch?: number;
+    /** Highest pitch always visible. Default C6 (84). */
+    maxPitch?: number;
+    /** Expand the visible window to include notes outside [minPitch,maxPitch]. Default true. */
+    autoFit?: boolean;
+    /** Optional single-note preview, fired when a note is added. */
+    onAuditionNote?: (pitch: number, velocity: number, durationMs: number) => void;
+    /** Velocity for newly-added notes. Default 100. */
+    defaultVelocity?: number;
+    /** Disable all interaction (e.g. while the track is generating). Default false. */
+    disabled?: boolean;
+    /** Extra className for the outer container. */
+    className?: string;
+    /** 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;
 
 /**
  * VolumeSlider Component
@@ -1621,6 +3162,323 @@ declare function calculateTimeBasedTarget(elapsedMs: number, estimatedDurationMs
  */
 declare function SorceryProgressBar({ isLoading, statusText, completeText, onComplete, heightClass, initialProgress, onProgressChange, estimatedDurationMs, }: SorceryProgressBarProps): React.ReactElement | null;
 
+/**
+ * DownloadPackButton — versioned-pack download trigger (SDK component).
+ *
+ * Parameterized by `packId`; drives the download through the host
+ * (`host.startSamplePackDownload` / `host.onSamplePackProgress`) so plugins
+ * never reach into the app's IPC (`window.electronAPI`). Two display variants:
+ *   - 'compact' (default) — small uppercase button for panel headers
+ *   - 'large'             — bigger CTA used inside SamplePackCTACard
+ *
+ * @since SDK 2.8.0 (moved from the app and refactored onto PluginHost).
+ */
+
+type DownloadPackButtonVariant = 'compact' | 'large';
+interface DownloadPackButtonProps {
+    /** Host the plugin received; drives the download + progress. */
+    host: PluginHost;
+    packId: string;
+    /** Pack display name, e.g. 'Drum Sample Library'. Used in tooltips/labels. */
+    displayName: string;
+    /** Bundle size in bytes (shown in the large-variant label). */
+    sizeBytes?: number;
+    variant?: DownloadPackButtonVariant;
+    /** Called once after the install completes (status === 'complete'). */
+    onDownloadComplete?: () => void;
+}
+declare const DownloadPackButton: React.FC<DownloadPackButtonProps>;
+
+/**
+ * SamplePackCTACard — empty-state card a generator panel renders when its
+ * sample pack is missing OR a newer version is available. Wraps
+ * DownloadPackButton in a centered card. The completion callback should
+ * re-fetch pack status on the parent so the card unmounts and the normal panel
+ * UI takes over.
+ *
+ * @since SDK 2.8.0 (moved from the app; download driven through PluginHost).
+ */
+
+type SamplePackCTACardStatus = 'missing' | 'stale' | 'checking';
+/** Minimal pack info the card needs. A PackConfig is structurally compatible. */
+interface SamplePackCardInfo {
+    packId: string;
+    displayName: string;
+    description: string;
+    sizeBytes?: number;
+}
+interface SamplePackCTACardProps {
+    /** Host the plugin received; drives the download. */
+    host: PluginHost;
+    pack: SamplePackCardInfo;
+    status: SamplePackCTACardStatus;
+    onDownloadComplete?: () => void;
+}
+declare const SamplePackCTACard: React.FC<SamplePackCTACardProps>;
+
+/**
+ * WaveformView — small canvas waveform for an audio file on disk.
+ *
+ * Reads bytes via `host.getAudioFileBytes`, decodes via
+ * `AudioContext.decodeAudioData`, computes peaks, and renders to a
+ * canvas. Suitable for take rows, sample previews, or any place a
+ * decorative ~40px waveform makes sense.
+ *
+ * The component is self-contained: it owns the AudioContext and the
+ * peak buffer, decodes once per `filePath` change, and tears down on
+ * unmount. Failures (file missing, decode error) render as a silent
+ * blank canvas — the caller can decide how to surface errors.
+ */
+
+interface WaveformViewProps {
+    host: PluginHost;
+    filePath: string;
+    /** Number of bins to compute. Default 256 — plenty for ~40px tall rows. */
+    bins?: number;
+    /** Tailwind / inline className for sizing. Default: w-full h-10. */
+    className?: string;
+    /** Override the bar fill style (e.g., to match a track color). */
+    fillStyle?: string;
+    /**
+     * If set, the bin range spans `targetSamples` instead of the file's
+     * actual length. Bins beyond the audio render as flat silence — used
+     * to align a partial recording inside a full-loop-width canvas so
+     * every take row has the same time scale.
+     */
+    targetSamples?: number;
+}
+declare const WaveformView: React.FC<WaveformViewProps>;
+
+/**
+ * Shared level-meter component.
+ *
+ * Renders a horizontal LED-style bar over -60dBFS → 0dBFS:
+ *   - A fixed left-to-right gradient (green → orange → red), so the color is
+ *     tied to POSITION: a quiet signal lights only the green left, a hot signal
+ *     reaches the red right. An "unlit" mask hides the gradient beyond the
+ *     current level.
+ *   - A deterministic segment grid (the "LED monitor" look) drawn as a pure-CSS
+ *     repeating overlay — constant DOM, no per-frame cost.
+ *   - An optional peak-hold marker (`peakHoldDb`) — a bright line at the recent
+ *     maximum that the caller holds/decays (see `useTrackMeter`).
+ *   - An optional CLIP badge the caller wires up.
+ *
+ * Pure presentational: takes the current dB + `active` flag (+ optional held
+ * peak) and draws. The only production consumer is the per-track strip
+ * (`TrackMeterStrip`, via `compact`). `compact` shrinks the bar and drops the
+ * numeric dB readout.
+ */
+
+interface LevelMeterProps {
+    /** Current peak level in dBFS. -120 means "no signal". */
+    peakDb: number;
+    /** True when the underlying audio callback is firing. False = floor. */
+    active: boolean;
+    /**
+     * Held peak in dBFS for the peak-hold marker. Omit to draw no marker. The
+     * marker is hidden when this is at/below the visible floor (-60).
+     */
+    peakHoldDb?: number;
+    /** Latched clip flag. When true, render the CLIP badge. */
+    clipped?: boolean;
+    /** User-clickable handler to clear the latched clip indicator. */
+    onClearClip?: () => void;
+    /**
+     * Thin strip mode for per-track meters: hides the numeric dB readout and
+     * shrinks the bar. Keeps the (rare) CLIP badge.
+     */
+    compact?: boolean;
+    /** Optional className overlaid on the wrapper for layout tweaks. */
+    className?: string;
+    /** Inline test id — make multiple instances distinguishable. */
+    'data-testid'?: string;
+}
+declare const LevelMeter: React.FC<LevelMeterProps>;
+
+/**
+ * TrackMeterStrip — the thin per-track peak meter welded to the bottom of a
+ * track row. Cosmetic: gives a general sense of each track's level and adds
+ * motion during playback.
+ *
+ * This is deliberately its OWN component so the per-row meter selector
+ * (`useTrackMeter`) re-renders ONLY this strip at ~30Hz, never the heavy
+ * TrackRow around it. Render it as a full-width sibling directly under a row
+ * body; it welds on with a squared top edge (like the track drawer does).
+ */
+
+interface TrackMeterStripProps {
+    /** Shared meter handle from `useTrackLevels(host, isPlaying)`. */
+    levels: TrackLevelsHandle;
+    /** Tracktion engine track id (matches `PluginTrackHandle.id`). */
+    trackId: string;
+    /** Round the bottom corners (false when a drawer welds on below). Default true. */
+    roundBottom?: boolean;
+    /** Optional className for layout tweaks on the wrapper. */
+    className?: string;
+}
+declare const TrackMeterStrip: React.FC<TrackMeterStripProps>;
+
+/**
+ * ScrollingWaveform — live waveform during recording (Phase 8.10).
+ *
+ * Reads the platform's `peakDb` history and renders it as a horizontal
+ * bar-graph that scrolls left as new samples arrive. Two halves: top
+ * band shows positive amplitude, bottom band mirrors it (matches the
+ * static waveform's min/max layout in `WaveformView`).
+ *
+ * The data source is a function the caller supplies — typically a ref
+ * to the `inputLevelDb` value from `AudioRoutingContext` polled at
+ * ~30Hz. The component samples that ref via requestAnimationFrame and
+ * shifts a fixed-size float ring buffer one column per frame.
+ *
+ * Pure presentational + animation logic; no IPC. Stops animating
+ * when `active` is false (engine isn't running the audio callback).
+ */
+
+interface ScrollingWaveformProps {
+    /** Function returning the latest peak in dBFS. Called per RAF. */
+    getPeakDb: () => number;
+    /** True while the audio callback is running; false freezes the wave. */
+    active: boolean;
+    /** Number of horizontal columns in the ring buffer. */
+    columns?: number;
+    /** Optional className for sizing. */
+    className?: string;
+    /** Highlight color for the wave. */
+    fillStyle?: string;
+}
+declare const ScrollingWaveform: React.FC<ScrollingWaveformProps>;
+
+/**
+ * OffsetScrubber — manual sample-offset slider for Lyria-generated audio.
+ *
+ * Renders a thin horizontal track with one tick per detected beat (tall
+ * tick on the downbeat) and a draggable thumb. Drag distance maps to a
+ * sample offset that is applied to the audio clip via
+ * `host.setAudioOffsetSamples(trackId, n)`.
+ *
+ * Snap behavior:
+ *   - Default: snap to the nearest beat in `cuePoints.beats`.
+ *   - Hold Shift: bypass snap (free 1-sample resolution).
+ *   - Click on a tick mark: jump to that beat exactly.
+ *
+ * The visible range is one bar (= meter beats) on each side of bar 1.
+ * For a 4-bar / 4/4 clip at 44100 Hz, one bar at 120 BPM is 88_200
+ * samples — so the slider covers ±88_200 samples, ~2 s either way. That
+ * matches the alignment errors we observe from Lyria detection misses
+ * (typically <1 beat off).
+ *
+ * BPM mismatch chip: shown when `cuePoints.detected_bpm` is more than
+ * 1 BPM away from the project BPM, since the beat ticks won't line up
+ * with the project grid in that case.
+ */
+
+interface OffsetScrubberProps {
+    /** Detected beat positions + sample rate. Slider is disabled when null. */
+    cuePoints: PluginCuePoints | null;
+    /** Current offset, in samples (signed). */
+    offsetSamples: number;
+    /** Project BPM — used to compute the visible range and the mismatch chip. */
+    projectBpm: number;
+    /** Beats per bar, defaults to 4. */
+    meter?: number;
+    /** Called on drag-end with the resolved offset (already snapped). */
+    onChange: (offsetSamples: number) => void;
+    /** Disable interaction (e.g., during generation / split). */
+    disabled?: boolean;
+}
+declare function OffsetScrubber({ cuePoints, offsetSamples, projectBpm, meter, onChange, disabled, }: OffsetScrubberProps): React.ReactElement;
+
+/**
+ * Shared waveform peaks + canvas drawer.
+ *
+ * Originally inlined in `stems/TrimEditorDrawer.tsx`; lifted to
+ * this module so the recorder plugin's per-take rows can render the
+ * same compact min/max display without duplicating the math.
+ *
+ * Design:
+ *   - `computePeaks` reduces an AudioBuffer to `bins` min/max pairs (mono
+ *     average across channels). Output layout is interleaved
+ *     `[min0, max0, min1, max1, ...]` so the renderer reads pairs
+ *     sequentially without index arithmetic.
+ *   - `drawWaveform` paints one 1px vertical bar per canvas column,
+ *     dpr-aware so it stays crisp on retina displays.
+ *
+ * No host or React dependencies — pure functions are safe to use from
+ * tests, web workers, or non-React renderers.
+ */
+interface WaveformPeaks {
+    /** Sample rate of the source file (used to convert sample → seconds). */
+    sampleRate: number;
+    /** Total length of the raw file in samples. */
+    totalSamples: number;
+    /** Min/max pairs per bin (length = bins × 2). */
+    peaks: Float32Array;
+}
+/**
+ * Reduce an AudioBuffer to `bins` min/max pairs. Mono averages across
+ * channels. The output buffer is fixed-size (`bins * 2`) for fast canvas
+ * traversal.
+ *
+ * `targetSamples` (optional) extends the bin range to a fixed sample
+ * count larger than the buffer's actual length — bins falling beyond
+ * the buffer get (0, 0) pairs, which renders as a flat tail. Used by
+ * the recorder so a partial last chunk's waveform sits at the start of
+ * a full-loop-width canvas instead of being stretched to fill.
+ */
+declare function computePeaks(audioBuffer: AudioBuffer, bins: number, targetSamples?: number): WaveformPeaks;
+/**
+ * Draw min/max peaks to the given canvas. Resizes the canvas backing
+ * store to CSS pixels × devicePixelRatio so the result is crisp on
+ * retina. Caller controls CSS sizing via the `<canvas>` element's
+ * className.
+ */
+declare function drawWaveform(canvas: HTMLCanvasElement, peaks: WaveformPeaks, options?: {
+    fillStyle?: string;
+}): void;
+
+/**
+ * WAV peak analyzer (Phase 8.10).
+ *
+ * Reads a WAV file via the plugin host, decodes it via Web Audio,
+ * scans every channel for the absolute maximum sample, and returns
+ * peak dBFS + a clipped flag (true when the peak >= -1dBFS, matching
+ * the engine's hard-limiter ceiling).
+ *
+ * Used by the recorder's take rows to surface "this take peaked at
+ * -8dB" or "this take CLIPPED" without the user having to click play.
+ */
+
+interface PeakAnalysis {
+    peakLinear: number;
+    peakDb: number;
+    clipped: boolean;
+}
+declare function analyzeWavPeak(host: PluginHost, filePath: string): Promise<PeakAnalysis>;
+
+/**
+ * Synthesize a PluginCuePoints object from raw BPM/sample-rate inputs.
+ *
+ * The OffsetScrubber consumes PluginCuePoints — a beat grid plus
+ * per-beat sample positions, normally produced by Lyria's onset
+ * detector. The recorder doesn't have detected cue points (live
+ * recordings have no detection pass), but it always knows the project
+ * BPM, the engine sample rate, and the loop length in bars. That's
+ * enough to construct a synthetic grid where every beat sits on a
+ * regular interval — which is exactly what the scrubber needs to
+ * provide tick marks + snap behavior for nudging the take's offset.
+ */
+
+interface SynthesizeCuePointsOptions {
+    bpm: number;
+    sampleRate: number;
+    /** Total bars in the clip (e.g. 4 for a 4-bar loop). */
+    bars: number;
+    /** Beats per bar. Defaults to 4 (4/4). */
+    meter?: number;
+}
+declare function synthesizeCuePoints({ bpm, sampleRate, bars, meter, }: SynthesizeCuePointsOptions): PluginCuePoints;
+
 /**
  * useSceneState — Scene-keyed state hook for plugin developers.
  *
@@ -1646,6 +3504,87 @@ 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.
+ *
+ * Powers the drawer "History" tab: restore any earlier sound, star favorites,
+ * and (via the host plugin) persist across project reopen. The SDK is ignorant
+ * of WHAT a sound is — each plugin records an opaque `descriptor` (a drum sample
+ * path / an instrument `{ displayName, zones }` / a synth Surge state blob) plus
+ * a human `label`, and supplies `applySound` to re-apply a chosen descriptor.
+ *
+ * Persistence is the plugin's job: pass `opts.onChange` (called after every
+ * mutation with the new state) to save, and call `restore()` on load to seed.
+ * Favorited entries are never auto-evicted by the cap.
+ *
+ * Robustness: `applySound` + `onChange` are read through refs, so the returned
+ * object is referentially STABLE regardless of whether the caller memoizes them.
+ * Plugins list this object in `loadTracks` deps — an unstable return previously
+ * caused a render loop, so keep it stable.
+ *
+ * @since SDK 2.13.0
+ */
+
+/** A track's ordered sound history plus the index of the currently-applied sound. */
+interface TrackSoundHistory {
+    entries: readonly SoundHistoryEntry[];
+    /** Index into `entries` of the currently-applied sound; -1 when empty. */
+    cursor: number;
+}
+interface UseSoundHistoryOptions {
+    /** Max non-favorited entries kept per track (favorites are never evicted). Default 24. */
+    max?: number;
+    /**
+     * Called after every mutation (record/undo/restoreTo/toggleFavorite/clear) with the
+     * track's new state — use it to persist. NOT called by `restore()` (that's a load).
+     */
+    onChange?: (trackId: string, state: TrackSoundHistory) => void;
+}
+interface UseSoundHistoryResult {
+    /** Remember a sound that was just applied (generation, scene-load, or shuffle). */
+    record(trackId: string, descriptor: unknown, label: string): void;
+    /** Re-apply the sound one step before the current one. Resolves true if it moved. */
+    undo(trackId: string): Promise<boolean>;
+    /** Re-apply a specific entry by index. Resolves true if it applied. */
+    restoreTo(trackId: string, index: number): Promise<boolean>;
+    /** The ordered history + cursor for a track (safe empty default). */
+    list(trackId: string): TrackSoundHistory;
+    /** Whether there is an earlier sound to step back to. */
+    canUndo(trackId: string): boolean;
+    /** Forget a track's history (e.g. on regenerate). Persists the cleared state. */
+    clear(trackId: string): void;
+    /** Forget ALL tracks' history in memory (e.g. before re-seeding on scene load). */
+    reset(): void;
+    /** Seed a track's full history (e.g. from persistence on load). Does NOT fire onChange. */
+    restore(trackId: string, state: {
+        entries?: readonly SoundHistoryEntry[];
+        cursor?: number;
+    } | null | undefined): void;
+    /** Toggle the favorite flag on an entry (favorites survive cap eviction). */
+    toggleFavorite(trackId: string, index: number): void;
+}
+declare function useSoundHistory(applySound: (trackId: string, descriptor: unknown) => Promise<void>, opts?: UseSoundHistoryOptions): UseSoundHistoryResult;
+
 /**
  * Plugin SDK Version
  *
@@ -1654,7 +3593,7 @@ declare function useSceneState<T>(activeSceneId: string | null, initialValue: T)
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.3.0";
+declare const PLUGIN_SDK_VERSION = "2.25.0";
 
 /**
  * FX Preset Definitions
@@ -1708,4 +3647,98 @@ declare function sliderToDb(slider: number): number;
  */
 declare function dbToSlider(db: number): number;
 
-export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, type CreateTrackOptions, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, type DeckBoundaryEvent, type DeckBoundaryListener, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, type GeneratorPlugin, type GeneratorType, type InstrumentDescriptor, InstrumentDrawer, type InstrumentDrawerProps, type LLMGenerationRequest, type LLMGenerationResult, type MidiClipData, type MidiWriteResult, type MixInterpolation, type MusicalContext, PLUGIN_SDK_VERSION, PanSlider, 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 PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, type SavePluginPresetOptions, type SceneChangeListener, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type StemType, type TrackFxDetailState, type TrackFxState, TrackRow, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };
+/**
+ * Format the cross-plugin concurrent-track context into a prose block
+ * that's safe to drop straight into an LLM user-prompt. Both the synth
+ * and drum builtin panels use this so the rendered prompt stays
+ * consistent across generators — and so a single change here propagates
+ * to every plugin that calls `host.getGenerationContext()`.
+ *
+ * Per-track payload follows the user's preferred shape (raw note JSON
+ * grouped by chord) so the model sees velocity / start-beat /
+ * duration / pitch verbatim and can reason about feel + harmony.
+ *
+ * Returns the empty string when there are no concurrent tracks — call
+ * sites can `if (block) push(block)` rather than baking in a placeholder.
+ */
+
+declare function formatConcurrentTracks(ctx: PluginGenerationContext): string;
+
+/**
+ * Lightweight, dependency-free semantic matching for sample selection.
+ *
+ * Sample generators (drums, instruments) ship a short StableAudio text
+ * prompt next to every sample ("tight 909-style kick one shot, hard click
+ * transient, short punchy body, dry, no hi hats, no loop"). When the user
+ * asks for "a 1950s style boom bap kick" we want to pick the sample whose
+ * prompt is closest to that intent — instead of a uniform random draw —
+ * while still preserving variety so a vague "give me a kick" doesn't return
+ * the identical sample every time.
+ *
+ * Design notes:
+ *   - Pure functions, no I/O, no SDK-type dependencies → trivially unit
+ *     testable with an injected `rng`, and safe to call from either the
+ *     main or renderer process.
+ *   - Scoring is IDF-weighted query-coverage (a TF-IDF / BM25-lite). The
+ *     IDF is derived from the candidate pool itself, so it is STRUCTURAL —
+ *     no hand-maintained synonym tables. Rare, discriminating tokens in the
+ *     prompts ("909", "dusty", "tube") dominate; corpus-universal filler
+ *     ("one", "shot", "dry") washes out to ~zero IDF on its own.
+ *   - The near-universal negative clauses StableAudio prompts carry
+ *     ("no hi hats", "no loop", "no melody") are stripped before tokenizing;
+ *     they are pure noise for matching.
+ *   - Selection is softmax-weighted random among the top-k. Flat scores →
+ *     ~uniform (≈ the old random behavior); a clear winner → tight
+ *     convergence. The all-zero (no-signal) case is intentionally left to
+ *     the caller to fall back to its existing random path over the full
+ *     pool — see `scorePromptMatch`'s contract below.
+ */
+/**
+ * Tokenize a prompt or query into matchable lowercase tokens.
+ *
+ *   1. Drop comma-delimited negative clauses ("no hi hats", "no loop").
+ *   2. Lowercase, split on any non-alphanumeric run.
+ *   3. Drop stop-words and 1–2 digit numeric noise ("01", "02") while
+ *      keeping meaningful numerics ("808", "909", "1950").
+ */
+declare function tokenizePrompt(text: string): string[];
+/**
+ * Score each candidate prompt against the query, returning a parallel array
+ * of scores in [0, 1] (1 = the candidate covers all of the query's
+ * discriminating intent).
+ *
+ * Contract: a returned max of 0 means the query shares NO matchable token
+ * with any candidate (no signal). Callers should treat that as "fall back to
+ * the existing uniform-random pick over the full pool" so vague queries keep
+ * today's variety rather than biasing toward an arbitrary top-k slice.
+ */
+declare function scorePromptMatch(query: string, candidatePrompts: ReadonlyArray<string>): number[];
+/** One scored candidate. `key` (if present) is what `excludeKeys` matches on. */
+interface ScoredCandidate<T> {
+    item: T;
+    score: number;
+    key?: string;
+}
+interface PickTopKOptions {
+    /** Consider only the top-k by score (default 5). */
+    k?: number;
+    /**
+     * Softmax temperature (default 0.3). Lower → sharper preference for the
+     * top match; higher → flatter (more variety). Scores are in [0, 1].
+     */
+    temperature?: number;
+    /** Candidate keys to exclude (e.g. shuffle history). */
+    excludeKeys?: ReadonlySet<string>;
+    /** Injectable RNG in [0, 1) for deterministic tests (default Math.random). */
+    rng?: () => number;
+}
+/**
+ * Pick one candidate via softmax-weighted random selection among the top-k
+ * by score. Returns null only when the pool is empty after exclusion.
+ *
+ * Equal scores → equal weights → uniform pick among the top-k, so this
+ * degrades gracefully toward random when the query gives no preference.
+ */
+declare function pickTopKWeighted<T>(scored: ReadonlyArray<ScoredCandidate<T>>, options?: PickTopKOptions): T | null;
+
+export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, type CrossfadeVolumeCurves, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginSkill, type PluginSkillInputSchema, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asCrossfadeMeta, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };