cabbage-react 1.0.46 → 1.0.48

package/README.md

@@ -34,14 +34,14 @@ Get properties for a widget from the backend. This hook:
 Get messages from the backend. This hook:
 
 - Automatically updates local state when a message is received
-- Expects a serialized JSON object (sent as a string) with a `messageType` property
+- Expects a serialized JSON object (sent as a string) with a `type` property
 
 #### Example: sending a message from Csound
 
 ```csd
 jsonData:S = sprintf({{
 {
-	"messageType":"NoteData",
+	"type":"NoteData",
 	"noteCount":%f,
 	"note":%f,
 	"noteLength":%f,

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,5 +1,5 @@
 /**
- * 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

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:n,value:s,gesture:a="complete"},o=null){const e={command:"controlData",channel:n,value:s,gesture:a};o!==null?o.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):window.parent!==window?window.parent.postMessage(e,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static isReadyToLoad(n=null,s={}){this.sendCustomCommand("isReadyToLoad",n)}static sendMidiMessageFromUI(n,s,a,o=null){var e={statusByte:n,dataByte1:s,dataByte2:a};const i={command:"midiMessage",obj:JSON.stringify(e)};o!==null?o.postMessage(i):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(i):window.parent!==window?window.parent.postMessage(i,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",i)}static MidiMessageFromHost(n,s,a){}static triggerFileOpenDialog(n,s,a={}){var o={channel:s,directory:a.directory||"",filters:a.filters||"*",openAtLastKnownLocation:a.openAtLastKnownLocation!==void 0?a.openAtLastKnownLocation:!0};const e={command:"fileOpen",obj:JSON.stringify(o)};n!==null?n.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):window.parent!==window?window.parent.postMessage(e,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static openUrl(n,s,a){var o={url:s,file:a};const e={command:"openUrl",obj:JSON.stringify(o)};n!==null?n.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):window.parent!==window?window.parent.postMessage(e,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static requestResize(n,s,a=null){const o={command:"requestResize",width:n,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(o):window.parent!==window?window.parent.postMessage(o,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",o)}static consumeKeypresses(n){typeof window.consumeKeypresses=="function"&&window.consumeKeypresses(n)}static sendChannelData(n,s,a=null){var o={channel:n};if(typeof s=="string")o.stringData=s;else if(typeof s=="number")o.floatData=s;else{console.warn("Cabbage: sendChannelData received unsupported data type:",typeof s);return}const e={command:"channelData",obj:JSON.stringify(o)};a!==null?a.postMessage(e):typeof window.sendMessageFromUI=="function"?window.sendMessageFromUI(e):window.parent!==window?window.parent.postMessage(e,"*"):console.error("Cabbage: window.sendMessageFromUI is not available. Message:",e)}static sendWidgetUpdate(n,s=null){const a={command:"widgetStateUpdate",obj:JSON.stringify(CabbageUtils.sanitizeForEditor(n))};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:",a)}static addMessageListener(n){const s=a=>{a.source!==window&&n(a.data)};return window.addEventListener("message",s),window.hostMessageCallback=n,()=>{window.removeEventListener("message",s),window.hostMessageCallback===n&&(window.hostMessageCallback=null)}}static sendCustomCommand(n,s=null,a={}){const o={command:n,text:JSON.stringify(a)};if(s!==null)s.postMessage(o);else if(typeof window.sendMessageFromUI=="function")try{const e=window.sendMessageFromUI(o)}catch(e){console.error("Cabbage: sendMessageFromUI threw error:",e),console.error("Cabbage: Error stack:",e.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[n,s]=l.useState();return l.useEffect(()=>{const a=o=>{const{id:e,widgetJson:i,command:f}=o.data;if(e===r&&i&&f==="widgetUpdate"){const t=JSON.parse(i);console.log(`[Cabbage-React] Received properties for channelId: ${e}`,t),s(t)}};return window.addEventListener("message",a),()=>{window.removeEventListener("message",a)}},[]),{properties:n}},y=(r,n="complete")=>{const{properties:s}=C(r),[a,o]=l.useState(),[e,i]=l.useState(),f=t=>{o(t),M.sendControlData({channel:r,value:t,gesture:n})};return l.useEffect(()=>{var m;const t=s==null?void 0:s.channels.find(d=>d.id===r);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),i(g)),a!==void 0)return;const w=(m=t.range)==null?void 0:m.value;w!=null&&(console.log(`[Cabbage-React] Received initial value for channelId: ${t.id}`,w),o(w))},[s]),l.useEffect(()=>{const t=g=>{var m;const{command:w}=g.data;if(w==="parameterChange"){const{value:d,paramIdx:c}=g.data.data;if(c!==e||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=(m=u==null?void 0:u.range)==null?void 0:m.value;console.log(`[Cabbage-React] Received batch widget update for channelId: ${c.id}`,b),o(b)}};return window.addEventListener("message",t),()=>{window.removeEventListener("message",t)}},[e]),{value:a,setValue:f}},I=r=>{const[n,s]=l.useState();return l.useEffect(()=>{const a=o=>{const{data:e,type:i}=o;if(e&&i==="message"){if(e.type!==r)return;console.log(`[Cabbage-React] Received data for messageType: ${e.type}`,e),s(e)}};return window.addEventListener("message",a),()=>{window.removeEventListener("message",a)}},[]),{data:n}};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 m, useEffect as f } from "react";
+class C {
   /**
    * Send a widget value change to the Cabbage backend.
    *
@@ -20,14 +20,14 @@ 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) {
+  static sendControlData({ channel: a, value: s, gesture: n = "complete" }, o = null) {
     const e = {
       command: "controlData",
-      channel: o,
+      channel: a,
       value: s,
-      gesture: a
+      gesture: n
     };
-    n !== null ? n.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : console.error(
+    o !== null ? o.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : window.parent !== window ? window.parent.postMessage(e, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
       e
     );
@@ -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(a = null, s = {}) {
+    this.sendCustomCommand("isReadyToLoad", a);
   }
   /**
    * 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) {
+  static sendMidiMessageFromUI(a, s, n, o = null) {
     var e = {
-      statusByte: o,
+      statusByte: a,
       dataByte1: s,
-      dataByte2: a
+      dataByte2: n
     };
-    const r = {
+    const i = {
       command: "midiMessage",
       obj: JSON.stringify(e)
     };
-    n !== null ? n.postMessage(r) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(r) : console.error(
+    o !== null ? o.postMessage(i) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(i) : window.parent !== window ? window.parent.postMessage(i, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
-      r
+      i
     );
   }
   /**
@@ -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(a, s, n) {
   }
   /**
    * Trigger a native file open dialog for file selection widgets.
@@ -83,18 +83,18 @@ 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 = {
+  static triggerFileOpenDialog(a, s, n = {}) {
+    var o = {
       channel: s,
-      directory: a.directory || "",
-      filters: a.filters || "*",
-      openAtLastKnownLocation: a.openAtLastKnownLocation !== void 0 ? a.openAtLastKnownLocation : !0
+      directory: n.directory || "",
+      filters: n.filters || "*",
+      openAtLastKnownLocation: n.openAtLastKnownLocation !== void 0 ? n.openAtLastKnownLocation : !0
     };
     const e = {
       command: "fileOpen",
-      obj: JSON.stringify(n)
+      obj: JSON.stringify(o)
     };
-    o !== null ? o.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : console.error(
+    a !== null ? a.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : window.parent !== window ? window.parent.postMessage(e, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
       e
     );
@@ -106,16 +106,16 @@ class y {
    * @param {string} url - URL to open
    * @param {string} file - File path to open
    */
-  static openUrl(o, s, a) {
-    var n = {
+  static openUrl(a, s, n) {
+    var o = {
       url: s,
-      file: a
+      file: n
     };
     const e = {
       command: "openUrl",
-      obj: JSON.stringify(n)
+      obj: JSON.stringify(o)
     };
-    o !== null ? o.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : console.error(
+    a !== null ? a.postMessage(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : window.parent !== window ? window.parent.postMessage(e, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
       e
     );
@@ -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(a, s, n = null) {
+    const o = {
       command: "requestResize",
-      width: o,
+      width: a,
       height: s
     };
-    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(a) {
+    typeof window.consumeKeypresses == "function" && window.consumeKeypresses(a);
   }
   /**
    * Send channel data directly to Csound without DAW automation involvement.
@@ -178,14 +178,14 @@ 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(a, s, n = null) {
+    var o = {
+      channel: a
     };
     if (typeof s == "string")
-      n.stringData = s;
+      o.stringData = s;
     else if (typeof s == "number")
-      n.floatData = s;
+      o.floatData = s;
     else {
       console.warn(
         "Cabbage: sendChannelData received unsupported data type:",
@@ -195,9 +195,9 @@ class y {
     }
     const e = {
       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(e) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(e) : window.parent !== window ? window.parent.postMessage(e, "*") : console.error(
       "Cabbage: window.sendMessageFromUI is not available. Message:",
       e
     );
@@ -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(a, s = null) {
+    const n = {
       command: "widgetStateUpdate",
-      obj: JSON.stringify(CabbageUtils.sanitizeForEditor(o))
+      obj: JSON.stringify(CabbageUtils.sanitizeForEditor(a))
     };
-    s !== null ? s.postMessage(a) : typeof window.sendMessageFromUI == "function" ? window.sendMessageFromUI(a) : console.error(
+    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:",
-      a
+      n
     );
   }
   /**
@@ -226,128 +226,163 @@ 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(a) {
+    const s = (n) => {
+      n.source !== window && a(n.data);
+    };
+    return window.addEventListener("message", s), window.hostMessageCallback = a, () => {
+      window.removeEventListener("message", s), window.hostMessageCallback === a && (window.hostMessageCallback = null);
+    };
+  }
+  static sendCustomCommand(a, s = null, n = {}) {
+    const o = {
+      command: a,
+      text: JSON.stringify(n)
     };
     if (s !== null)
-      s.postMessage(n);
+      s.postMessage(o);
     else if (typeof window.sendMessageFromUI == "function")
       try {
-        const e = window.sendMessageFromUI(n);
+        const e = window.sendMessageFromUI(o);
       } 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
-      );
+    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();
+const y = (r) => {
+  const [a, s] = m();
   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 n = (o) => {
+      const { id: e, widgetJson: i, command: p } = o.data;
+      if (e === r && i && p === "widgetUpdate") {
+        const t = JSON.parse(i);
         console.log(
           `[Cabbage-React] Received properties for channelId: ${e}`,
           t
         ), s(t);
       }
     };
-    return window.addEventListener("message", a), () => {
-      window.removeEventListener("message", a);
+    return window.addEventListener("message", n), () => {
+      window.removeEventListener("message", n);
     };
   }, []), {
-    properties: o
+    properties: a
   };
-}, F = (i, o = "complete") => {
-  const { properties: s } = C(i), [a, n] = w(), [e, r] = w(), u = (t) => {
-    n(t), y.sendControlData({
-      channel: i,
+}, F = (r, a = "complete") => {
+  const { properties: s } = y(r), [n, o] = m(), [e, i] = m(), p = (t) => {
+    o(t), C.sendControlData({
+      channel: r,
       value: t,
-      gesture: o
+      gesture: a
     });
   };
   return f(() => {
-    var m;
+    var c;
     const t = s == null ? void 0 : s.channels.find(
-      (d) => d.id === i
+      (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}`,
       l
-    ), r(l)), a !== void 0) return;
-    const g = (m = t.range) == null ? void 0 : m.value;
-    g != null && (console.log(
+    ), i(l)), n !== void 0) return;
+    const w = (c = t.range) == null ? void 0 : c.value;
+    w != null && (console.log(
       `[Cabbage-React] Received initial value for channelId: ${t.id}`,
-      g
-    ), n(g));
+      w
+    ), o(w));
   }, [s]), f(() => {
     const t = (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;
+      var c;
+      const { command: w } = l.data;
+      if (w === "parameterChange") {
+        const { value: d, paramIdx: g } = l.data.data;
+        if (g !== e || 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 = (c = u == null ? void 0 : u.range) == null ? void 0 : c.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
+    value: n,
+    setValue: p
   };
-}, v = (i) => {
-  const [o, s] = w();
+}, v = (r) => {
+  const [a, s] = m();
   return f(() => {
-    const a = (n) => {
-      const { data: e, type: r } = n;
-      if (e && r === "message") {
-        if (e.type !== i) return;
+    const n = (o) => {
+      const { data: e, type: i } = o;
+      if (e && i === "message") {
+        if (e.type !== r) return;
         console.log(
           `[Cabbage-React] Received data for messageType: ${e.type}`,
           e
         ), s(e);
       }
     };
-    return window.addEventListener("message", a), () => {
-      window.removeEventListener("message", a);
+    return window.addEventListener("message", n), () => {
+      window.removeEventListener("message", n);
     };
   }, []), {
-    data: o
+    data: a
   };
 };
 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.46",
+	"version": "1.0.48",
 	"type": "module",
 	"keywords": [
 		"cabbage",