supersonic-scsynth 0.2.2 → 0.3.0

package/README.md

@@ -8,11 +8,13 @@ A WebAssembly port of SuperCollider's scsynth audio synthesis engine for the bro
 
 ```html
 <script type="module">
-  import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';
+  import { SuperSonic } from './dist/supersonic.js';
 
   const sonic = new SuperSonic({
-    sampleBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/',
-    synthdefBaseURL: 'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/'
+    workerBaseURL: './dist/workers/',
+    wasmBaseURL: './dist/wasm/',
+    sampleBaseURL: './dist/samples/',
+    synthdefBaseURL: './dist/synthdefs/'
   });
 
   await sonic.init();
@@ -29,11 +31,11 @@ A WebAssembly port of SuperCollider's scsynth audio synthesis engine for the bro
 </script>
 ```
 
-**Note:** Requires specific HTTP headers (COOP/COEP) for SharedArrayBuffer support. See [Browser Requirements](#browser-requirements) below.
+**Important:** SuperSonic requires self-hosting (cannot load from CDN). See [CDN Usage](#cdn-usage) below.
 
 ## Installation
 
-**Via npm:**
+**Via npm (for local bundling):**
 ```bash
 # Core engine only (~450KB)
 npm install supersonic-scsynth
@@ -42,15 +44,15 @@ npm install supersonic-scsynth
 npm install supersonic-scsynth-bundle
 ```
 
-**Via CDN:**
+**Pre-built distribution (recommended):**
+Download the pre-built package (~35MB with all synthdefs and samples) and serve from your own domain:
+https://samaaron.github.io/supersonic/supersonic-dist.zip
+
+Extract to your web server and import as:
 ```javascript
-import { SuperSonic } from 'https://unpkg.com/supersonic-scsynth@latest';
+import { SuperSonic } from './dist/supersonic.js';
 ```
 
-**Pre-built distribution:**
-Download the 'nightly' build (~35MB with all synthdefs and samples):
-https://samaaron.github.io/supersonic/supersonic-dist.zip
-
 ## Packages
 
 SuperSonic is split into multiple packages:
@@ -69,8 +71,10 @@ All synthdefs and samples are from [Sonic Pi](https://github.com/sonic-pi-net/so
 **Creating an instance:**
 ```javascript
 const sonic = new SuperSonic({
-  sampleBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@latest/samples/',
-  synthdefBaseURL: 'https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/',
+  workerBaseURL: './dist/workers/',  // Required: Path to worker files
+  wasmBaseURL: './dist/wasm/',       // Required: Path to WASM files
+  sampleBaseURL: './dist/samples/',  // Optional: Path to audio samples
+  synthdefBaseURL: './dist/synthdefs/', // Optional: Path to synthdefs
   audioPathMap: { /* optional custom path mappings */ }
 });
 ```
@@ -121,6 +125,43 @@ Cross-Origin-Resource-Policy: cross-origin
 
 See `example/server.rb` for a reference implementation.
 
+## CDN Usage
+
+SuperSonic cannot be loaded from a CDN. The core library must be self-hosted on your domain.
+
+### Why Self-Hosting is Required
+
+SuperSonic uses `SharedArrayBuffer` for real-time audio performance. Browsers require workers that use `SharedArrayBuffer` to come from the same origin as the page. Even with proper COOP/COEP headers, cross-origin workers with shared memory are blocked. This is a fundamental browser security requirement stemming from Spectre attack mitigation.
+
+What this means:
+- You cannot use `import { SuperSonic } from 'https://unpkg.com/supersonic/...'`
+- You must download and self-host the core library on your own domain
+- The npm packages exist for convenience but must be bundled and deployed to your server
+
+### Synthdefs and Samples Can Use CDN
+
+Pre-compiled synthdefs and audio samples can be loaded from CDNs. They're just data files, not workers.
+
+```javascript
+// Self-hosted core library
+import { SuperSonic } from './dist/supersonic.js';
+
+// CDN-hosted synthdefs and samples work fine
+const sonic = new SuperSonic({
+  workerBaseURL: './dist/workers/',  // Must be self-hosted
+  wasmBaseURL: './dist/wasm/',       // Must be self-hosted
+  sampleBaseURL: 'https://unpkg.com/supersonic-scsynth-samples@0.1.6/samples/',
+  synthdefBaseURL: 'https://unpkg.com/supersonic-scsynth-synthdefs@0.1.6/synthdefs/'
+});
+
+await sonic.init();
+await sonic.loadSynthDefs(['sonic-pi-beep', 'sonic-pi-tb303']);
+```
+
+### Hybrid Approach
+
+Self-host the SuperSonic core (JS, WASM, workers) with COOP/COEP headers. Use CDN for synthdefs and samples to save bandwidth. See `example/simple-cdn.html` for a working example.
+
 ## Building from Source
 
 **Prerequisites:**
@@ -167,7 +208,7 @@ dist/
     └── debug_worker.js           # Debug logger
 ```
 
-The engine expects these files at `./dist/` relative to your HTML. Paths are currently not configurable.
+You must specify the paths to `workers/` and `wasm/` directories when creating a SuperSonic instance using the `workerBaseURL` and `wasmBaseURL` options.
 
 ## License
 

package/dist/supersonic.js

@@ -766,7 +766,8 @@ var { readPacket, writePacket, readMessage, writeMessage, readBundle, writeBundl
 
 // js/lib/scsynth_osc.js
 var ScsynthOSC = class {
-  constructor() {
+  constructor(workerBaseURL = null) {
+    this.workerBaseURL = workerBaseURL;
     this.workers = {
       oscOut: null,
       // Scheduler worker (now also writes directly to ring buffer)
@@ -799,9 +800,9 @@ var ScsynthOSC = class {
     this.ringBufferBase = ringBufferBase;
     this.bufferConstants = bufferConstants;
     try {
-      this.workers.oscOut = new Worker(new URL("./workers/osc_out_prescheduler_worker.js", import.meta.url), { type: "module" });
-      this.workers.oscIn = new Worker(new URL("./workers/osc_in_worker.js", import.meta.url), { type: "module" });
-      this.workers.debug = new Worker(new URL("./workers/debug_worker.js", import.meta.url), { type: "module" });
+      this.workers.oscOut = new Worker(this.workerBaseURL + "osc_out_prescheduler_worker.js", { type: "module" });
+      this.workers.oscIn = new Worker(this.workerBaseURL + "osc_in_worker.js", { type: "module" });
+      this.workers.debug = new Worker(this.workerBaseURL + "debug_worker.js", { type: "module" });
       this.setupWorkerHandlers();
       const initPromises = [
         this.initWorker(this.workers.oscOut, "OSC SCHEDULER+WRITER"),
@@ -1916,12 +1917,16 @@ var SuperSonic = class _SuperSonic {
     this.onDebugMessage = null;
     this.onInitialized = null;
     this.onError = null;
-    const moduleUrl = new URL(import.meta.url);
-    const basePath = new URL(".", moduleUrl).href;
-    this.basePath = basePath;
+    if (!options.workerBaseURL || !options.wasmBaseURL) {
+      throw new Error('SuperSonic requires workerBaseURL and wasmBaseURL options. Example:\nnew SuperSonic({\n  workerBaseURL: "/supersonic/workers/",\n  wasmBaseURL: "/supersonic/wasm/"\n})');
+    }
+    const workerBaseURL = options.workerBaseURL;
+    const wasmBaseURL = options.wasmBaseURL;
     this.config = {
-      wasmUrl: new URL("wasm/scsynth-nrt.wasm", basePath).href,
-      workletUrl: new URL("workers/scsynth_audio_worklet.js", basePath).href,
+      wasmUrl: options.wasmUrl || wasmBaseURL + "scsynth-nrt.wasm",
+      workletUrl: options.workletUrl || workerBaseURL + "scsynth_audio_worklet.js",
+      workerBaseURL,
+      // Store for worker creation
       development: false,
       audioContextOptions: {
         latencyHint: "interactive",
@@ -2031,12 +2036,13 @@ var SuperSonic = class _SuperSonic {
    */
   async #loadWasmManifest() {
     try {
-      const manifestUrl = new URL("wasm/manifest.json", this.basePath).href;
+      const wasmBaseURL = this.config.workerBaseURL.replace("/workers/", "/wasm/");
+      const manifestUrl = wasmBaseURL + "manifest.json";
       const response = await fetch(manifestUrl);
       if (response.ok) {
         const manifest = await response.json();
         const wasmFile = manifest.wasmFile;
-        this.config.wasmUrl = new URL(`wasm/${wasmFile}`, this.basePath).href;
+        this.config.wasmUrl = wasmBaseURL + wasmFile;
         console.log(`[SuperSonic] Using WASM build: ${wasmFile}`);
         console.log(`[SuperSonic] Build: ${manifest.buildId} (git: ${manifest.gitHash})`);
       }
@@ -2081,7 +2087,7 @@ var SuperSonic = class _SuperSonic {
    * Initialize OSC communication layer
    */
   async #initializeOSC() {
-    this.osc = new ScsynthOSC();
+    this.osc = new ScsynthOSC(this.config.workerBaseURL);
     this.osc.onRawOSC((msg) => {
       if (this.onOSC) {
         this.onOSC(msg);
@@ -2324,7 +2330,7 @@ var SuperSonic = class _SuperSonic {
     }
     if (!this.sampleBaseURL) {
       throw new Error(
-        'sampleBaseURL not configured. Please set it in SuperSonic constructor options.\nExample: new SuperSonic({ sampleBaseURL: "https://unpkg.com/supersonic-scsynth-samples@latest/samples/" })\nOr install sample packages: npm install supersonic-scsynth-samples'
+        'sampleBaseURL not configured. Please set it in SuperSonic constructor options.\nExample: new SuperSonic({ sampleBaseURL: "./dist/samples/" })\nOr use CDN: new SuperSonic({ sampleBaseURL: "https://unpkg.com/supersonic-scsynth-samples@latest/samples/" })\nOr install: npm install supersonic-scsynth-samples'
       );
     }
     return this.sampleBaseURL + scPath;
@@ -2525,7 +2531,7 @@ var SuperSonic = class _SuperSonic {
     }
     if (!this.synthdefBaseURL) {
       throw new Error(
-        'synthdefBaseURL not configured. Please set it in SuperSonic constructor options.\nExample: new SuperSonic({ synthdefBaseURL: "https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/" })\nOr install: npm install supersonic-scsynth-synthdefs'
+        'synthdefBaseURL not configured. Please set it in SuperSonic constructor options.\nExample: new SuperSonic({ synthdefBaseURL: "./dist/synthdefs/" })\nOr use CDN: new SuperSonic({ synthdefBaseURL: "https://unpkg.com/supersonic-scsynth-synthdefs@latest/synthdefs/" })\nOr install: npm install supersonic-scsynth-synthdefs'
       );
     }
     const results = {};

package/dist/wasm/manifest.json

@@ -1,6 +1,6 @@
 {
   "wasmFile": "scsynth-nrt.wasm",
-  "buildId": "20251114-221419",
-  "buildTime": "2025-11-14T22:14:19Z",
-  "gitHash": "cfd4b75"
+  "buildId": "20251117-205541",
+  "buildTime": "2025-11-17T20:55:41Z",
+  "gitHash": "264e2ae"
 }

package/dist/workers/osc_out_prescheduler_worker.js

@@ -24,6 +24,11 @@ var periodicTimer = null;    // Single periodic timer (25ms interval)
 var sequenceCounter = 0;
 var isDispatching = false;  // Prevent reentrancy into dispatch loop
 
+// Retry queue for failed writes
+var retryQueue = [];
+var MAX_RETRY_QUEUE_SIZE = 100;
+var MAX_RETRIES_PER_MESSAGE = 5;
+
 // Statistics
 var stats = {
     bundlesScheduled: 0,
@@ -38,7 +43,12 @@ var stats = {
     maxLateDispatchMs: 0,
     totalSendTasks: 0,
     totalSendProcessMs: 0,
-    maxSendProcessMs: 0
+    maxSendProcessMs: 0,
+    messagesRetried: 0,
+    retriesSucceeded: 0,
+    retriesFailed: 0,
+    retryQueueSize: 0,
+    maxRetryQueueSize: 0
 };
 
 // Timing constants
@@ -123,8 +133,9 @@ function initSharedBuffer() {
 /**
  * Write OSC message directly to ring buffer (replaces MessagePort to writer worker)
  * This is now the ONLY place that writes to the ring buffer
+ * Returns true if successful, false if failed (caller should queue for retry)
  */
-function writeToRingBuffer(oscMessage) {
+function writeToRingBuffer(oscMessage, isRetry) {
     if (!sharedBuffer || !atomicView) {
         console.error('[PreScheduler] Not initialized for ring buffer writing');
         stats.bundlesDropped++;
@@ -149,10 +160,14 @@ function writeToRingBuffer(oscMessage) {
     var available = (bufferConstants.IN_BUFFER_SIZE - 1 - head + tail) % bufferConstants.IN_BUFFER_SIZE;
 
     if (available < totalSize) {
-        // Buffer full - drop message (prescheduler should not block)
+        // Buffer full - return false so caller can queue for retry
         stats.bufferOverruns++;
-        stats.bundlesDropped++;
-        console.warn('[PreScheduler] Ring buffer full, dropping message');
+        if (!isRetry) {
+            // Only increment bundlesDropped on initial attempt
+            // Retries increment different counters
+            stats.bundlesDropped++;
+            console.warn('[PreScheduler] Ring buffer full, message will be queued for retry');
+        }
         return false;
     }
 
@@ -191,6 +206,17 @@ function writeToRingBuffer(oscMessage) {
     // Write payload
     uint8View.set(oscMessage, writePos + bufferConstants.MESSAGE_HEADER_SIZE);
 
+    // Diagnostic: Log first few writes
+    if (stats.bundlesWritten < 5) {
+        schedulerLog('[PreScheduler] Write:', 'seq=' + stats.bundlesWritten,
+                    'pos=' + head, 'size=' + totalSize, 'newHead=' + ((head + totalSize) % bufferConstants.IN_BUFFER_SIZE));
+    }
+
+    // CRITICAL: Ensure memory barrier before publishing head pointer
+    // All previous writes (header + payload) must be visible to C++ reader
+    // Atomics.load provides necessary memory fence/barrier
+    Atomics.load(atomicView, CONTROL_INDICES.IN_HEAD);
+
     // Update head pointer (publish message)
     var newHead = (head + totalSize) % bufferConstants.IN_BUFFER_SIZE;
     Atomics.store(atomicView, CONTROL_INDICES.IN_HEAD, newHead);
@@ -199,6 +225,77 @@ function writeToRingBuffer(oscMessage) {
     return true;
 }
 
+/**
+ * Add a message to the retry queue
+ */
+function queueForRetry(oscData, context) {
+    if (retryQueue.length >= MAX_RETRY_QUEUE_SIZE) {
+        console.error('[PreScheduler] Retry queue full, dropping message permanently');
+        stats.retriesFailed++;
+        return;
+    }
+
+    retryQueue.push({
+        oscData: oscData,
+        retryCount: 0,
+        context: context || 'unknown',
+        queuedAt: performance.now()
+    });
+
+    stats.retryQueueSize = retryQueue.length;
+    if (stats.retryQueueSize > stats.maxRetryQueueSize) {
+        stats.maxRetryQueueSize = stats.retryQueueSize;
+    }
+
+    schedulerLog('[PreScheduler] Queued message for retry:', context, 'queue size:', retryQueue.length);
+}
+
+/**
+ * Attempt to retry queued messages
+ * Called periodically from checkAndDispatch
+ */
+function processRetryQueue() {
+    if (retryQueue.length === 0) {
+        return;
+    }
+
+    var i = 0;
+    while (i < retryQueue.length) {
+        var item = retryQueue[i];
+
+        // Try to write
+        var success = writeToRingBuffer(item.oscData, true);
+
+        if (success) {
+            // Success - remove from queue
+            retryQueue.splice(i, 1);
+            stats.retriesSucceeded++;
+            stats.messagesRetried++;
+            stats.retryQueueSize = retryQueue.length;
+            schedulerLog('[PreScheduler] Retry succeeded for:', item.context,
+                        'after', item.retryCount + 1, 'attempts');
+            // Don't increment i - we removed an item
+        } else {
+            // Failed - increment retry count
+            item.retryCount++;
+            stats.messagesRetried++;
+
+            if (item.retryCount >= MAX_RETRIES_PER_MESSAGE) {
+                // Give up on this message
+                console.error('[PreScheduler] Giving up on message after',
+                             MAX_RETRIES_PER_MESSAGE, 'retries:', item.context);
+                retryQueue.splice(i, 1);
+                stats.retriesFailed++;
+                stats.retryQueueSize = retryQueue.length;
+                // Don't increment i - we removed an item
+            } else {
+                // Keep in queue, try again next cycle
+                i++;
+            }
+        }
+    }
+}
+
 /**
  * Schedule an OSC bundle by its NTP timestamp
  * Non-bundles or bundles without timestamps are dispatched immediately
@@ -209,7 +306,11 @@ function scheduleEvent(oscData, editorId, runTag) {
     if (ntpTime === null) {
         // Not a bundle - dispatch immediately to ring buffer
         schedulerLog('[PreScheduler] Non-bundle message, dispatching immediately');
-        writeToRingBuffer(oscData);
+        var success = writeToRingBuffer(oscData, false);
+        if (!success) {
+            // Queue for retry
+            queueForRetry(oscData, 'immediate message');
+        }
         return;
     }
 
@@ -338,6 +439,9 @@ function stopPeriodicPolling() {
 function checkAndDispatch() {
     isDispatching = true;
 
+    // First, try to process any queued retries
+    processRetryQueue();
+
     var currentNTP = getCurrentNTP();
     var lookaheadTime = currentNTP + LOOKAHEAD_S;
     var dispatchCount = 0;
@@ -361,7 +465,11 @@ function checkAndDispatch() {
                         'early=' + (timeUntilExec * 1000).toFixed(1) + 'ms',
                         'remaining=' + stats.eventsPending);
 
-            writeToRingBuffer(nextEvent.oscData);
+            var success = writeToRingBuffer(nextEvent.oscData, false);
+            if (!success) {
+                // Queue for retry
+                queueForRetry(nextEvent.oscData, 'scheduled bundle NTP=' + nextEvent.ntpTime.toFixed(3));
+            }
             dispatchCount++;
         } else {
             // Rest aren't ready yet (heap is sorted)
@@ -369,10 +477,11 @@ function checkAndDispatch() {
         }
     }
 
-    if (dispatchCount > 0 || eventHeap.length > 0) {
+    if (dispatchCount > 0 || eventHeap.length > 0 || retryQueue.length > 0) {
         schedulerLog('[PreScheduler] Dispatch cycle complete:',
                     'dispatched=' + dispatchCount,
-                    'pending=' + eventHeap.length);
+                    'pending=' + eventHeap.length,
+                    'retrying=' + retryQueue.length);
     }
 
     isDispatching = false;
@@ -474,10 +583,16 @@ function processImmediate(oscData) {
     if (isBundle(oscData)) {
         var messages = extractMessagesFromBundle(oscData);
         for (var i = 0; i < messages.length; i++) {
-            writeToRingBuffer(messages[i]);
+            var success = writeToRingBuffer(messages[i], false);
+            if (!success) {
+                queueForRetry(messages[i], 'immediate bundle message ' + i);
+            }
         }
     } else {
-        writeToRingBuffer(oscData);
+        var success = writeToRingBuffer(oscData, false);
+        if (!success) {
+            queueForRetry(oscData, 'immediate message');
+        }
     }
 }
 
@@ -555,7 +670,12 @@ self.addEventListener('message', function(event) {
                         maxLateDispatchMs: stats.maxLateDispatchMs,
                         totalSendTasks: stats.totalSendTasks,
                         totalSendProcessMs: stats.totalSendProcessMs,
-                        maxSendProcessMs: stats.maxSendProcessMs
+                        maxSendProcessMs: stats.maxSendProcessMs,
+                        messagesRetried: stats.messagesRetried,
+                        retriesSucceeded: stats.retriesSucceeded,
+                        retriesFailed: stats.retriesFailed,
+                        retryQueueSize: stats.retryQueueSize,
+                        maxRetryQueueSize: stats.maxRetryQueueSize
                     }
                 });
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supersonic-scsynth",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "SuperCollider scsynth WebAssembly port for AudioWorklet - Run SuperCollider synthesis in the browser",
   "main": "dist/supersonic.js",
   "unpkg": "dist/supersonic.js",

package/dist/workers/osc_out_worker.js

@@ -1,382 +0,0 @@
-/*
-    SuperSonic - SuperCollider AudioWorklet WebAssembly port
-    Copyright (c) 2025 Sam Aaron
-
-    Based on SuperCollider by James McCartney and community
-    GPL v3 or later
-*/
-
-/**
- * OSC OUT Worker - Scheduler for OSC bundles
- * Handles timed bundles and forwards them to the writer worker
- * NO LONGER writes to ring buffer directly - all writes go through osc_writer_worker.js
- * ES5-compatible for Qt WebEngine
- */
-
-// Reference to the writer worker
-var writerWorker = null;
-
-// Scheduling state
-var scheduledEvents = [];
-var currentTimer = null;
-var cachedTimeDelta = null;
-var minimumScheduleRequirementS = 0.002; // 2ms for audio precision
-var latencyS = 0.05; // 50ms latency compensation for scsynth
-
-var DEBUG_SCHED_LOGS = false;
-function schedulerLog() {
-    if (DEBUG_SCHED_LOGS) {
-        console.log.apply(console, arguments);
-    }
-}
-function schedulerWarn() {
-    if (DEBUG_SCHED_LOGS) {
-        console.warn.apply(console, arguments);
-    }
-}
-
-// Statistics
-var stats = {
-    bundlesScheduled: 0,
-    bundlesSentToWriter: 0
-};
-
-/**
- * Initialize scheduler
- */
-function init(buffer, base, constants) {
-    // We don't need the ring buffer anymore, but keep the params for compatibility
-    schedulerLog('[OSCSchedulerWorker] Initialized (scheduler only, no ring buffer access)');
-}
-
-/**
- * Send message to writer worker
- */
-function sendToWriter(oscMessage) {
-    if (!writerWorker) {
-        console.error('[OSCSchedulerWorker] Writer worker not set');
-        return;
-    }
-
-    // Send to writer worker via postMessage
-    writerWorker.postMessage({
-        type: 'write',
-        oscData: oscMessage
-    });
-
-    stats.bundlesSentToWriter++;
-}
-
-/**
- * Get or set cached time delta for synchronization
- */
-function getOrSetTimeDelta(delta) {
-    if (cachedTimeDelta === null) {
-        cachedTimeDelta = delta;
-    }
-    return cachedTimeDelta;
-}
-
-/**
- * Check if data is an OSC bundle (starts with "#bundle\0")
- */
-function isBundle(data) {
-    if (data.length < 16) return false;
-    var bundleTag = String.fromCharCode.apply(null, data.slice(0, 8));
-    return bundleTag === '#bundle\0';
-}
-
-/**
- * Parse OSC bundle timestamp from binary data
- * OSC bundles start with "#bundle\0" followed by 8-byte NTP timestamp
- */
-function parseBundleTimestamp(data) {
-    if (!isBundle(data)) return null;
-
-    // Read NTP timestamp (8 bytes, big-endian)
-    var view = new DataView(data.buffer, data.byteOffset + 8, 8);
-    var seconds = view.getUint32(0, false); // NTP seconds since 1900
-    var fraction = view.getUint32(4, false); // NTP fractional seconds
-
-    // Convert NTP to JavaScript time
-    // NTP epoch is 1900, JS epoch is 1970 (difference: 2208988800 seconds)
-    var NTP_TO_UNIX = 2208988800;
-
-    // Special OSC timestamps
-    if (seconds === 0 && fraction === 1) {
-        return 0; // Immediate execution
-    }
-
-    // Convert to JavaScript timestamp (milliseconds since 1970)
-    var unixSeconds = seconds - NTP_TO_UNIX;
-    var milliseconds = (fraction / 4294967296) * 1000; // Convert fraction to ms
-
-    return (unixSeconds * 1000) + milliseconds;
-}
-
-/**
- * Extract OSC messages from a bundle
- * Returns array of message buffers
- */
-function extractMessagesFromBundle(data) {
-    var messages = [];
-
-    if (!isBundle(data)) {
-        // Not a bundle, return as single message
-        return [data];
-    }
-
-    // Skip "#bundle\0" (8 bytes) and timestamp (8 bytes)
-    var offset = 16;
-
-    while (offset < data.length) {
-        // Read message size (4 bytes, big-endian)
-        if (offset + 4 > data.length) break;
-
-        var view = new DataView(data.buffer, data.byteOffset + offset, 4);
-        var messageSize = view.getInt32(0, false);
-        offset += 4;
-
-        if (messageSize <= 0 || offset + messageSize > data.length) break;
-
-        // Extract message data
-        var messageData = data.slice(offset, offset + messageSize);
-
-        // Check if this is a nested bundle
-        if (isBundle(messageData)) {
-            // Recursively extract from nested bundle
-            var nestedMessages = extractMessagesFromBundle(messageData);
-            messages = messages.concat(nestedMessages);
-        } else {
-            // It's a message, add it
-            messages.push(messageData);
-        }
-
-        offset += messageSize;
-
-        // Align to 4-byte boundary if needed
-        while (offset % 4 !== 0 && offset < data.length) {
-            offset++;
-        }
-    }
-
-    return messages;
-}
-
-/**
- * Process incoming OSC data (message or bundle)
- * Pre-scheduler: waits for calculated time then sends to writer
- * waitTimeMs is calculated by SuperSonic based on AudioContext time
- */
-function processOSC(oscData, editorId, runTag, waitTimeMs) {
-    stats.bundlesScheduled++;
-
-    // If no wait time provided, or wait time is 0 or negative, send immediately
-    if (waitTimeMs === null || waitTimeMs === undefined || waitTimeMs <= 0) {
-        sendToWriter(oscData);
-        return;
-    }
-
-    // Schedule to send after waitTimeMs
-    setTimeout(function() {
-        sendToWriter(oscData);
-    }, waitTimeMs);
-}
-
-/**
- * Process immediate send - forces immediate execution by unpacking bundles
- * Bundles are unpacked to individual messages (stripping timestamps)
- * Messages are sent as-is
- * Used when the caller wants immediate execution without scheduling
- */
-function processImmediate(oscData) {
-    if (isBundle(oscData)) {
-        // Extract all messages from the bundle (removes timestamp wrapper)
-        // Send each message individually for immediate execution
-        var messages = extractMessagesFromBundle(oscData);
-        for (var i = 0; i < messages.length; i++) {
-            sendToWriter(messages[i]);
-        }
-    } else {
-        // Regular message - send as-is
-        sendToWriter(oscData);
-    }
-}
-
-/**
- * Insert event into priority queue
- */
-function insertEvent(userId, editorId, runId, runTag, adjustedTimeS, oscBundle) {
-    var info = { userId: userId, editorId: editorId, runTag: runTag, runId: runId };
-    scheduledEvents.push([adjustedTimeS, info, oscBundle]);
-    scheduledEvents.sort(function(a, b) { return a[0] - b[0]; });
-    scheduleNextEvent();
-}
-
-/**
- * Schedule the next event timer
- */
-function scheduleNextEvent() {
-    if (scheduledEvents.length === 0) {
-        clearCurrentTimer();
-        return;
-    }
-
-    var nextEvent = scheduledEvents[0];
-    var adjustedTimeS = nextEvent[0];
-
-    if (!currentTimer || (currentTimer && currentTimer.timeS > adjustedTimeS)) {
-        addRunNextEventTimer(adjustedTimeS);
-    }
-}
-
-/**
- * Clear current timer
- */
-function clearCurrentTimer() {
-    if (currentTimer) {
-        clearTimeout(currentTimer.timerId);
-        currentTimer = null;
-    }
-}
-
-/**
- * Add timer for next event
- */
-function addRunNextEventTimer(adjustedTimeS) {
-    clearCurrentTimer();
-
-    var nowS = Date.now() / 1000;
-    var timeDeltaS = adjustedTimeS - nowS;
-
-    if (timeDeltaS <= minimumScheduleRequirementS) {
-        runNextEvent();
-    } else {
-        var delayMs = (timeDeltaS - minimumScheduleRequirementS) * 1000;
-        currentTimer = {
-            timeS: adjustedTimeS,
-            timerId: setTimeout(function() {
-                currentTimer = null;
-                runNextEvent();
-            }, delayMs)
-        };
-    }
-}
-
-/**
- * Run the next scheduled event
- */
-function runNextEvent() {
-    clearCurrentTimer();
-
-    if (scheduledEvents.length === 0) {
-        return;
-    }
-
-    var event = scheduledEvents.shift();
-    var data = event[2];
-
-    // Send the complete bundle unchanged (with original timestamp)
-    sendToWriter(data);
-
-    scheduleNextEvent();
-}
-
-/**
- * Cancel events by editor and tag
- */
-function cancelEditorTag(editorId, runTag) {
-    scheduledEvents = scheduledEvents.filter(function(e) {
-        return e[1].runTag !== runTag || e[1].editorId !== editorId;
-    });
-    scheduleNextEvent();
-}
-
-/**
- * Cancel all events from an editor
- */
-function cancelEditor(editorId) {
-    scheduledEvents = scheduledEvents.filter(function(e) {
-        return e[1].editorId !== editorId;
-    });
-    scheduleNextEvent();
-}
-
-/**
- * Cancel all scheduled events
- */
-function cancelAllTags() {
-    scheduledEvents = [];
-    clearCurrentTimer();
-}
-
-/**
- * Reset time delta for resync
- */
-function resetTimeDelta() {
-    cachedTimeDelta = null;
-}
-
-/**
- * Handle messages from main thread
- */
-self.onmessage = function(event) {
-    var data = event.data;
-
-    try {
-        switch (data.type) {
-            case 'init':
-                init(data.sharedBuffer, data.ringBufferBase, data.bufferConstants);
-                self.postMessage({ type: 'initialized' });
-                break;
-
-            case 'setWriterWorker':
-                // Set reference to writer worker (passed as MessagePort)
-                writerWorker = data.port;
-                schedulerLog('[OSCSchedulerWorker] Writer worker connected');
-                break;
-
-            case 'send':
-                // Single send method for both messages and bundles
-                // waitTimeMs is calculated by SuperSonic based on AudioContext time
-                processOSC(data.oscData, data.editorId, data.runTag, data.waitTimeMs);
-                break;
-
-            case 'sendImmediate':
-                // Force immediate send, extracting all messages from bundles
-                // Ignores timestamps - for apps that don't expect scheduling
-                processImmediate(data.oscData);
-                break;
-
-            case 'cancelEditorTag':
-                cancelEditorTag(data.editorId, data.runTag);
-                break;
-
-            case 'cancelEditor':
-                cancelEditor(data.editorId);
-                break;
-
-            case 'cancelAll':
-                cancelAllTags();
-                break;
-
-            case 'getStats':
-                self.postMessage({
-                    type: 'stats',
-                    stats: stats
-                });
-                break;
-
-            default:
-                schedulerWarn('[OSCOutWorker] Unknown message type:', data.type);
-        }
-    } catch (error) {
-        console.error('[OSCOutWorker] Error:', error);
-        self.postMessage({
-            type: 'error',
-            error: error.message
-        });
-    }
-};
-
-schedulerLog('[OSCSchedulerWorker] Script loaded - scheduler only, delegates to writer worker');

package/dist/workers/ring_buffer_worker_base.js

@@ -1,305 +0,0 @@
-/*
-    SuperSonic - SuperCollider AudioWorklet WebAssembly port
-    Copyright (c) 2025 Sam Aaron
-
-    Based on SuperCollider by James McCartney and community
-    GPL v3 or later
-*/
-
-/**
- * Base class for ring buffer workers
- * Provides common functionality for polling ring buffers with Atomics.wait()
- * ES5-compatible for Qt WebEngine
- */
-
-// Ring buffer configuration
-var RingBufferWorkerBase = function(bufferType) {
-    this.bufferType = bufferType; // 'OUT', 'SYSTEM', etc.
-    this.sharedBuffer = null;
-    this.ringBufferBase = null;
-    this.atomicView = null;
-    this.dataView = null;
-    this.uint8View = null;
-    this.bufferConstants = null;
-    this.CONTROL_INDICES = {};
-    this.running = false;
-    this.loggedCorruptionState = false;
-
-    // Statistics
-    this.stats = {
-        messagesReceived: 0,
-        lastSequenceReceived: -1,
-        droppedMessages: 0,
-        wakeups: 0,
-        timeouts: 0
-    };
-};
-
-/**
- * Initialize ring buffer access
- */
-RingBufferWorkerBase.prototype.initRingBuffer = function(buffer, base, constants) {
-    this.sharedBuffer = buffer;
-    this.ringBufferBase = base;
-    this.bufferConstants = constants;
-    this.atomicView = new Int32Array(this.sharedBuffer);
-    this.dataView = new DataView(this.sharedBuffer);
-    this.uint8View = new Uint8Array(this.sharedBuffer);
-
-    // Calculate control indices based on buffer type
-    var headOffset, tailOffset;
-    if (this.bufferType === 'OUT') {
-        headOffset = 8;
-        tailOffset = 12;
-    } else if (this.bufferType === 'SYSTEM') {
-        headOffset = 24;  // system_head offset
-        tailOffset = 28;  // system_tail offset
-    }
-
-    // Debug logging for SYSTEM worker
-    if (this.bufferType === 'SYSTEM') {
-        console.log('[' + this.bufferType + 'Worker] Init params:', {
-            ringBufferBase: base,
-            CONTROL_START: constants.CONTROL_START,
-            headOffset: headOffset,
-            tailOffset: tailOffset,
-            calculatedHeadByteOffset: base + constants.CONTROL_START + headOffset,
-            calculatedHeadIndex: (base + constants.CONTROL_START + headOffset) / 4
-        });
-        console.log('[' + this.bufferType + 'Worker] Buffer constants:', {
-            SYSTEM_BUFFER_START: constants.SYSTEM_BUFFER_START,
-            SYSTEM_BUFFER_SIZE: constants.SYSTEM_BUFFER_SIZE,
-            MESSAGE_MAGIC: constants.MESSAGE_MAGIC,
-            PADDING_MAGIC: constants.PADDING_MAGIC
-        });
-    }
-
-    this.CONTROL_INDICES = {
-        HEAD: (this.ringBufferBase + this.bufferConstants.CONTROL_START + headOffset) / 4,
-        TAIL: (this.ringBufferBase + this.bufferConstants.CONTROL_START + tailOffset) / 4
-    };
-
-    // Debug: log buffer info for SYSTEM
-    if (this.bufferType === 'SYSTEM') {
-        var bufferInfo = this.getBufferInfo();
-        console.log('[' + this.bufferType + 'Worker] Buffer info:', bufferInfo);
-        console.log('[' + this.bufferType + 'Worker] Control indices:', this.CONTROL_INDICES);
-
-        // Check initial buffer state - read first 64 bytes
-        var startPos = this.ringBufferBase + bufferInfo.start;
-        console.log('[' + this.bufferType + 'Worker] First 64 bytes of buffer at position', startPos + ':');
-        for (var i = 0; i < 64; i += 4) {
-            var value = this.dataView.getUint32(startPos + i, true);
-            console.log('  Offset', i + ':', '0x' + value.toString(16).padStart(8, '0'));
-        }
-
-        // Check current head/tail values
-        var currentHead = Atomics.load(this.atomicView, this.CONTROL_INDICES.HEAD);
-        var currentTail = Atomics.load(this.atomicView, this.CONTROL_INDICES.TAIL);
-        console.log('[' + this.bufferType + 'Worker] Initial head:', currentHead, 'tail:', currentTail);
-    }
-};
-
-/**
- * Get buffer start and size based on type
- */
-RingBufferWorkerBase.prototype.getBufferInfo = function() {
-    if (this.bufferType === 'OUT') {
-        return {
-            start: this.bufferConstants.OUT_BUFFER_START,
-            size: this.bufferConstants.OUT_BUFFER_SIZE
-        };
-    } else if (this.bufferType === 'SYSTEM') {
-        return {
-            start: this.bufferConstants.SYSTEM_BUFFER_START,
-            size: this.bufferConstants.SYSTEM_BUFFER_SIZE
-        };
-    }
-    return null;
-};
-
-/**
- * Read all available messages from buffer
- */
-RingBufferWorkerBase.prototype.readMessages = function() {
-    var head = Atomics.load(this.atomicView, this.CONTROL_INDICES.HEAD);
-    var tail = Atomics.load(this.atomicView, this.CONTROL_INDICES.TAIL);
-
-    var messages = [];
-
-    if (head === tail) {
-        return messages; // No messages
-    }
-
-    var bufferInfo = this.getBufferInfo();
-    var currentTail = tail;
-    var messagesRead = 0;
-    var maxMessages = 100;
-
-    while (currentTail !== head && messagesRead < maxMessages) {
-        var readPos = this.ringBufferBase + bufferInfo.start + currentTail;
-
-        // Read message header (now always contiguous due to padding)
-        var magic = this.dataView.getUint32(readPos, true);
-
-        // Check for padding marker - skip to beginning
-        if (magic === this.bufferConstants.PADDING_MAGIC) {
-            currentTail = 0;
-            continue;
-        }
-
-        if (magic !== this.bufferConstants.MESSAGE_MAGIC) {
-            // Only log first few corrupted messages to avoid spamming
-            if (this.stats.droppedMessages < 5) {
-                console.error('[' + this.bufferType + 'Worker] Corrupted message at position', currentTail, 'magic:', magic, 'expected:', this.bufferConstants.MESSAGE_MAGIC);
-            }
-            this.stats.droppedMessages++;
-            // Skip this byte and continue
-            currentTail = (currentTail + 1) % bufferInfo.size;
-            continue;
-        }
-
-        var length = this.dataView.getUint32(readPos + 4, true);
-        var sequence = this.dataView.getUint32(readPos + 8, true);
-        var padding = this.dataView.getUint32(readPos + 12, true);  // unused padding field
-
-        // Validate message length
-        if (length < this.bufferConstants.MESSAGE_HEADER_SIZE || length > bufferInfo.size) {
-            // Only log first few invalid lengths to avoid spamming
-            if (this.stats.droppedMessages < 5) {
-                console.error('[' + this.bufferType + 'Worker] Invalid message length:', length);
-            }
-            this.stats.droppedMessages++;
-            currentTail = (currentTail + 1) % bufferInfo.size;
-            continue;
-        }
-
-        // Check for dropped messages via sequence
-        if (this.stats.lastSequenceReceived >= 0) {
-            var expectedSeq = (this.stats.lastSequenceReceived + 1) & 0xFFFFFFFF;
-            if (sequence !== expectedSeq) {
-                var dropped = (sequence - expectedSeq + 0x100000000) & 0xFFFFFFFF;
-                if (dropped < 1000) { // Sanity check
-                    console.warn('[' + this.bufferType + 'Worker] Detected', dropped, 'dropped messages');
-                    this.stats.droppedMessages += dropped;
-                }
-            }
-        }
-        this.stats.lastSequenceReceived = sequence;
-
-        // Read payload (OSC binary data) - now contiguous due to padding
-        var payloadLength = length - this.bufferConstants.MESSAGE_HEADER_SIZE;
-        var payloadStart = readPos + this.bufferConstants.MESSAGE_HEADER_SIZE;
-
-        // Create a proper copy (not a view into SharedArrayBuffer)
-        var payload = new Uint8Array(payloadLength);
-        for (var i = 0; i < payloadLength; i++) {
-            payload[i] = this.uint8View[payloadStart + i];
-        }
-
-        messages.push({
-            oscData: payload,
-            sequence: sequence
-        });
-
-        // Move to next message
-        currentTail = (currentTail + length) % bufferInfo.size;
-        messagesRead++;
-        this.stats.messagesReceived++;
-    }
-
-    // Update tail pointer (consume messages)
-    if (messagesRead > 0) {
-        Atomics.store(this.atomicView, this.CONTROL_INDICES.TAIL, currentTail);
-    }
-
-    return messages;
-};
-
-/**
- * Main wait loop using Atomics.wait for instant wake
- */
-RingBufferWorkerBase.prototype.waitLoop = function() {
-    var self = this;
-    while (this.running) {
-        try {
-            // Get current HEAD value
-            var currentHead = Atomics.load(this.atomicView, this.CONTROL_INDICES.HEAD);
-            var currentTail = Atomics.load(this.atomicView, this.CONTROL_INDICES.TAIL);
-
-            // If buffer is empty, wait for AudioWorklet to notify us
-            if (currentHead === currentTail) {
-                // Wait for up to 100ms (allows checking stop signal)
-                var result = Atomics.wait(this.atomicView, this.CONTROL_INDICES.HEAD, currentHead, 100);
-
-                if (result === 'ok' || result === 'not-equal') {
-                    // We were notified or value changed!
-                    this.stats.wakeups++;
-                } else if (result === 'timed-out') {
-                    this.stats.timeouts++;
-                    continue; // Check running flag
-                }
-            }
-
-            // Read all available messages
-            var messages = this.readMessages();
-
-            // Debug: log ONCE if we tried to read but got no valid messages due to corruption
-            if (messages.length === 0 && currentHead !== currentTail && this.stats.droppedMessages > 0) {
-                if (this.bufferType === 'SYSTEM' && !this.loggedCorruptionState) {
-                    console.log('[' + this.bufferType + 'Worker] Head != tail (head=' + currentHead + ', tail=' + currentTail + ') but all messages corrupted. Dropped:', this.stats.droppedMessages);
-                    this.loggedCorruptionState = true;
-                }
-            }
-
-            if (messages.length > 0) {
-                // Send to main thread
-                self.postMessage({
-                    type: 'messages',
-                    messages: messages,
-                    stats: {
-                        wakeups: this.stats.wakeups,
-                        timeouts: this.stats.timeouts,
-                        messagesReceived: this.stats.messagesReceived,
-                        droppedMessages: this.stats.droppedMessages
-                    }
-                });
-            }
-
-        } catch (error) {
-            console.error('[' + this.bufferType + 'Worker] Error in wait loop:', error);
-            self.postMessage({
-                type: 'error',
-                error: error.message
-            });
-
-            // Brief pause on error before retrying
-            Atomics.wait(this.atomicView, 0, this.atomicView[0], 10);
-        }
-    }
-};
-
-/**
- * Start the wait loop
- */
-RingBufferWorkerBase.prototype.start = function() {
-    if (!this.sharedBuffer) {
-        console.error('[' + this.bufferType + 'Worker] Cannot start - not initialized');
-        return;
-    }
-
-    if (this.running) {
-        console.warn('[' + this.bufferType + 'Worker] Already running');
-        return;
-    }
-
-    this.running = true;
-    this.waitLoop();
-};
-
-/**
- * Stop the wait loop
- */
-RingBufferWorkerBase.prototype.stop = function() {
-    this.running = false;
-};

package/dist/workers/system_worker.js

@@ -1,64 +0,0 @@
-/*
-    SuperSonic - SuperCollider AudioWorklet WebAssembly port
-    Copyright (c) 2025 Sam Aaron
-
-    Based on SuperCollider by James McCartney and community
-    GPL v3 or later
-*/
-
-/**
- * System Message Worker - Handles internal SuperSonic messages
- * Uses the shared ring buffer base class
- * ES5-compatible for Qt WebEngine
- */
-
-// Import the base class
-importScripts('ring_buffer_worker_base.js');
-
-// Create worker instance for SYSTEM buffer
-var worker = new RingBufferWorkerBase('SYSTEM');
-
-// Override postMessage to maintain compatibility
-worker.postMessage = self.postMessage.bind(self);
-
-/**
- * Handle messages from main thread
- */
-self.onmessage = function(event) {
-    var data = event.data;
-
-    try {
-        switch (data.type) {
-            case 'init':
-                worker.initRingBuffer(data.sharedBuffer, data.ringBufferBase, data.bufferConstants);
-                self.postMessage({ type: 'initialized' });
-                break;
-
-            case 'start':
-                worker.start();
-                break;
-
-            case 'stop':
-                worker.stop();
-                break;
-
-            case 'getStats':
-                self.postMessage({
-                    type: 'stats',
-                    stats: worker.stats
-                });
-                break;
-
-            default:
-                console.warn('[SystemWorker] Unknown message type:', data.type);
-        }
-    } catch (error) {
-        console.error('[SystemWorker] Error:', error);
-        self.postMessage({
-            type: 'error',
-            error: error.message
-        });
-    }
-};
-
-console.log('[SystemWorker] Script loaded');