@signalsandsorcery/plugin-sdk 2.25.1 → 2.26.1

package/dist/index.d.mts

@@ -547,6 +547,11 @@ interface PluginHost {
         key: string;
         mode: string;
     } | null>;
+    /**
+     * Read a scene's human display name by db id (for labelling a crossfade's
+     * origin/target scenes). Optional — callers MUST null-check. @since SDK 2.26.0
+     */
+    getSceneName?(sceneDbId: string): Promise<string | null>;
     /** Subscribe to transport state changes. Returns unsubscribe function. */
     onTransportEvent(listener: TransportEventListener): UnsubscribeFn;
     /** Subscribe to deck boundary events. Returns unsubscribe function. */
@@ -2602,6 +2607,10 @@ interface CrossfadePairMeta {
     sliderPos: number;
     originDbId: string;
     targetDbId: string;
+    /** DB id of the ORIGIN source track (in the from scene) — drives the "used once" exclusion. */
+    originSourceDbId: string;
+    /** DB id of the TARGET source track (in the to scene). */
+    targetSourceDbId: string;
     originSourceName: string;
     originSoundLabel: string;
     targetSourceName: string;
@@ -2826,8 +2835,9 @@ declare function ImportTrackModal({ host, open, onClose, onImported, title, test
  *
  * 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.
+ * scene), in ANY order — the only constraint is same plugin/family (the picker is
+ * per-panel). A source track already used in a crossfade is hidden (via
+ * excludeSourceDbIds), so each source is used at most once.
  *
  * Self-fetching: given the scoped `host`, it calls `host.listSceneFamilyTracks`
  * for both scenes (ungated — a transition deliberately bridges different keys).
@@ -2845,7 +2855,7 @@ interface CrossfadeSelection {
     dbId: string;
     /** Display name (for the row caption). */
     name: string;
-    /** Musical role (same for both — enforced by the picker). */
+    /** Musical role of the source track (the panel uses the TARGET's for generation). */
     role?: string;
 }
 interface CrossfadeModalProps {
@@ -2861,6 +2871,12 @@ interface CrossfadeModalProps {
     fromSceneName?: string;
     /** Display name for the target scene heading (optional). */
     toSceneName?: string;
+    /**
+     * Source-track DB ids already used in a crossfade (origin + target of every
+     * existing pair in this panel). Hidden from BOTH dropdowns so each source is
+     * used at most once. @since SDK 2.26.0
+     */
+    excludeSourceDbIds?: readonly 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. */
@@ -2868,7 +2884,7 @@ interface CrossfadeModalProps {
     /** data-testid prefix. */
     testIdPrefix?: string;
 }
-declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
+declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
 
 /**
  * ConfirmDialog — styled in-app confirmation modal (SDK component).
@@ -3593,7 +3609,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.25.0";
+declare const PLUGIN_SDK_VERSION = "2.26.0";
 
 /**
  * FX Preset Definitions

package/dist/index.d.ts

@@ -547,6 +547,11 @@ interface PluginHost {
         key: string;
         mode: string;
     } | null>;
+    /**
+     * Read a scene's human display name by db id (for labelling a crossfade's
+     * origin/target scenes). Optional — callers MUST null-check. @since SDK 2.26.0
+     */
+    getSceneName?(sceneDbId: string): Promise<string | null>;
     /** Subscribe to transport state changes. Returns unsubscribe function. */
     onTransportEvent(listener: TransportEventListener): UnsubscribeFn;
     /** Subscribe to deck boundary events. Returns unsubscribe function. */
@@ -2602,6 +2607,10 @@ interface CrossfadePairMeta {
     sliderPos: number;
     originDbId: string;
     targetDbId: string;
+    /** DB id of the ORIGIN source track (in the from scene) — drives the "used once" exclusion. */
+    originSourceDbId: string;
+    /** DB id of the TARGET source track (in the to scene). */
+    targetSourceDbId: string;
     originSourceName: string;
     originSoundLabel: string;
     targetSourceName: string;
@@ -2826,8 +2835,9 @@ declare function ImportTrackModal({ host, open, onClose, onImported, title, test
  *
  * 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.
+ * scene), in ANY order — the only constraint is same plugin/family (the picker is
+ * per-panel). A source track already used in a crossfade is hidden (via
+ * excludeSourceDbIds), so each source is used at most once.
  *
  * Self-fetching: given the scoped `host`, it calls `host.listSceneFamilyTracks`
  * for both scenes (ungated — a transition deliberately bridges different keys).
@@ -2845,7 +2855,7 @@ interface CrossfadeSelection {
     dbId: string;
     /** Display name (for the row caption). */
     name: string;
-    /** Musical role (same for both — enforced by the picker). */
+    /** Musical role of the source track (the panel uses the TARGET's for generation). */
     role?: string;
 }
 interface CrossfadeModalProps {
@@ -2861,6 +2871,12 @@ interface CrossfadeModalProps {
     fromSceneName?: string;
     /** Display name for the target scene heading (optional). */
     toSceneName?: string;
+    /**
+     * Source-track DB ids already used in a crossfade (origin + target of every
+     * existing pair in this panel). Hidden from BOTH dropdowns so each source is
+     * used at most once. @since SDK 2.26.0
+     */
+    excludeSourceDbIds?: readonly 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. */
@@ -2868,7 +2884,7 @@ interface CrossfadeModalProps {
     /** data-testid prefix. */
     testIdPrefix?: string;
 }
-declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
+declare function CrossfadeModal({ host, open, fromSceneId, toSceneId, fromSceneName, toSceneName, excludeSourceDbIds, onClose, onCreate, testIdPrefix, }: CrossfadeModalProps): React.ReactElement | null;
 
 /**
  * ConfirmDialog — styled in-app confirmation modal (SDK component).
@@ -3593,7 +3609,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.25.0";
+declare const PLUGIN_SDK_VERSION = "2.26.0";
 
 /**
  * FX Preset Definitions

package/dist/index.js

@@ -2570,6 +2570,8 @@ function parseCrossfadePairs(sceneData) {
       sliderPos: g.origin.meta.sliderPos,
       originDbId: g.origin.dbId,
       targetDbId: g.target.dbId,
+      originSourceDbId: g.origin.meta.sourceTrackDbId,
+      targetSourceDbId: g.target.meta.sourceTrackDbId,
       originSourceName: g.origin.meta.sourceName,
       originSoundLabel: g.origin.meta.soundLabel,
       targetSourceName: g.target.meta.sourceName,
@@ -2845,6 +2847,7 @@ function CrossfadeModal({
   toSceneId,
   fromSceneName,
   toSceneName,
+  excludeSourceDbIds,
   onClose,
   onCreate,
   testIdPrefix = "crossfade-modal"
@@ -2854,6 +2857,8 @@ function CrossfadeModal({
   const [targetDbId, setTargetDbId] = (0, import_react12.useState)("");
   const [isCreating, setIsCreating] = (0, import_react12.useState)(false);
   const [error, setError] = (0, import_react12.useState)(null);
+  const [fromName, setFromName] = (0, import_react12.useState)(null);
+  const [toName, setToName] = (0, import_react12.useState)(null);
   const cancelRef = (0, import_react12.useRef)(null);
   const refresh = (0, import_react12.useCallback)(async () => {
     if (!host.listSceneFamilyTracks) {
@@ -2862,12 +2867,15 @@ function CrossfadeModal({
     }
     setLoad({ status: "loading" });
     try {
-      const [origin, target] = await Promise.all([
+      const [origin, target, fName, tName] = await Promise.all([
         host.listSceneFamilyTracks(fromSceneId),
-        host.listSceneFamilyTracks(toSceneId)
+        host.listSceneFamilyTracks(toSceneId),
+        host.getSceneName ? host.getSceneName(fromSceneId) : Promise.resolve(null),
+        host.getSceneName ? host.getSceneName(toSceneId) : Promise.resolve(null)
       ]);
+      setFromName(fName);
+      setToName(tName);
       setLoad({ status: "ready", origin, target });
-      setOriginDbId(origin[0]?.dbId ?? "");
     } catch (err) {
       setLoad({ status: "error", message: err instanceof Error ? err.message : "Failed to load tracks." });
     }
@@ -2881,21 +2889,26 @@ function CrossfadeModal({
       void refresh();
     }
   }, [open, refresh]);
-  const originTrack = (0, import_react12.useMemo)(
-    () => load.status === "ready" ? load.origin.find((t) => t.dbId === originDbId) ?? null : null,
-    [load, originDbId]
+  const excludeSet = (0, import_react12.useMemo)(() => new Set(excludeSourceDbIds ?? []), [excludeSourceDbIds]);
+  const originCandidates = (0, import_react12.useMemo)(
+    () => load.status === "ready" ? load.origin.filter((t) => !excludeSet.has(t.dbId)) : [],
+    [load, excludeSet]
   );
-  const originRole = originTrack?.role;
-  const targetCandidates = (0, import_react12.useMemo)(() => {
-    if (load.status !== "ready") return [];
-    if (!originRole) return load.target;
-    return load.target.filter((t) => t.role === originRole);
-  }, [load, originRole]);
+  const targetCandidates = (0, import_react12.useMemo)(
+    () => load.status === "ready" ? load.target.filter((t) => !excludeSet.has(t.dbId)) : [],
+    [load, excludeSet]
+  );
+  (0, import_react12.useEffect)(() => {
+    if (!originCandidates.some((t) => t.dbId === originDbId)) {
+      setOriginDbId(originCandidates[0]?.dbId ?? "");
+    }
+  }, [originCandidates, originDbId]);
   (0, import_react12.useEffect)(() => {
     if (!targetCandidates.some((t) => t.dbId === targetDbId)) {
       setTargetDbId(targetCandidates[0]?.dbId ?? "");
     }
   }, [targetCandidates, targetDbId]);
+  const originTrack = originCandidates.find((t) => t.dbId === originDbId) ?? null;
   const targetTrack = targetCandidates.find((t) => t.dbId === targetDbId) ?? null;
   const canCreate = !isCreating && !!originTrack && !!targetTrack;
   const handleClose = (0, import_react12.useCallback)(() => {
@@ -2916,6 +2929,8 @@ function CrossfadeModal({
       setIsCreating(false);
     }
   }, [originTrack, targetTrack, onCreate, onClose]);
+  const fromLabel = fromName ?? fromSceneName ?? null;
+  const toLabel = toName ?? toSceneName ?? null;
   if (!open) return null;
   return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(Modal, { open, onClose: handleClose, testIdPrefix, initialFocusRef: cancelRef, children: /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(
     "div",
@@ -2928,24 +2943,31 @@ function CrossfadeModal({
         /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("p", { className: "text-[11px] text-sas-muted leading-relaxed", children: [
           "Bridge a track from",
           " ",
-          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: fromSceneName ?? "the origin scene" }),
+          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: fromLabel ?? "the origin scene" }),
           " into one from",
           " ",
-          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: toSceneName ?? "the target scene" }),
+          /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-sas-text", children: toLabel ?? "the target scene" }),
           ". Both layers share one generated part; each keeps its own preset."
         ] }),
         load.status === "loading" && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { className: "text-xs text-sas-muted py-4 text-center", children: "Loading tracks\u2026" }),
         load.status === "error" && /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { className: "text-xs text-sas-danger py-4 text-center", children: load.message }),
-        load.status === "ready" && (load.origin.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
+        load.status === "ready" && (originCandidates.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(
           "div",
           {
             className: "text-xs text-sas-muted py-4 text-center",
             "data-testid": `${testIdPrefix}-empty-origin`,
-            children: "No matching tracks in the origin scene. Add one there first."
+            children: [
+              "No available tracks in ",
+              fromLabel ?? "the origin scene",
+              ". Add one (or free one from another crossfade) first."
+            ]
           }
         ) : /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)(import_jsx_runtime14.Fragment, { children: [
           /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("label", { className: "block", children: [
-            /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("span", { className: "text-[10px] uppercase tracking-wide text-sas-muted", children: "Origin (top)" }),
+            /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("span", { className: "text-[10px] uppercase tracking-wide text-sas-muted", children: [
+              "Origin ",
+              fromLabel ? `(${fromLabel})` : "(top)"
+            ] }),
             /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
               "select",
               {
@@ -2954,7 +2976,7 @@ function CrossfadeModal({
                 onChange: (e) => setOriginDbId(e.target.value),
                 disabled: isCreating,
                 className: "sas-input w-full mt-0.5 text-xs",
-                children: load.origin.map((t) => /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("option", { value: t.dbId, children: [
+                children: originCandidates.map((t) => /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("option", { value: t.dbId, children: [
                   t.name,
                   t.role ? ` \xB7 ${t.role}` : ""
                 ] }, t.dbId))
@@ -2963,13 +2985,13 @@ function CrossfadeModal({
           ] }),
           /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("label", { className: "block", children: [
             /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("span", { className: "text-[10px] uppercase tracking-wide text-sas-muted", children: [
-              "Target (bottom)",
-              originRole ? ` \xB7 ${originRole}` : ""
+              "Target ",
+              toLabel ? `(${toLabel})` : "(bottom)"
             ] }),
             targetCandidates.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime14.jsxs)("div", { className: "text-xs text-sas-danger mt-0.5", "data-testid": `${testIdPrefix}-empty-target`, children: [
-              "No ",
-              originRole ?? "matching",
-              " track in the target scene to crossfade into."
+              "No available tracks in ",
+              toLabel ?? "the target scene",
+              " to crossfade into."
             ] }) : /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
               "select",
               {
@@ -3888,7 +3910,7 @@ function useTrackReorder({
 }
 
 // src/constants/sdk-version.ts
-var PLUGIN_SDK_VERSION = "2.25.0";
+var PLUGIN_SDK_VERSION = "2.26.0";
 
 // src/utils/format-concurrent-tracks.ts
 function formatConcurrentTracks(ctx) {