cabbage-react 1.0.47 → 1.0.49

package/dist/cabbage/cabbage.d.ts

@@ -212,6 +212,35 @@ export class Cabbage {
      * @param {Object|null} vscode - VS Code API object (null for plugin mode)
      * @param {Object} additionalData - Additional data to include in the command
      */
-    static sendCustomCommand(command: string, vscode?: Object | null, additionalData?: Object): void;
+    /**
+     * Register a listener for incoming messages from the Cabbage backend.
+     *
+     * Abstracts the two environments so that the same UI code works everywhere:
+     * - **VS Code (iframe relay)**: messages arrive as window `message` events
+     * - **Native plugin (DAW)**: messages arrive via `window.hostMessageCallback`
+     *
+     * @param {function(Object): void} callback - Called with the message object.
+     *   Common message shapes:
+     *   - `{ command: "parameterChange", data: { paramIdx, value } }` (data may be top-level or nested)
+     *   - `{ command: "widgetUpdate", id, value }` (from cabbageSetValue / cabbageSet)
+     *   - `{ command: "widgetUpdate", id, widgetJson }` (full widget update)
+     *   - `{ command: "channelDataUpdate", data: { channel, value } }`
+     * @returns {function(): void} Cleanup function — call it when the UI is torn down.
+     *
+     * @example <caption>Vanilla HTML</caption>
+     * import { Cabbage } from './cabbage/cabbage.js';
+     * Cabbage.addMessageListener((msg) => {
+     *   const data = msg.data ?? msg;
+     *   if (msg.command === 'parameterChange') { ... }
+     * });
+     *
+     * @example <caption>Svelte</caption>
+     * import { onMount, onDestroy } from 'svelte';
+     * let remove;
+     * onMount(() => { remove = Cabbage.addMessageListener((msg) => { ... }); });
+     * onDestroy(() => remove?.());
+     */
+    static addMessageListener(callback: (arg0: Object) => void): () => void;
+    static sendCustomCommand(command: any, vscode?: null, additionalData?: {}): void;
 }
 //# sourceMappingURL=cabbage.d.ts.map

package/dist/cabbage/cabbage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cabbage.d.ts","sourceRoot":"","sources":["../../src/cabbage/cabbage.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH;IACC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oDALG;QAAqB,OAAO,EAApB,MAAM;QACc,KAAK,EAAzB,MAAM,GAAC,MAAM;QACC,OAAO;KAC7B,WAAQ,MAAM,GAAC,IAAI,QAyBrB;IAED;;;;;OAKG;IACH,8BAHW,MAAM,GAAC,IAAI,mBACX,MAAM,QAIhB;IACD;;;;;;;OAOG;IACH,yCALW,MAAM,aACN,MAAM,aACN,MAAM,WACN,MAAM,GAAC,IAAI,QA+BrB;IAED;;;;;;OAMG;IACH,uCAJW,MAAM,aACN,MAAM,aACN,MAAM,QAE8C;IAE/D;;;;;;;;;OASG;IACH,qCAPW,MAAM,GAAC,IAAI,WACX,MAAM,YAEd;QAAyB,SAAS;QACT,OAAO;QACN,uBAAuB;KACnD,QA4BA;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,GAAC,IAAI,OACX,MAAM,QACN,MAAM,QAwBhB;IAED;;;;;;;;;;;OAWG;IACH,4BAPW,MAAM,UACN,MAAM,WACN,MAAM,QA4BhB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,kCANW,OAAO,QAUjB;IAED;;;;;;OAMG;IACH,gCAJW,MAAM,QACN,MAAM,GAAC,MAAM,WACb,MAAM,GAAC,IAAI,QAqCrB;IAED;;;;;;OAMG;IACH,gCAiBC;IAED;;;;;;OAMG;IACH,kCAJW,MAAM,WACN,MAAM,GAAC,IAAI,mBACX,MAAM,QAiChB;CACD"}
+{"version":3,"file":"cabbage.d.ts","sourceRoot":"","sources":["../../src/cabbage/cabbage.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH;IACC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oDALG;QAAqB,OAAO,EAApB,MAAM;QACc,KAAK,EAAzB,MAAM,GAAC,MAAM;QACC,OAAO;KAC7B,WAAQ,MAAM,GAAC,IAAI,QA2BrB;IAED;;;;;OAKG;IACH,8BAHW,MAAM,GAAC,IAAI,mBACX,MAAM,QAIhB;IACD;;;;;;;OAOG;IACH,yCALW,MAAM,aACN,MAAM,aACN,MAAM,WACN,MAAM,GAAC,IAAI,QAiCrB;IAED;;;;;;OAMG;IACH,uCAJW,MAAM,aACN,MAAM,aACN,MAAM,QAE8C;IAE/D;;;;;;;;;OASG;IACH,qCAPW,MAAM,GAAC,IAAI,WACX,MAAM,YAEd;QAAyB,SAAS;QACT,OAAO;QACN,uBAAuB;KACnD,QA8BA;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,GAAC,IAAI,OACX,MAAM,QACN,MAAM,QA0BhB;IAED;;;;;;;;;;;OAWG;IACH,4BAPW,MAAM,UACN,MAAM,WACN,MAAM,QA8BhB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,kCANW,OAAO,QAUjB;IAED;;;;;;OAMG;IACH,gCAJW,MAAM,QACN,MAAM,GAAC,MAAM,WACb,MAAM,GAAC,IAAI,QAuCrB;IAED;;;;;;OAMG;IACH,gCAmBC;IAED;;;;;;OAMG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,oCArBW,CAAS,IAAM,EAAN,MAAM,KAAG,IAAI,GAMpB,MAAY,IAAI,CAkC5B;IAED,iFAiCC;CACD"}

package/dist/hooks/useCabbageMessage.d.ts

@@ -1,10 +1,11 @@
 /**
- * Custom hook to get a message from Cabbage backend.
+ * Custom hook to get the latest message for a specific type from Cabbage backend.
  * This hook listens to messages sent from the backend and updates the local state
  * whenever new data is received.
- * @param messageType
+ * @param messageType - The value of the `type` property in the incoming message object to listen for.
+ * @param onMessage - Callback fires immediately (synchronous - bypasses state batching)
  */
-export declare const useCabbageMessage: <T>(messageType: string) => {
-    data: T | undefined;
+export declare const useCabbageMessage: <T>(messageType: string, onMessage?: (message: T) => void) => {
+    message: T | undefined;
 };
 //# sourceMappingURL=useCabbageMessage.d.ts.map

package/dist/hooks/useCabbageMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCabbageMessage.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageMessage.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,eAAe,MAAM;;CA8BvD,CAAC"}
+{"version":3,"file":"useCabbageMessage.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageMessage.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,eACrB,MAAM,cACP,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI;;CA0BhC,CAAC"}

package/dist/hooks/useCabbageProperties.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCabbageProperties.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageProperties.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,cAAe,MAAM;;CAgCrD,CAAC"}
+{"version":3,"file":"useCabbageProperties.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageProperties.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,cAAe,MAAM;;CA8BrD,CAAC"}

package/dist/hooks/useCabbageState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCabbageState.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageState.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,aACrB,MAAM,YACR,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,UAAU;;sBAOb,CAAC;CA6FnC,CAAC"}
+{"version":3,"file":"useCabbageState.d.ts","sourceRoot":"","sources":["../../src/hooks/useCabbageState.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,aACrB,MAAM,YACR,OAAO,GAAG,OAAO,GAAG,KAAK,GAAG,UAAU;;sBAOb,CAAC;CA2FnC,CAAC"}

package/dist/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("react");class M{static sendControlData({channel:o,value:s,gesture:a="complete"},n=null){const e={command:"controlData",channel:o,value:s,gesture:a};n!==null?n.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static isReadyToLoad(o=null,s={}){this.sendCustomCommand("isReadyToLoad",o)}static sendMidiMessageFromUI(o,s,a,n=null){var e={statusByte:o,dataByte1:s,dataByte2:a};const r={command:"midiMessage",obj:JSON.stringify(e)};n!==null?n.postMessage(r):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(r):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",r)}static MidiMessageFromHost(o,s,a){}static triggerFileOpenDialog(o,s,a={}){var n={channel:s,directory:a.directory||"",filters:a.filters||"*",openAtLastKnownLocation:a.openAtLastKnownLocation!==void 0?a.openAtLastKnownLocation:!0};const e={command:"fileOpen",obj:JSON.stringify(n)};o!==null?o.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static openUrl(o,s,a){var n={url:s,file:a};const e={command:"openUrl",obj:JSON.stringify(n)};o!==null?o.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static requestResize(o,s,a=null){const n={command:"requestResize",width:o,height:s};if(a!==null){console.warn("Cabbage: requestResize is not supported in VS Code extension mode");return}else typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(n):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",n)}static consumeKeypresses(o){typeof window.consumeKeypresses=="function"&&window.consumeKeypresses(o)}static sendChannelData(o,s,a=null){var n={channel:o};if(typeof s=="string")n.stringData=s;else if(typeof s=="number")n.floatData=s;else{console.warn("Cabbage: sendChannelData received unsupported data type:",typeof s);return}const e={command:"channelData",obj:JSON.stringify(n)};a!==null?a.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static sendWidgetUpdate(o,s=null){const a={command:"widgetStateUpdate",obj:JSON.stringify(CabbageUtils.sanitizeForEditor(o))};s!==null?s.postMessage(a):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(a):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",a)}static sendCustomCommand(o,s=null,a={}){const n={command:o,text:JSON.stringify(a)};if(s!==null)s.postMessage(n);else if(typeof window.sendMessageFromUI=="function")try{const e=window.sendMessageFromUI(n)}catch(e){console.error("Cabbage: sendMessageFromUI threw error:",e),console.error("Cabbage: Error stack:",e.stack)}else console.error("Cabbage: window.sendMessageFromUI is not available yet. Message:",n),console.error("Cabbage: typeof window.sendMessageFromUI:",typeof window.sendMessageFromUI),console.error("Cabbage: window.sendMessageFromUI value:",window.sendMessageFromUI)}}const C=i=>{const[o,s]=l.useState();return l.useEffect(()=>{const a=n=>{const{id:e,widgetJson:r,command:w}=n.data;if(e===i&&r&&w==="widgetUpdate"){const t=JSON.parse(r);console.log(`[Cabbage-React] Received properties for channelId: ${e}`,t),s(t)}};return window.addEventListener("message",a),()=>{window.removeEventListener("message",a)}},[]),{properties:o}},y=(i,o="complete")=>{const{properties:s}=C(i),[a,n]=l.useState(),[e,r]=l.useState(),w=t=>{n(t),M.sendControlData({channel:i,value:t,gesture:o})};return l.useEffect(()=>{var u;const t=s==null?void 0:s.channels.find(d=>d.id===i);if(!t)return;const g=t.parameterIndex;if(e===void 0&&g!==void 0&&(console.log(`[Cabbage-React] Received parameterIndex for channelId: ${t.id}`,g),r(g)),a!==void 0)return;const c=(u=t.range)==null?void 0:u.value;c!=null&&(console.log(`[Cabbage-React] Received initial value for channelId: ${t.id}`,c),n(c))},[s]),l.useEffect(()=>{const t=g=>{var u;const{command:c}=g.data;if(c==="parameterChange"){const{value:d,paramIdx:m}=g.data.data;if(m!==e||d===null)return;console.log(`[Cabbage-React] Received parameterChange for parameterIndex: ${m}`,d),n(d)}else if(c==="batchWidgetUpdate"){const d=g.data.widgets,m=d==null?void 0:d.find(b=>b.id===i);if(!m)return;const f=JSON.parse(m.widgetJson).channels.find(b=>b.id===i),p=(u=f==null?void 0:f.range)==null?void 0:u.value;console.log(`[Cabbage-React] Received batch widget update for channelId: ${m.id}`,p),n(p)}};return window.addEventListener("message",t),()=>{window.removeEventListener("message",t)}},[e]),{value:a,setValue:w}},I=i=>{const[o,s]=l.useState();return l.useEffect(()=>{const a=n=>{const{data:e,type:r}=n;if(e&&r==="message"){if(e.type!==i)return;console.log(`[Cabbage-React] Received data for messageType: ${e.type}`,e),s(e)}};return window.addEventListener("message",a),()=>{window.removeEventListener("message",a)}},[]),{data:o}};exports.Cabbage=M;exports.useCabbageMessage=I;exports.useCabbageProperties=C;exports.useCabbageState=y;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("react");class M{static sendControlData({channel:s,value:e,gesture:a="complete"},o=null){const n={command:"controlData",channel:s,value:e,gesture:a};o!==null?o.postMessage(n):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(n):window.parent!==window?window.parent.postMessage(n,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",n)}static isReadyToLoad(s=null,e={}){this.sendCustomCommand("isReadyToLoad",s)}static sendMidiMessageFromUI(s,e,a,o=null){var n={statusByte:s,dataByte1:e,dataByte2:a};const t={command:"midiMessage",obj:JSON.stringify(n)};o!==null?o.postMessage(t):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(t):window.parent!==window?window.parent.postMessage(t,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",t)}static MidiMessageFromHost(s,e,a){}static triggerFileOpenDialog(s,e,a={}){var o={channel:e,directory:a.directory||"",filters:a.filters||"*",openAtLastKnownLocation:a.openAtLastKnownLocation!==void 0?a.openAtLastKnownLocation:!0};const n={command:"fileOpen",obj:JSON.stringify(o)};s!==null?s.postMessage(n):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(n):window.parent!==window?window.parent.postMessage(n,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",n)}static openUrl(s,e,a){var o={url:e,file:a};const n={command:"openUrl",obj:JSON.stringify(o)};s!==null?s.postMessage(n):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(n):window.parent!==window?window.parent.postMessage(n,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",n)}static requestResize(s,e,a=null){const o={command:"requestResize",width:s,height:e};if(a!==null){console.warn("Cabbage: requestResize is not supported in VS Code extension mode");return}else typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(o):window.parent!==window?window.parent.postMessage(o,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",o)}static consumeKeypresses(s){typeof window.consumeKeypresses=="function"&&window.consumeKeypresses(s)}static sendChannelData(s,e,a=null){var o={channel:s};if(typeof e=="string")o.stringData=e;else if(typeof e=="number")o.floatData=e;else{console.warn("Cabbage: sendChannelData received unsupported data type:",typeof e);return}const n={command:"channelData",obj:JSON.stringify(o)};a!==null?a.postMessage(n):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(n):window.parent!==window?window.parent.postMessage(n,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",n)}static sendWidgetUpdate(s,e=null){const a={command:"widgetStateUpdate",obj:JSON.stringify(CabbageUtils.sanitizeForEditor(s))};e!==null?e.postMessage(a):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(a):window.parent!==window?window.parent.postMessage(a,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",a)}static addMessageListener(s){const e=a=>{a.source!==window&&s(a.data)};return window.addEventListener("message",e),window.hostMessageCallback=s,()=>{window.removeEventListener("message",e),window.hostMessageCallback===s&&(window.hostMessageCallback=null)}}static sendCustomCommand(s,e=null,a={}){const o={command:s,text:JSON.stringify(a)};if(e!==null)e.postMessage(o);else if(typeof window.sendMessageFromUI=="function")try{const n=window.sendMessageFromUI(o)}catch(n){console.error("Cabbage: sendMessageFromUI threw error:",n),console.error("Cabbage: Error stack:",n.stack)}else window.parent!==window?window.parent.postMessage(o,"*"):(console.error("Cabbage: window.sendMessageFromUI is not available yet. Message:",o),console.error("Cabbage: typeof window.sendMessageFromUI:",typeof window.sendMessageFromUI),console.error("Cabbage: window.sendMessageFromUI value:",window.sendMessageFromUI))}}const C=r=>{const[s,e]=l.useState();return l.useEffect(()=>{const a=o=>{const{id:n,widgetJson:t,command:m}=o.data;if(n===r&&t&&m==="widgetUpdate"){const i=JSON.parse(t);console.log(`[Cabbage-React] Received properties for channelId: ${n}`,i),e(i)}};return window.addEventListener("message",a),()=>window.removeEventListener("message",a)},[]),{properties:s}},y=(r,s="complete")=>{const{properties:e}=C(r),[a,o]=l.useState(),[n,t]=l.useState(),m=i=>{o(i),M.sendControlData({channel:r,value:i,gesture:s})};return l.useEffect(()=>{var f;const i=e==null?void 0:e.channels.find(d=>d.id===r);if(!i)return;const g=i.parameterIndex;if(n===void 0&&g!==void 0&&(console.log(`[Cabbage-React] Received parameterIndex for channelId: ${i.id}`,g),t(g)),a!==void 0)return;const w=(f=i.range)==null?void 0:f.value;w!=null&&(console.log(`[Cabbage-React] Received initial value for channelId: ${i.id}`,w),o(w))},[e]),l.useEffect(()=>{const i=g=>{var f;const{command:w}=g.data;if(w==="parameterChange"){const{value:d,paramIdx:c}=g.data.data;if(c!==n||d===null)return;console.log(`[Cabbage-React] Received parameterChange for parameterIndex: ${c}`,d),o(d)}else if(w==="batchWidgetUpdate"){const d=g.data.widgets,c=d==null?void 0:d.find(p=>p.id===r);if(!c)return;const u=JSON.parse(c.widgetJson).channels.find(p=>p.id===r),b=(f=u==null?void 0:u.range)==null?void 0:f.value;console.log(`[Cabbage-React] Received batch widget update for channelId: ${c.id}`,b),o(b)}};return window.addEventListener("message",i),()=>window.removeEventListener("message",i)},[n]),{value:a,setValue:m}},I=(r,s)=>{const[e,a]=l.useState();return l.useEffect(()=>{const o=n=>{const{data:t,type:m}=n;!t||m!=="message"||t.type===r&&(console.log(`[Cabbage-React] Received data for messageType: ${t.type}`,t),s&&s(t),a(t))};return window.addEventListener("message",o),()=>window.removeEventListener("message",o)},[r,s]),{message:e}};exports.Cabbage=M;exports.useCabbageMessage=I;exports.useCabbageProperties=C;exports.useCabbageState=y;

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { useState as w, useEffect as f } from "react";
-class y {
+import { useState as f, useEffect as p } from "react";
+class C {
   /**
    * Send a widget value change to the Cabbage backend.
    *
@@ -20,16 +20,16 @@ class y {
    * @param {string} [data.gesture="complete"] - The gesture type: "begin" (start of interaction), "value" (during interaction), "end" (end of continuous interaction), or "complete" (discrete action e.g. button click).
    * @param {Object|null} vscode - VS Code API object (null for plugin mode)
    */
-  static sendControlData({ channel: o, value: s, gesture: a = "complete" }, n = null) {
-    const e = {
+  static sendControlData({ channel: s, value: e, gesture: n = "complete" }, o = null) {
+    const a = {
       command: "controlData",
-      channel: o,
-      value: s,
-      gesture: a
+      channel: s,
+      value: e,
+      gesture: n
     };
-    n !== null ? n.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : console.error(
+    o !== null ? o.postMessage(a) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(a) : window.parent !== window ? window.parent.postMessage(a, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
-      e
+      a
     );
   }
   /**
@@ -38,8 +38,8 @@ class y {
    * @param {Object|null} vscode - VS Code API object (null for plugin mode)
    * @param {Object} additionalData - Additional initialization data
    */
-  static isReadyToLoad(o = null, s = {}) {
-    this.sendCustomCommand("isReadyToLoad", o);
+  static isReadyToLoad(s = null, e = {}) {
+    this.sendCustomCommand("isReadyToLoad", s);
   }
   /**
    * Send a MIDI message from the UI to the Cabbage backend.
@@ -49,19 +49,19 @@ class y {
    * @param {number} dataByte2 - Second MIDI data byte
    * @param {Object|null} vscode - VS Code API object (null for plugin mode)
    */
-  static sendMidiMessageFromUI(o, s, a, n = null) {
-    var e = {
-      statusByte: o,
-      dataByte1: s,
-      dataByte2: a
+  static sendMidiMessageFromUI(s, e, n, o = null) {
+    var a = {
+      statusByte: s,
+      dataByte1: e,
+      dataByte2: n
     };
-    const r = {
+    const t = {
       command: "midiMessage",
-      obj: JSON.stringify(e)
+      obj: JSON.stringify(a)
     };
-    n !== null ? n.postMessage(r) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(r) : console.error(
+    o !== null ? o.postMessage(t) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(t) : window.parent !== window ? window.parent.postMessage(t, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
-      r
+      t
     );
   }
   /**
@@ -71,7 +71,7 @@ class y {
    * @param {number} dataByte1 - First MIDI data byte
    * @param {number} dataByte2 - Second MIDI data byte
    */
-  static MidiMessageFromHost(o, s, a) {
+  static MidiMessageFromHost(s, e, n) {
   }
   /**
    * Trigger a native file open dialog for file selection widgets.
@@ -83,20 +83,20 @@ class y {
    * @param {string} [options.filters="*"] - File filters (e.g., "*.wav;*.aiff")
    * @param {boolean} [options.openAtLastKnownLocation=true] - Whether to open at last known location
    */
-  static triggerFileOpenDialog(o, s, a = {}) {
-    var n = {
-      channel: s,
-      directory: a.directory || "",
-      filters: a.filters || "*",
-      openAtLastKnownLocation: a.openAtLastKnownLocation !== void 0 ? a.openAtLastKnownLocation : !0
+  static triggerFileOpenDialog(s, e, n = {}) {
+    var o = {
+      channel: e,
+      directory: n.directory || "",
+      filters: n.filters || "*",
+      openAtLastKnownLocation: n.openAtLastKnownLocation !== void 0 ? n.openAtLastKnownLocation : !0
     };
-    const e = {
+    const a = {
       command: "fileOpen",
-      obj: JSON.stringify(n)
+      obj: JSON.stringify(o)
     };
-    o !== null ? o.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : console.error(
+    s !== null ? s.postMessage(a) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(a) : window.parent !== window ? window.parent.postMessage(a, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
-      e
+      a
     );
   }
   /**
@@ -106,18 +106,18 @@ class y {
    * @param {string} url - URL to open
    * @param {string} file - File path to open
    */
-  static openUrl(o, s, a) {
-    var n = {
-      url: s,
-      file: a
+  static openUrl(s, e, n) {
+    var o = {
+      url: e,
+      file: n
     };
-    const e = {
+    const a = {
       command: "openUrl",
-      obj: JSON.stringify(n)
+      obj: JSON.stringify(o)
     };
-    o !== null ? o.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : console.error(
+    s !== null ? s.postMessage(a) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(a) : window.parent !== window ? window.parent.postMessage(a, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
-      e
+      a
     );
   }
   /**
@@ -132,21 +132,21 @@ class y {
    * The response will be sent via hostMessageCallback with:
    * {command: "resizeResponse", accepted: boolean, width: number, height: number}
    */
-  static requestResize(o, s, a = null) {
-    const n = {
+  static requestResize(s, e, n = null) {
+    const o = {
       command: "requestResize",
-      width: o,
-      height: s
+      width: s,
+      height: e
     };
-    if (a !== null) {
+    if (n !== null) {
       console.warn(
         "Cabbage: requestResize is not supported in VS Code extension mode"
       );
       return;
     } else
-      typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(n) : console.error(
+      typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(o) : window.parent !== window ? window.parent.postMessage(o, "*") : console.error(
         "Cabbage: window.sendMessageFromUI is not available. Message:",
-        n
+        o
       );
   }
   /**
@@ -168,8 +168,8 @@ class y {
    * myCustomEditor.addEventListener('focus', () => Cabbage.consumeKeypresses(true));
    * myCustomEditor.addEventListener('blur',  () => Cabbage.consumeKeypresses(false));
    */
-  static consumeKeypresses(o) {
-    typeof window.consumeKeypresses == "function" && window.consumeKeypresses(o);
+  static consumeKeypresses(s) {
+    typeof window.consumeKeypresses == "function" && window.consumeKeypresses(s);
   }
   /**
    * Send channel data directly to Csound without DAW automation involvement.
@@ -178,28 +178,28 @@ class y {
    * @param {number|string} data - The data to send (number or string)
    * @param {Object|null} vscode - VS Code API object (null for plugin mode)
    */
-  static sendChannelData(o, s, a = null) {
-    var n = {
-      channel: o
+  static sendChannelData(s, e, n = null) {
+    var o = {
+      channel: s
     };
-    if (typeof s == "string")
-      n.stringData = s;
-    else if (typeof s == "number")
-      n.floatData = s;
+    if (typeof e == "string")
+      o.stringData = e;
+    else if (typeof e == "number")
+      o.floatData = e;
     else {
       console.warn(
         "Cabbage: sendChannelData received unsupported data type:",
-        typeof s
+        typeof e
       );
       return;
     }
-    const e = {
+    const a = {
       command: "channelData",
-      obj: JSON.stringify(n)
+      obj: JSON.stringify(o)
     };
-    a !== null ? a.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : console.error(
+    n !== null ? n.postMessage(a) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(a) : window.parent !== window ? window.parent.postMessage(a, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
-      e
+      a
     );
   }
   /**
@@ -209,14 +209,14 @@ class y {
    * @param {Object} widget - The widget configuration object to update
    * @param {Object|null} vscode - VS Code API object (null for plugin mode)
    */
-  static sendWidgetUpdate(o, s = null) {
-    const a = {
+  static sendWidgetUpdate(s, e = null) {
+    const n = {
       command: "widgetStateUpdate",
-      obj: JSON.stringify(CabbageUtils.sanitizeForEditor(o))
+      obj: JSON.stringify(CabbageUtils.sanitizeForEditor(s))
     };
-    s !== null ? s.postMessage(a) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(a) : console.error(
+    e !== null ? e.postMessage(n) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(n) : window.parent !== window ? window.parent.postMessage(n, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
-      a
+      n
     );
   }
   /**
@@ -226,128 +226,152 @@ class y {
    * @param {Object|null} vscode - VS Code API object (null for plugin mode)
    * @param {Object} additionalData - Additional data to include in the command
    */
-  static sendCustomCommand(o, s = null, a = {}) {
-    const n = {
-      command: o,
-      text: JSON.stringify(a)
+  /**
+   * Register a listener for incoming messages from the Cabbage backend.
+   *
+   * Abstracts the two environments so that the same UI code works everywhere:
+   * - **VS Code (iframe relay)**: messages arrive as window `message` events
+   * - **Native plugin (DAW)**: messages arrive via `window.hostMessageCallback`
+   *
+   * @param {function(Object): void} callback - Called with the message object.
+   *   Common message shapes:
+   *   - `{ command: "parameterChange", data: { paramIdx, value } }` (data may be top-level or nested)
+   *   - `{ command: "widgetUpdate", id, value }` (from cabbageSetValue / cabbageSet)
+   *   - `{ command: "widgetUpdate", id, widgetJson }` (full widget update)
+   *   - `{ command: "channelDataUpdate", data: { channel, value } }`
+   * @returns {function(): void} Cleanup function — call it when the UI is torn down.
+   *
+   * @example <caption>Vanilla HTML</caption>
+   * import { Cabbage } from './cabbage/cabbage.js';
+   * Cabbage.addMessageListener((msg) => {
+   *   const data = msg.data ?? msg;
+   *   if (msg.command === 'parameterChange') { ... }
+   * });
+   *
+   * @example <caption>Svelte</caption>
+   * import { onMount, onDestroy } from 'svelte';
+   * let remove;
+   * onMount(() => { remove = Cabbage.addMessageListener((msg) => { ... }); });
+   * onDestroy(() => remove?.());
+   */
+  static addMessageListener(s) {
+    const e = (n) => {
+      n.source !== window && s(n.data);
+    };
+    return window.addEventListener("message", e), window.hostMessageCallback = s, () => {
+      window.removeEventListener("message", e), window.hostMessageCallback === s && (window.hostMessageCallback = null);
+    };
+  }
+  static sendCustomCommand(s, e = null, n = {}) {
+    const o = {
+      command: s,
+      text: JSON.stringify(n)
     };
-    if (s !== null)
-      s.postMessage(n);
+    if (e !== null)
+      e.postMessage(o);
     else if (typeof window.sendMessageFromUI == "function")
       try {
-        const e = window.sendMessageFromUI(n);
-      } catch (e) {
-        console.error("Cabbage: sendMessageFromUI threw error:", e), console.error("Cabbage: Error stack:", e.stack);
+        const a = window.sendMessageFromUI(o);
+      } catch (a) {
+        console.error("Cabbage: sendMessageFromUI threw error:", a), console.error("Cabbage: Error stack:", a.stack);
       }
-    else
-      console.error(
-        "Cabbage: window.sendMessageFromUI is not available yet. Message:",
-        n
-      ), console.error(
-        "Cabbage: typeof window.sendMessageFromUI:",
-        typeof window.sendMessageFromUI
-      ), console.error(
-        "Cabbage: window.sendMessageFromUI value:",
-        window.sendMessageFromUI
-      );
+    else window.parent !== window ? window.parent.postMessage(o, "*") : (console.error(
+      "Cabbage: window.sendMessageFromUI is not available yet. Message:",
+      o
+    ), console.error(
+      "Cabbage: typeof window.sendMessageFromUI:",
+      typeof window.sendMessageFromUI
+    ), console.error(
+      "Cabbage: window.sendMessageFromUI value:",
+      window.sendMessageFromUI
+    ));
   }
 }
-const C = (i) => {
-  const [o, s] = w();
-  return f(() => {
-    const a = (n) => {
-      const { id: e, widgetJson: r, command: u } = n.data;
-      if (e === i && r && u === "widgetUpdate") {
-        const t = JSON.parse(r);
+const y = (r) => {
+  const [s, e] = f();
+  return p(() => {
+    const n = (o) => {
+      const { id: a, widgetJson: t, command: c } = o.data;
+      if (a === r && t && c === "widgetUpdate") {
+        const i = JSON.parse(t);
         console.log(
-          `[Cabbage-React] Received properties for channelId: ${e}`,
-          t
-        ), s(t);
+          `[Cabbage-React] Received properties for channelId: ${a}`,
+          i
+        ), e(i);
       }
     };
-    return window.addEventListener("message", a), () => {
-      window.removeEventListener("message", a);
-    };
+    return window.addEventListener("message", n), () => window.removeEventListener("message", n);
   }, []), {
-    properties: o
+    properties: s
   };
-}, F = (i, o = "complete") => {
-  const { properties: s } = C(i), [a, n] = w(), [e, r] = w(), u = (t) => {
-    n(t), y.sendControlData({
-      channel: i,
-      value: t,
-      gesture: o
+}, F = (r, s = "complete") => {
+  const { properties: e } = y(r), [n, o] = f(), [a, t] = f(), c = (i) => {
+    o(i), C.sendControlData({
+      channel: r,
+      value: i,
+      gesture: s
     });
   };
-  return f(() => {
+  return p(() => {
     var m;
-    const t = s == null ? void 0 : s.channels.find(
-      (d) => d.id === i
+    const i = e == null ? void 0 : e.channels.find(
+      (d) => d.id === r
     );
-    if (!t) return;
-    const l = t.parameterIndex;
-    if (e === void 0 && l !== void 0 && (console.log(
-      `[Cabbage-React] Received parameterIndex for channelId: ${t.id}`,
+    if (!i) return;
+    const l = i.parameterIndex;
+    if (a === void 0 && l !== void 0 && (console.log(
+      `[Cabbage-React] Received parameterIndex for channelId: ${i.id}`,
       l
-    ), r(l)), a !== void 0) return;
-    const g = (m = t.range) == null ? void 0 : m.value;
-    g != null && (console.log(
-      `[Cabbage-React] Received initial value for channelId: ${t.id}`,
-      g
-    ), n(g));
-  }, [s]), f(() => {
-    const t = (l) => {
+    ), t(l)), n !== void 0) return;
+    const w = (m = i.range) == null ? void 0 : m.value;
+    w != null && (console.log(
+      `[Cabbage-React] Received initial value for channelId: ${i.id}`,
+      w
+    ), o(w));
+  }, [e]), p(() => {
+    const i = (l) => {
       var m;
-      const { command: g } = l.data;
-      if (g === "parameterChange") {
-        const { value: d, paramIdx: c } = l.data.data;
-        if (c !== e || d === null) return;
+      const { command: w } = l.data;
+      if (w === "parameterChange") {
+        const { value: d, paramIdx: g } = l.data.data;
+        if (g !== a || d === null) return;
         console.log(
-          `[Cabbage-React] Received parameterChange for parameterIndex: ${c}`,
+          `[Cabbage-React] Received parameterChange for parameterIndex: ${g}`,
           d
-        ), n(d);
-      } else if (g === "batchWidgetUpdate") {
-        const d = l.data.widgets, c = d == null ? void 0 : d.find((p) => p.id === i);
-        if (!c) return;
-        const b = JSON.parse(c.widgetJson).channels.find(
-          (p) => p.id === i
-        ), M = (m = b == null ? void 0 : b.range) == null ? void 0 : m.value;
+        ), o(d);
+      } else if (w === "batchWidgetUpdate") {
+        const d = l.data.widgets, g = d == null ? void 0 : d.find((b) => b.id === r);
+        if (!g) return;
+        const u = JSON.parse(g.widgetJson).channels.find(
+          (b) => b.id === r
+        ), M = (m = u == null ? void 0 : u.range) == null ? void 0 : m.value;
         console.log(
-          `[Cabbage-React] Received batch widget update for channelId: ${c.id}`,
+          `[Cabbage-React] Received batch widget update for channelId: ${g.id}`,
           M
-        ), n(M);
+        ), o(M);
       }
     };
-    return window.addEventListener("message", t), () => {
-      window.removeEventListener("message", t);
-    };
-  }, [e]), {
-    value: a,
-    setValue: u
+    return window.addEventListener("message", i), () => window.removeEventListener("message", i);
+  }, [a]), {
+    value: n,
+    setValue: c
   };
-}, v = (i) => {
-  const [o, s] = w();
-  return f(() => {
-    const a = (n) => {
-      const { data: e, type: r } = n;
-      if (e && r === "message") {
-        if (e.type !== i) return;
-        console.log(
-          `[Cabbage-React] Received data for messageType: ${e.type}`,
-          e
-        ), s(e);
-      }
-    };
-    return window.addEventListener("message", a), () => {
-      window.removeEventListener("message", a);
+}, v = (r, s) => {
+  const [e, n] = f();
+  return p(() => {
+    const o = (a) => {
+      const { data: t, type: c } = a;
+      !t || c !== "message" || t.type === r && (console.log(
+        `[Cabbage-React] Received data for messageType: ${t.type}`,
+        t
+      ), s && s(t), n(t));
     };
-  }, []), {
-    data: o
-  };
+    return window.addEventListener("message", o), () => window.removeEventListener("message", o);
+  }, [r, s]), { message: e };
 };
 export {
-  y as Cabbage,
+  C as Cabbage,
   v as useCabbageMessage,
-  C as useCabbageProperties,
+  y as useCabbageProperties,
   F as useCabbageState
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cabbage-react",
-	"version": "1.0.47",
+	"version": "1.0.49",
 	"type": "module",
 	"keywords": [
 		"cabbage",