@signalsandsorcery/plugin-sdk 2.26.1 → 2.34.1

package/dist/index.d.mts

@@ -383,6 +383,19 @@ interface PluginHost {
     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>;
+    /**
+     * Persist a preset as the track's durable sound identity (DB `preset_state`,
+     * the shape getTrackSound reads back). setPluginState/setRawPluginState are
+     * engine-only — a copied sound that is never persisted has no identity, so
+     * drift checks (e.g. the transition-designer preset re-sync) can never
+     * observe convergence. Call after applying a copied state to a layer track.
+     * @since SDK 2.34.0
+     */
+    persistTrackPresetState?(trackId: string, preset: {
+        state: string;
+        stateType: 'raw' | 'valuetree';
+        name?: string;
+    }): Promise<void>;
     /** List plugins currently loaded on a track. */
     getTrackPlugins(trackId: string): Promise<PluginSynthInfo[]>;
     /** Remove a plugin from a track. */
@@ -882,6 +895,30 @@ interface PluginHost {
     deleteSampleTrack(trackId: string): Promise<void>;
     /** Get all sample tracks in the active scene. Re-establishes ownership. */
     getPluginSampleTracks(): Promise<PluginSampleTrackInfo[]>;
+    /**
+     * Resolve a sample-track row id (as returned by `listSceneFamilyTracks`) back
+     * to its library `sampleId` + metadata, so a loop can be re-created in another
+     * scene (transition crossfade/fade). Returns null if not a sample track.
+     * @since SDK 2.31.0
+     */
+    getSampleTrackInfo?(dbId: string): Promise<{
+        sampleId: string;
+        fileName?: string;
+        bpm?: number;
+        key?: string;
+    } | null>;
+    /**
+     * Render an audio transition effect onto a sample (offline DSP via the audio
+     * tool), returning a NEW library sample to place. Used for stutter / chopped
+     * loop transitions. @since SDK 2.32.0
+     */
+    renderSampleEffect?(sampleId: string, spec: {
+        effect: 'stutter' | 'chopped';
+        bars: number;
+        bpm: number;
+        repeats?: number;
+        slices?: number;
+    }): Promise<PluginSampleInfo>;
     /** Time-stretch a sample to a target BPM. Returns the new sample info. */
     timeStretchSample(sampleId: string, targetBpm: number): Promise<PluginSampleInfo>;
     /**
@@ -1197,6 +1234,10 @@ interface SceneFamilyTrack {
     name: string;
     /** Musical role if set — used to enforce same-role crossfade pairing. */
     role?: string;
+    /** Generation prompt, when the track was AI-generated. The crossfade picker
+     * shows this as the primary label (users recognise tracks by prompt, not id).
+     * @since SDK 2.27.0 */
+    prompt?: string;
 }
 /**
  * One OTHER scene and its candidate tracks (already type-filtered). Scenes with
@@ -2573,6 +2614,16 @@ declare function TrackRow({ track, prompt, runtimeState, soloedOut, fxDetailStat
  *
  * @since SDK 2.23.0
  */
+
+/**
+ * Stable, state-aware identity for a track's sound — used to auto-detect when a
+ * transition's SOURCE preset/sample has drifted from the copy on its layer. A
+ * preset hashes its full STATE blob (so a same-name param tweak still differs); a
+ * sample uses its path; an instrument uses its id + zones. Empty string = no sound.
+ * @since SDK 2.32.0
+ */
+declare function hashString(s: string): string;
+declare function soundIdentity(snap: TrackSoundSnapshot | null | undefined): string;
 /** Which half of the pair a per-layer control / member targets. */
 type CrossfadeSlot = 'origin' | 'target';
 /**
@@ -2772,6 +2823,224 @@ interface CrossfadeInpaintInput {
  */
 declare function buildCrossfadeInpaintPrompt(input: CrossfadeInpaintInput): string;
 
+/**
+ * Fade metadata — family-agnostic types + parsing for transition orphan fades
+ * (synth / drum / instrument panels).
+ *
+ * A fade is a CROSSFADE WITH ONE EMPTY ENDPOINT: a single generated track that
+ * either fades IN (a target-only track entering — `morph(∅ → target)`) or fades
+ * OUT (an origin-only track leaving — `morph(origin → ∅)`) across the transition
+ * loop. It reuses the same generation pipeline (`buildCrossfadeInpaintPrompt`
+ * with one empty endpoint) and the same volume-automation fader as crossfade.
+ *
+ * Stored in scene plugin_data under `track:<dbId>:fade` (ONE entry per track —
+ * unlike crossfade there is no partner / groupId). Kept as a SEPARATE type from
+ * crossfade so the load-bearing "drop a half-broken pair" guard in
+ * `parseCrossfadePairs` stays intact.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** Which way the lone track fades over the transition. */
+type FadeDirection = 'in' | 'out';
+/**
+ * How the fade is shaped:
+ * - `volume` — a one-sided level ramp does the work (DJ-style). Best for
+ *   textural/sustained material (pads, atmospheres).
+ * - `build` — the MIDI carries the fade (the inpaint grows sparse→full on the way
+ *   in, or dissolves on the way out); the level stays flat. Best for articulated
+ *   material (lead, bass, drums, winds, vocals).
+ */
+type FadeGesture = 'volume' | 'build';
+/** Per-track fade metadata (one scene-data value per fade track). */
+interface FadeMeta {
+    direction: FadeDirection;
+    gesture: FadeGesture;
+    /**
+     * Audio transition variant for one-sided LOOP transitions. `'fade'` (default,
+     * and the only value MIDI panels write) is a plain level ramp; `stutter` /
+     * `chopped` re-render the loop's audio, `delay` adds a delay-throw FX. Shown as
+     * a badge on the row. @since SDK 2.32.0
+     */
+    effect?: 'fade' | 'stutter' | 'chopped' | 'delay';
+    /** DB id of the SOURCE track this fade's preset/sample + pattern was seeded from. */
+    sourceTrackDbId: string;
+    /** DB id of the scene the source track lives in (the from/to scene). */
+    sourceSceneId: string;
+    /** Source track display name (shown in the caption). */
+    sourceName: string;
+    /** Copied preset/sample label (shown in the caption). */
+    soundLabel: string;
+    /** Fade position 0..1 — WHERE in time the fade midpoint sits. */
+    sliderPos: number;
+}
+/** A fade entry resolved from scene data: the fade track's dbId + its metadata. */
+interface FadeEntry {
+    dbId: string;
+    meta: FadeMeta;
+}
+/** Narrow an unknown scene-data value to FadeMeta (defensive — survives partial blobs). */
+declare function asFadeMeta(val: unknown): FadeMeta | null;
+/**
+ * Scan all `track:<dbId>:fade` keys in a scene's plugin_data and return one entry
+ * per valid fade. Unlike crossfade there is no grouping or both-present gate — a
+ * fade is intrinsically a single track.
+ */
+declare function parseFades(sceneData: Record<string, unknown>): FadeEntry[];
+/**
+ * Build a ONE-sided volume-automation curve for a fade over `bars` at `bpm`.
+ *
+ * - `gesture === 'build'` → flat at unity (0 dB). The compositional build in the
+ *   MIDI carries the fade; layering a volume ramp on top would double-fade.
+ * - `gesture === 'volume'` → an equal-power ramp identical to ONE half of
+ *   `buildCrossfadeVolumeCurves`: fade-out ≡ its `origin` curve (unity→floor),
+ *   fade-in ≡ its `target` curve (floor→unity). `sliderPos` sets WHERE the −3 dB
+ *   midpoint sits in time.
+ *
+ * Points span [0, durationSeconds] so the engine re-reads them each loop. Returns
+ * dB points for `host.setTrackVolumeAutomation`.
+ *
+ * @since SDK 2.28.0
+ */
+declare function buildFadeVolumeCurve(bars: number, bpm: number, direction: FadeDirection, sliderPos: number, gesture: FadeGesture, steps?: number): VolumeAutomationPoint[];
+/**
+ * Roles whose fades default to a `volume` (level) ramp — sustained/textural
+ * material that enters/leaves by level in real productions. Everything else
+ * defaults to `build` (the notes carry the fade).
+ *
+ * This is a UI default heuristic over role tokens, NOT the canonical role list
+ * (that lives in the app's instrument-classification + `host.getValidRoles()`).
+ * There is no textural↔articulated axis in the taxonomy, so this small curated
+ * subset lives next to its consumer (the fade modal/panels).
+ *
+ * @since SDK 2.28.0
+ */
+declare const TEXTURAL_ROLES: ReadonlySet<string>;
+/** Pick the default fade gesture for a track's role (textural → volume, else build). */
+declare function defaultFadeGesture(role: string | null | undefined): FadeGesture;
+
+/**
+ * FadeTrackRow — a transition "fade track": a single locked TrackRow with a
+ * direction badge (Fade in / Fade out) and a one-sided fade slider.
+ *
+ * A fade is a crossfade with one empty endpoint — a lone generated track that
+ * either enters (fade in, for a target-only track) or leaves (fade out, for an
+ * origin-only track) across the transition loop. Like a crossfade layer, the
+ * sound/generation controls are omitted (the SDK TrackRow is "controlled by
+ * omission"): no shuffle / Create / preset-pick / FX / drawer / inner-delete.
+ * What remains: per-track volume/pan/mute/solo and a single delete.
+ *
+ * The slider represents WHERE in the loop the fade sits (earlier ↔ later). Omit
+ * `onSliderChange` to render it read-only.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** The single (engine track) layer of a fade. */
+interface FadeLayer {
+    /** Engine track id of this fade's track (also the meter key). */
+    trackId: string;
+    /** Display name of this fade's (newly created) track. */
+    name: string;
+    /** Musical role (drives the auto gesture). */
+    role?: string;
+    /** Name of the SOURCE track this fade was seeded from (origin/target scene). */
+    sourceName?: string;
+    /** Human label of the copied preset/sound, shown in the caption. */
+    soundLabel?: string;
+    /** Playback state for this track. */
+    runtimeState: {
+        muted: boolean;
+        solo: boolean;
+        volume: number;
+        pan: number;
+    };
+}
+interface FadeTrackRowProps {
+    /** The lone fade track. */
+    layer: FadeLayer;
+    /** 'in' (enters across the loop) or 'out' (leaves across the loop). */
+    direction: FadeDirection;
+    /** How the fade is shaped — shown read-only (volume = level ramp, build = notes). */
+    gesture: FadeGesture;
+    /** Audio transition variant — relabels the badge (Stutter/Chopped/Delay). @since SDK 2.32.0 */
+    effect?: 'fade' | 'stutter' | 'chopped' | 'delay';
+    /** Fade position 0..1 — WHERE in time the fade sits. Defaults centered. */
+    sliderPos?: number;
+    /** Toggle mute. */
+    onMuteToggle: () => void;
+    /** Toggle solo. */
+    onSoloToggle: () => void;
+    /** Change the track's volume. */
+    onVolumeChange: (volume: number) => void;
+    /** Change the track's pan. */
+    onPanChange: (pan: number) => void;
+    /** Delete the fade. */
+    onDelete: () => void;
+    /** Move the fade point. Omit to render the slider read-only. */
+    onSliderChange?: (pos: number) => void;
+    /** Shared meter handle (welds a peak meter to the track). */
+    levels?: TrackLevelsHandle;
+    /** Left-border accent. Defaults to transition purple. */
+    accentColor?: string;
+}
+declare function FadeTrackRow({ layer, direction, gesture, effect, sliderPos, onMuteToggle, onSoloToggle, onVolumeChange, onPanChange, onDelete, onSliderChange, levels, accentColor, }: FadeTrackRowProps): React.ReactElement;
+
+/**
+ * FadeModal — "add a fade" picker for a transition scene.
+ *
+ * Shown only inside a `scene_type='transition'` scene. It self-fetches the FROM
+ * (origin) and TO (target) scenes' family tracks and diffs them by role to find
+ * ORPHANS — tracks with no counterpart on the other side:
+ *   - origin-only surplus → "Fade out" candidates (the track leaves)
+ *   - target-only surplus → "Fade in" candidates (the track enters)
+ * Tracks whose role is matched on both sides are crossfade territory and are NOT
+ * shown here. A source already used in a crossfade or a fade is hidden (via
+ * excludeSourceDbIds).
+ *
+ * The fade GESTURE (volume vs build) is auto-selected from the track's role and
+ * shown read-only — the user does not choose it. On confirm the modal hands the
+ * selection + direction + gesture to `onCreate`, which the panel implements
+ * (create one track, generate a chord-conforming part, copy the sound, apply a
+ * one-sided volume curve). `onCreate` should reject on failure so the modal can
+ * show it and stay open.
+ *
+ * @since SDK 2.28.0
+ */
+
+/** A picked orphan track handed to `onCreate`. */
+interface FadeSelection {
+    /** Source track DB id (selector for getTrackSound + seeding the part). */
+    dbId: string;
+    /** Display name (for the row caption). */
+    name: string;
+    /** Musical role of the source track (drives the auto gesture). */
+    role?: string;
+}
+interface FadeModalProps {
+    /** Scoped host — the modal calls listSceneFamilyTracks itself. */
+    host: PluginHost;
+    /** Controls visibility (the panel owns open/closed from its header button). */
+    open: boolean;
+    /** DB id of the transition's FROM (origin) scene. */
+    fromSceneId: string;
+    /** DB id of the transition's TO (target) scene. */
+    toSceneId: string;
+    /** Display name for the origin scene heading (optional). */
+    fromSceneName?: string;
+    /** Display name for the target scene heading (optional). */
+    toSceneName?: string;
+    /** Source-track DB ids already used in a crossfade OR a fade — hidden here. */
+    excludeSourceDbIds?: readonly string[];
+    /** Close handler (Escape, backdrop, Cancel, or after a successful create). */
+    onClose: () => void;
+    /** Build the fade. Should reject on failure so the modal shows it. */
+    onCreate: (selection: FadeSelection, direction: FadeDirection, gesture: FadeGesture) => Promise<void>;
+    /** data-testid prefix. */
+    testIdPrefix?: string;
+}
+declare function FadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: FadeModalProps): React.ReactElement | null;
+
 /**
  * ImportTrackModal — "import a track from another scene" picker (SDK component).
  *
@@ -2886,6 +3155,181 @@ interface CrossfadeModalProps {
 }
 declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
 
+/**
+ * TransitionDesigner — the per-panel transition staging board, rendered INLINE as
+ * a toggled view inside a generator panel (NOT a modal).
+ *
+ * The multi-row, persistent successor to {@link CrossfadeModal} + {@link FadeModal}:
+ * instead of opening a single-pair dialog ~20 times, the panel header gains a
+ * Tracks ⇄ Transition toggle; flipping to Transition replaces the panel's track
+ * list with this board. Playback is unaffected (the engine keeps playing the
+ * scene's tracks — they're just not shown until you toggle back). Shown only
+ * inside a `scene_type='transition'` scene and scoped to one panel family (a synth
+ * board shows only synth tracks — "drums can't crossfade to synth" is enforced
+ * structurally because each board asks its own family-scoped host).
+ *
+ * Two index-aligned, drag-reorderable columns: origin (scene A, left) and target
+ * (scene B, right). Row i pairs origin[i] with target[i]; the pairing derives the
+ * transition type (both → crossfade, origin-only → fade out, target-only → fade
+ * in). Insert a "gap" above a cell to push a track so it fades instead of
+ * crossfading with whatever sits opposite. The pool per column is the scene's
+ * family tracks MINUS sources already consumed by a committed crossfade/fade
+ * (`excludeSourceDbIds`).
+ *
+ * Per-row **Create** reuses the panel's EXISTING orchestration via `onCreateCrossfade`
+ * / `onCreateFade`. Creates run CONCURRENTLY — fire several at once, or **Create all**
+ * (a bounded pool). Each in-flight row shows its own progress bar and locks just its
+ * own cells; the rest of the board stays editable. On success the source leaves the
+ * pool (the panel updates `excludeSourceDbIds`) and the row collapses; deleting the
+ * committed crossfade/fade on the deck returns the source here. The staged
+ * arrangement persists to the transition scene's plugin_data so it survives toggles.
+ *
+ * @since SDK 2.29.0 (modal); inline toggle view + concurrent creation since 2.30.0.
+ */
+
+interface TransitionDesignerProps {
+    /** Scoped host — the board calls listSceneFamilyTracks / getSceneName itself. */
+    host: PluginHost;
+    /** DB id of the transition's FROM (origin) scene. */
+    fromSceneId: string;
+    /** DB id of the transition's TO (target) scene. */
+    toSceneId: string;
+    /** DB id of the transition scene itself — the staged draft is persisted here. */
+    transitionSceneId: string;
+    /**
+     * Source-track DB ids already consumed by a committed crossfade OR fade in this
+     * panel. Hidden from both columns so each source is used at most once; when the
+     * deck row is deleted the panel drops the id and the source reappears here.
+     */
+    excludeSourceDbIds?: readonly string[];
+    /**
+     * Build a crossfade pair — the panel's existing handler (create two tracks, one
+     * morphed clip, copy each preset). Should reject on failure. Safe to call
+     * concurrently.
+     */
+    onCreateCrossfade: (origin: CrossfadeSelection, target: CrossfadeSelection) => Promise<void>;
+    /** Build a one-sided fade — the panel's existing handler. Should reject on failure. */
+    onCreateFade: (selection: FadeSelection, direction: FadeDirection, gesture: FadeGesture) => Promise<void>;
+    /**
+     * Build an AUDIO-only one-sided transition (stutter / chopped / delay). When
+     * provided, one-sided rows render an effect selector; absent (MIDI panels) →
+     * one-sided rows stay plain fades. @since SDK 2.32.0
+     */
+    onCreateAudioTransition?: (selection: FadeSelection, direction: FadeDirection, effect: 'stutter' | 'chopped' | 'delay') => Promise<void>;
+    /** Short family label for the heading, e.g. "Synths". */
+    familyLabel?: string;
+    /** data-testid prefix. */
+    testIdPrefix?: string;
+}
+declare function TransitionDesigner({ host, fromSceneId, toSceneId, transitionSceneId, excludeSourceDbIds, onCreateCrossfade, onCreateFade, onCreateAudioTransition, familyLabel, testIdPrefix, }: TransitionDesignerProps): React.ReactElement;
+
+/**
+ * Transition Designer — pure helpers for the per-panel transition staging board.
+ *
+ * The designer is the multi-row, persistent successor to CrossfadeModal/FadeModal:
+ * it lays out ONE panel-family's origin (scene A) and target (scene B) source
+ * tracks as two index-aligned, drag-reorderable columns. Row i pairs the origin
+ * slot at index i with the target slot at index i, and the pairing DERIVES the
+ * transition type:
+ *   - both filled            → crossfade (morph A→B)
+ *   - origin filled, target blank → fade out (the track leaves)
+ *   - target filled, origin blank → fade in  (the track enters)
+ * A slot may be a source-track dbId or `null` (a blank spacer). Blanks let the
+ * user open a gap so a mid-list track becomes a fade instead of crossfading with
+ * whatever happens to sit opposite it (the CSV-style layout).
+ *
+ * The "available pool" per column is the scene's family tracks MINUS the sources
+ * already consumed by a committed crossfade/fade (excludeSourceDbIds). Creating a
+ * row reuses the panel's existing crossfade/fade orchestration; deleting the
+ * committed crossfade/fade on the deck returns its source to the pool.
+ *
+ * This module owns only the shape + the pure slot/row math so it can be unit
+ * tested without a DOM and can't drift across the three panels. The component
+ * (TransitionDesigner.tsx) owns the overlay, drag wiring, and persistence.
+ *
+ * @since SDK 2.29.0
+ */
+/**
+ * Persisted per-transition-scene draft: the two columns' slot orders. A slot is
+ * a source-track dbId, or `null` for a blank spacer (an intentional gap). Stored
+ * in the transition scene's plugin_data under {@link TRANSITION_DESIGNER_DRAFT_KEY};
+ * because plugin_data is scoped by (plugin_id, sceneId), each panel family keeps
+ * its own draft automatically.
+ */
+interface TransitionDesignerDraft {
+    /** Origin (scene A) column order — dbIds or `null` blanks. */
+    originOrder: (string | null)[];
+    /** Target (scene B) column order — dbIds or `null` blanks. */
+    targetOrder: (string | null)[];
+    /** Per one-sided-row audio effect, keyed by the source dbId. @since SDK 2.32.0 */
+    rowEffects?: Record<string, AudioEffect>;
+}
+/** scene-data key (under the transition scene) holding the staged draft. */
+declare const TRANSITION_DESIGNER_DRAFT_KEY = "transitionDesigner:draft";
+/** The transition a single aligned row represents (derived from its two slots). */
+type TransitionRowType = 'crossfade' | 'fade-out' | 'fade-in';
+/**
+ * Audio-only transition gesture for a ONE-SIDED (orphan) loop. `'fade'` is the
+ * default level ramp (works for any family); `stutter`/`chopped`/`delay` are
+ * audio panels only, surfaced via the row's effect selector when the panel
+ * passes `onCreateAudioTransition`. @since SDK 2.32.0
+ */
+type AudioEffect = 'fade' | 'stutter' | 'chopped' | 'delay';
+declare const AUDIO_EFFECTS: readonly AudioEffect[];
+declare const AUDIO_EFFECT_LABEL: Record<AudioEffect, string>;
+declare function asAudioEffect(v: unknown): AudioEffect | null;
+/** Derive a row's transition type from which slots are filled. `null` = empty row. */
+declare function rowType(hasOrigin: boolean, hasTarget: boolean): TransitionRowType | null;
+/** Narrow an unknown scene-data value to a TransitionDesignerDraft (defensive). */
+declare function asTransitionDesignerDraft(val: unknown): TransitionDesignerDraft | null;
+/**
+ * Reconcile a saved slot order against the current pool of available source ids:
+ * - keep saved ids still in the pool (in their saved position),
+ * - keep `null` blanks,
+ * - drop ids no longer in the pool (consumed by a created crossfade/fade, or the
+ *   source track was deleted) and any duplicates,
+ * - append pool ids missing from the saved order (newly added tracks) at the end.
+ *
+ * Pure; exported for unit testing.
+ */
+declare function reconcileSlots(saved: readonly (string | null)[] | undefined, poolIds: readonly string[]): (string | null)[];
+/** One assembled designer row: the two source dbIds (or `null`) + derived type. */
+interface DesignerRowSlots {
+    originId: string | null;
+    targetId: string | null;
+    type: TransitionRowType | null;
+}
+/** Zip two slot columns into index-aligned rows with their derived type. */
+declare function buildRowSlots(originSlots: readonly (string | null)[], targetSlots: readonly (string | null)[]): DesignerRowSlots[];
+/**
+ * Tidy the columns for persistence: drop rows where BOTH slots are blank (a
+ * meaningless gap) and trim trailing blanks per column. Returns clean columns
+ * suitable for {@link TransitionDesignerDraft}.
+ */
+declare function normalizeSlots(originSlots: readonly (string | null)[], targetSlots: readonly (string | null)[]): TransitionDesignerDraft;
+/** Pad a column with trailing `null`s up to `n` (so both columns render aligned). */
+declare function padSlots(slots: readonly (string | null)[], n: number): (string | null)[];
+/** Pad both columns to equal length (= the longer column). */
+declare function padPair(originSlots: readonly (string | null)[], targetSlots: readonly (string | null)[]): [(string | null)[], (string | null)[]];
+/** Shallow element-wise equality for two slot columns. */
+declare function slotsEqual(a: readonly (string | null)[], b: readonly (string | null)[]): boolean;
+/**
+ * Stable key identifying an in-flight create, derived from the row's SOURCE dbIds
+ * (not its row index) — so reordering or inserting a gap mid-create still maps the
+ * progress indicator to the right row, and concurrent creates never collide. dbIds
+ * are UUIDs, so `|` is a safe origin/target separator. `null` for an empty row.
+ *
+ * @since SDK 2.30.0
+ */
+declare function rowKey(row: DesignerRowSlots): string | null;
+/**
+ * The set of source dbIds referenced by a collection of in-flight {@link rowKey}s —
+ * used to lock those cells (no drag / gap edits) while their create runs.
+ *
+ * @since SDK 2.30.0
+ */
+declare function dbIdsFromKeys(keys: Iterable<string>): Set<string>;
+
 /**
  * ConfirmDialog — styled in-app confirmation modal (SDK component).
  *
@@ -3609,7 +4053,7 @@ declare function useSoundHistory(applySound: (trackId: string, descriptor: unkno
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.26.0";
+declare const PLUGIN_SDK_VERSION = "2.34.0";
 
 /**
  * FX Preset Definitions
@@ -3757,4 +4201,4 @@ interface PickTopKOptions {
  */
 declare function pickTopKWeighted<T>(scored: ReadonlyArray<ScoredCandidate<T>>, options?: PickTopKOptions): T | null;
 
-export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, type CrossfadeVolumeCurves, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginSkill, type PluginSkillInputSchema, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asCrossfadeMeta, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbToSlider, drawWaveform, formatConcurrentTracks, moveItem, parseCrossfadePairs, pickTopKWeighted, pitchToName, pxToCell, resizeNoteDuration, scorePromptMatch, sliderToDb, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };
+export { AUDIO_EFFECTS, AUDIO_EFFECT_LABEL, type AudioEffect, type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, ConfirmDialog, type ConfirmDialogProps, type CreateTrackOptions, type CrossfadeInpaintInput, type CrossfadeLayer, type CrossfadeMeta, CrossfadeModal, type CrossfadeModalProps, type CrossfadePairMeta, type CrossfadeSelection, type CrossfadeSlot, CrossfadeTrackRow, type CrossfadeTrackRowProps, type CrossfadeVolumeCurves, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, DRAG_DEAD_ZONE, type DeckBoundaryEvent, type DeckBoundaryListener, type DesignerRowSlots, DownloadPackButton, type DownloadPackButtonProps, type DownloadPackButtonVariant, type DrawerTab, type DrumKit, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, EQUAL_POWER_GAIN, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FadeDirection, type FadeEntry, type FadeGesture, type FadeLayer, type FadeMeta, FadeModal, type FadeModalProps, type FadeSelection, FadeTrackRow, type FadeTrackRowProps, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, GUTTER_W, type GeneratorPlugin, type GeneratorType, type ImportCandidateScene, type ImportCandidateTrack, ImportTrackModal, type ImportTrackModalProps, type InstrumentDescriptor, TrackDrawer as InstrumentDrawer, type TrackDrawerProps as InstrumentDrawerProps, type InstrumentSampler, type InstrumentZone, type LLMCandidate, type LLMContent, type LLMFunctionDeclaration, type LLMGenerationConfig, type LLMGenerationRequest, type LLMGenerationResult, type LLMPart, type LLMSystemInstruction, type LLMTool, type LLMToolUseRequest, type LLMToolUseResponse, type LLMUsageMetadata, LevelMeter, type LevelMeterProps, type ListAudioFilesOptions, type ListImportableTracksOptions, type MidiClipData, type MidiWriteResult, type MixInterpolation, Modal, type ModalProps, type MusicalContext, OffsetScrubber, type OffsetScrubberProps, PLUGIN_SDK_VERSION, PX_PER_BEAT, PanSlider, type PeakAnalysis, PianoRollEditor, type PianoRollEditorProps, type PickTopKOptions, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginSkill, type PluginSkillInputSchema, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackLevel, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, RESIZE_HANDLE_PX, ROW_HEIGHT, type ReadMidiClip, type ReadMidiResult, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, SamplePackCTACard, type SamplePackCTACardProps, type SamplePackCTACardStatus, type SamplePackCardInfo, type SavePluginPresetOptions, type SceneChangeListener, type SceneFamilyTrack, type ScoredCandidate, ScrollingWaveform, type ScrollingWaveformProps, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type SoundHistoryEntry, type StemType, type SynthesizeCuePointsOptions, TEXTURAL_ROLES, TRANSITION_DESIGNER_DRAFT_KEY, TrackDrawer, type TrackDrawerProps, type TrackFxDetailState, type TrackFxState, type TrackLevelsHandle, TrackMeterStrip, type TrackMeterStripProps, type TrackMeterView, TrackRow, type TrackRowDragProps, type TrackSoundHistory, type TrackSoundSnapshot, type TrackStateChangeListener, TransitionDesigner, type TransitionDesignerDraft, type TransitionDesignerProps, type TransitionRowType, type TransportEvent, type TransportEventListener, type UnsubscribeFn, type UseSoundHistoryOptions, type UseSoundHistoryResult, type UseTrackReorderOptions, type UseTrackReorderResult, type VolumeAutomationPoint, VolumeSlider, type WaveformPeaks, WaveformView, type WaveformViewProps, analyzeWavPeak, asAudioEffect, asCrossfadeMeta, asFadeMeta, asTransitionDesignerDraft, buildCrossfadeInpaintPrompt, buildCrossfadeVolumeCurves, buildFadeVolumeCurve, buildRowSlots, calculateTimeBasedTarget, cellToPx, centerScrollTop, computePeaks, dbIdsFromKeys, dbToSlider, defaultFadeGesture, drawWaveform, formatConcurrentTracks, hashString, moveItem, normalizeSlots, padPair, padSlots, parseCrossfadePairs, parseFades, pickTopKWeighted, pitchToName, pxToCell, reconcileSlots, resizeNoteDuration, rowKey, rowType, scorePromptMatch, sliderToDb, slotsEqual, soundIdentity, synthesizeCuePoints, tokenizePrompt, transposeNotes, useAnySolo, useSceneState, useSoundHistory, useTrackLevel, useTrackLevels, useTrackMeter, useTrackReorder, useTransportPlaying };