supersonic-scsynth 0.1.9 → 0.2.1

package/dist/supersonic.js

@@ -769,11 +769,15 @@ var ScsynthOSC = class {
   constructor() {
     this.workers = {
       oscOut: null,
+      // Scheduler worker (now also writes directly to ring buffer)
       oscIn: null,
       debug: null
     };
     this.callbacks = {
-      onOSCMessage: null,
+      onRawOSC: null,
+      // Raw binary OSC callback
+      onParsedOSC: null,
+      // Parsed OSC callback
       onDebugMessage: null,
       onError: null,
       onInitialized: null
@@ -795,12 +799,12 @@ var ScsynthOSC = class {
     this.ringBufferBase = ringBufferBase;
     this.bufferConstants = bufferConstants;
     try {
-      this.workers.oscOut = new Worker("./dist/workers/osc_out_worker.js");
-      this.workers.oscIn = new Worker("./dist/workers/osc_in_worker.js");
-      this.workers.debug = new Worker("./dist/workers/debug_worker.js");
+      this.workers.oscOut = new Worker(new URL("./workers/osc_out_prescheduler_worker.js", import.meta.url));
+      this.workers.oscIn = new Worker(new URL("./workers/osc_in_worker.js", import.meta.url));
+      this.workers.debug = new Worker(new URL("./workers/debug_worker.js", import.meta.url));
       this.setupWorkerHandlers();
       const initPromises = [
-        this.initWorker(this.workers.oscOut, "OSC OUT"),
+        this.initWorker(this.workers.oscOut, "OSC SCHEDULER+WRITER"),
         this.initWorker(this.workers.oscIn, "OSC IN"),
         this.initWorker(this.workers.debug, "DEBUG")
       ];
@@ -851,19 +855,24 @@ var ScsynthOSC = class {
       const data = event.data;
       switch (data.type) {
         case "messages":
-          if (this.callbacks.onOSCMessage) {
-            data.messages.forEach((msg) => {
-              if (msg.oscData) {
-                try {
-                  const options = { metadata: false, unpackSingleArgs: false };
-                  const decoded = osc_default.readPacket(msg.oscData, options);
-                  this.callbacks.onOSCMessage(decoded);
-                } catch (e) {
-                  console.error("[ScsynthOSC] Failed to decode OSC message:", e, msg);
-                }
+          data.messages.forEach((msg) => {
+            if (!msg.oscData) return;
+            if (this.callbacks.onRawOSC) {
+              this.callbacks.onRawOSC({
+                oscData: msg.oscData,
+                sequence: msg.sequence
+              });
+            }
+            if (this.callbacks.onParsedOSC) {
+              try {
+                const options = { metadata: false, unpackSingleArgs: false };
+                const decoded = osc_default.readPacket(msg.oscData, options);
+                this.callbacks.onParsedOSC(decoded);
+              } catch (e) {
+                console.error("[ScsynthOSC] Failed to decode OSC message:", e, msg);
               }
-            });
-          }
+            }
+          });
           break;
         case "error":
           console.error("[ScsynthOSC] OSC IN error:", data.error);
@@ -906,23 +915,24 @@ var ScsynthOSC = class {
   /**
    * Send OSC data (message or bundle)
    * - OSC messages are sent immediately
-   * - OSC bundles are scheduled based on waitTimeMs (calculated by SuperSonic)
+   * - OSC bundles are scheduled based on audioTimeS (target audio time)
    *
    * @param {Uint8Array} oscData - Binary OSC data (message or bundle)
-   * @param {Object} options - Optional metadata (editorId, runTag, waitTimeMs)
+   * @param {Object} options - Optional metadata (editorId, runTag, audioTimeS, currentTimeS)
    */
   send(oscData, options = {}) {
     if (!this.initialized) {
       console.error("[ScsynthOSC] Not initialized");
       return;
     }
-    const { editorId = 0, runTag = "", waitTimeMs = null } = options;
+    const { editorId = 0, runTag = "", audioTimeS = null, currentTimeS = null } = options;
     this.workers.oscOut.postMessage({
       type: "send",
       oscData,
       editorId,
       runTag,
-      waitTimeMs
+      audioTimeS,
+      currentTimeS
     });
   }
   /**
@@ -1021,10 +1031,16 @@ var ScsynthOSC = class {
     });
   }
   /**
-   * Set callback for OSC messages received from scsynth
+   * Set callback for raw binary OSC messages received from scsynth
    */
-  onOSCMessage(callback) {
-    this.callbacks.onOSCMessage = callback;
+  onRawOSC(callback) {
+    this.callbacks.onRawOSC = callback;
+  }
+  /**
+   * Set callback for parsed OSC messages received from scsynth
+   */
+  onParsedOSC(callback) {
+    this.callbacks.onParsedOSC = callback;
   }
   /**
    * Set callback for debug messages
@@ -1584,8 +1600,289 @@ var MemPool = class {
 var __blockDataAddress = (blockAddress) => blockAddress > 0 ? blockAddress + SIZEOF_MEM_BLOCK : 0;
 var __blockSelfAddress = (dataAddress) => dataAddress > 0 ? dataAddress - SIZEOF_MEM_BLOCK : 0;
 
+// js/timing_constants.js
+var NTP_EPOCH_OFFSET = 2208988800;
+var DRIFT_UPDATE_INTERVAL_MS = 15e3;
+
 // js/supersonic.js
-var SuperSonic = class {
+var BufferManager = class {
+  constructor(options) {
+    const {
+      audioContext,
+      sharedBuffer,
+      bufferPool,
+      allocatedBuffers,
+      resolveAudioPath,
+      registerPendingOp
+    } = options;
+    this.audioContext = audioContext;
+    this.sharedBuffer = sharedBuffer;
+    this.bufferPool = bufferPool;
+    this.allocatedBuffers = allocatedBuffers;
+    this.resolveAudioPath = resolveAudioPath;
+    this.registerPendingOp = registerPendingOp;
+    this.bufferLocks = /* @__PURE__ */ new Map();
+    this.GUARD_BEFORE = 3;
+    this.GUARD_AFTER = 1;
+    this.MAX_BUFFERS = 1024;
+  }
+  #validateBufferNumber(bufnum) {
+    if (!Number.isInteger(bufnum) || bufnum < 0 || bufnum >= this.MAX_BUFFERS) {
+      throw new Error(`Invalid buffer number ${bufnum} (must be 0-${this.MAX_BUFFERS - 1})`);
+    }
+  }
+  async prepareFromFile(params) {
+    const {
+      bufnum,
+      path,
+      startFrame = 0,
+      numFrames = 0,
+      channels = null
+    } = params;
+    this.#validateBufferNumber(bufnum);
+    let allocatedPtr = null;
+    let pendingToken = null;
+    let allocationRegistered = false;
+    const releaseLock = await this.#acquireBufferLock(bufnum);
+    let lockReleased = false;
+    try {
+      await this.#awaitPendingReplacement(bufnum);
+      const resolvedPath = this.resolveAudioPath(path);
+      const response = await fetch(resolvedPath);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${resolvedPath}: ${response.status} ${response.statusText}`);
+      }
+      const arrayBuffer = await response.arrayBuffer();
+      const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
+      const start = Math.max(0, Math.floor(startFrame || 0));
+      const availableFrames = audioBuffer.length - start;
+      const framesRequested = numFrames && numFrames > 0 ? Math.min(Math.floor(numFrames), availableFrames) : availableFrames;
+      if (framesRequested <= 0) {
+        throw new Error(`No audio frames available for buffer ${bufnum} from ${path}`);
+      }
+      const selectedChannels = this.#normalizeChannels(channels, audioBuffer.numberOfChannels);
+      const numChannels = selectedChannels.length;
+      const totalSamples = framesRequested * numChannels + (this.GUARD_BEFORE + this.GUARD_AFTER) * numChannels;
+      allocatedPtr = this.#malloc(totalSamples);
+      const interleaved = new Float32Array(totalSamples);
+      const dataOffset = this.GUARD_BEFORE * numChannels;
+      for (let frame = 0; frame < framesRequested; frame++) {
+        for (let ch = 0; ch < numChannels; ch++) {
+          const sourceChannel = selectedChannels[ch];
+          const channelData = audioBuffer.getChannelData(sourceChannel);
+          interleaved[dataOffset + frame * numChannels + ch] = channelData[start + frame];
+        }
+      }
+      this.#writeToSharedBuffer(allocatedPtr, interleaved);
+      const sizeBytes = interleaved.length * 4;
+      const { uuid, allocationComplete } = this.#registerPending(bufnum);
+      pendingToken = uuid;
+      this.#recordAllocation(bufnum, allocatedPtr, sizeBytes, uuid, allocationComplete);
+      allocationRegistered = true;
+      const managedCompletion = this.#attachFinalizer(bufnum, uuid, allocationComplete);
+      releaseLock();
+      lockReleased = true;
+      return {
+        ptr: allocatedPtr,
+        numFrames: framesRequested,
+        numChannels,
+        sampleRate: audioBuffer.sampleRate,
+        uuid,
+        allocationComplete: managedCompletion
+      };
+    } catch (error) {
+      if (allocationRegistered && pendingToken) {
+        this.#finalizeReplacement(bufnum, pendingToken, false);
+      } else if (allocatedPtr) {
+        this.bufferPool.free(allocatedPtr);
+      }
+      throw error;
+    } finally {
+      if (!lockReleased) {
+        releaseLock();
+      }
+    }
+  }
+  async prepareEmpty(params) {
+    const {
+      bufnum,
+      numFrames,
+      numChannels = 1,
+      sampleRate = null
+    } = params;
+    this.#validateBufferNumber(bufnum);
+    let allocationRegistered = false;
+    let pendingToken = null;
+    let allocatedPtr = null;
+    if (!Number.isFinite(numFrames) || numFrames <= 0) {
+      throw new Error(`/b_alloc requires a positive number of frames (got ${numFrames})`);
+    }
+    if (!Number.isFinite(numChannels) || numChannels <= 0) {
+      throw new Error(`/b_alloc requires a positive channel count (got ${numChannels})`);
+    }
+    const roundedFrames = Math.floor(numFrames);
+    const roundedChannels = Math.floor(numChannels);
+    const totalSamples = roundedFrames * roundedChannels + (this.GUARD_BEFORE + this.GUARD_AFTER) * roundedChannels;
+    const releaseLock = await this.#acquireBufferLock(bufnum);
+    let lockReleased = false;
+    try {
+      await this.#awaitPendingReplacement(bufnum);
+      allocatedPtr = this.#malloc(totalSamples);
+      const interleaved = new Float32Array(totalSamples);
+      this.#writeToSharedBuffer(allocatedPtr, interleaved);
+      const sizeBytes = interleaved.length * 4;
+      const { uuid, allocationComplete } = this.#registerPending(bufnum);
+      pendingToken = uuid;
+      this.#recordAllocation(bufnum, allocatedPtr, sizeBytes, uuid, allocationComplete);
+      allocationRegistered = true;
+      const managedCompletion = this.#attachFinalizer(bufnum, uuid, allocationComplete);
+      releaseLock();
+      lockReleased = true;
+      return {
+        ptr: allocatedPtr,
+        numFrames: roundedFrames,
+        numChannels: roundedChannels,
+        sampleRate: sampleRate || this.audioContext.sampleRate,
+        uuid,
+        allocationComplete: managedCompletion
+      };
+    } catch (error) {
+      if (allocationRegistered && pendingToken) {
+        this.#finalizeReplacement(bufnum, pendingToken, false);
+      } else if (allocatedPtr) {
+        this.bufferPool.free(allocatedPtr);
+      }
+      throw error;
+    } finally {
+      if (!lockReleased) {
+        releaseLock();
+      }
+    }
+  }
+  #normalizeChannels(requestedChannels, fileChannels) {
+    if (!requestedChannels || requestedChannels.length === 0) {
+      return Array.from({ length: fileChannels }, (_, i) => i);
+    }
+    requestedChannels.forEach((channel) => {
+      if (!Number.isInteger(channel) || channel < 0 || channel >= fileChannels) {
+        throw new Error(`Channel ${channel} is out of range (file has ${fileChannels} channels)`);
+      }
+    });
+    return requestedChannels;
+  }
+  #malloc(totalSamples) {
+    const bytesNeeded = totalSamples * 4;
+    const ptr = this.bufferPool.malloc(bytesNeeded);
+    if (ptr === 0) {
+      const stats = this.bufferPool.stats();
+      const availableMB = ((stats.available || 0) / (1024 * 1024)).toFixed(2);
+      const totalMB = ((stats.total || 0) / (1024 * 1024)).toFixed(2);
+      const requestedMB = (bytesNeeded / (1024 * 1024)).toFixed(2);
+      throw new Error(
+        `Buffer pool allocation failed: requested ${requestedMB}MB, available ${availableMB}MB of ${totalMB}MB total`
+      );
+    }
+    return ptr;
+  }
+  #writeToSharedBuffer(ptr, data) {
+    const heap = new Float32Array(this.sharedBuffer, ptr, data.length);
+    heap.set(data);
+  }
+  #registerPending(bufnum) {
+    if (!this.registerPendingOp) {
+      return {
+        uuid: crypto.randomUUID(),
+        allocationComplete: Promise.resolve()
+      };
+    }
+    const uuid = crypto.randomUUID();
+    const allocationComplete = this.registerPendingOp(uuid, bufnum);
+    return { uuid, allocationComplete };
+  }
+  async #acquireBufferLock(bufnum) {
+    const prev = this.bufferLocks.get(bufnum) || Promise.resolve();
+    let releaseLock;
+    const current = new Promise((resolve) => {
+      releaseLock = resolve;
+    });
+    this.bufferLocks.set(bufnum, prev.then(() => current));
+    await prev;
+    return () => {
+      if (releaseLock) {
+        releaseLock();
+        releaseLock = null;
+      }
+      if (this.bufferLocks.get(bufnum) === current) {
+        this.bufferLocks.delete(bufnum);
+      }
+    };
+  }
+  #recordAllocation(bufnum, ptr, sizeBytes, pendingToken, pendingPromise) {
+    const previousEntry = this.allocatedBuffers.get(bufnum);
+    const entry = {
+      ptr,
+      size: sizeBytes,
+      pendingToken,
+      pendingPromise,
+      previousAllocation: previousEntry ? { ptr: previousEntry.ptr, size: previousEntry.size } : null
+    };
+    this.allocatedBuffers.set(bufnum, entry);
+    return entry;
+  }
+  async #awaitPendingReplacement(bufnum) {
+    const existing = this.allocatedBuffers.get(bufnum);
+    if (existing && existing.pendingToken && existing.pendingPromise) {
+      try {
+        await existing.pendingPromise;
+      } catch {
+      }
+    }
+  }
+  #attachFinalizer(bufnum, pendingToken, promise) {
+    if (!promise || typeof promise.then !== "function") {
+      this.#finalizeReplacement(bufnum, pendingToken, true);
+      return Promise.resolve();
+    }
+    return promise.then((value) => {
+      this.#finalizeReplacement(bufnum, pendingToken, true);
+      return value;
+    }).catch((error) => {
+      this.#finalizeReplacement(bufnum, pendingToken, false);
+      throw error;
+    });
+  }
+  #finalizeReplacement(bufnum, pendingToken, success) {
+    const entry = this.allocatedBuffers.get(bufnum);
+    if (!entry || entry.pendingToken !== pendingToken) {
+      return;
+    }
+    const previous = entry.previousAllocation;
+    if (success) {
+      entry.pendingToken = null;
+      entry.pendingPromise = null;
+      entry.previousAllocation = null;
+      if (previous?.ptr) {
+        this.bufferPool.free(previous.ptr);
+      }
+      return;
+    }
+    if (entry.ptr) {
+      this.bufferPool.free(entry.ptr);
+    }
+    entry.pendingPromise = null;
+    if (previous?.ptr) {
+      this.allocatedBuffers.set(bufnum, {
+        ptr: previous.ptr,
+        size: previous.size,
+        pendingToken: null,
+        previousAllocation: null
+      });
+    } else {
+      this.allocatedBuffers.delete(bufnum);
+    }
+  }
+};
+var SuperSonic = class _SuperSonic {
   // Expose OSC utilities as static methods
   static osc = {
     encode: (message) => osc_default.writePacket(message),
@@ -1604,11 +1901,14 @@ var SuperSonic = class {
     this.wasmModule = null;
     this.wasmInstance = null;
     this.bufferPool = null;
+    this.bufferManager = null;
+    this.loadedSynthDefs = /* @__PURE__ */ new Set();
     this.pendingBufferOps = /* @__PURE__ */ new Map();
-    this.wasmTimeOffset = null;
     this._timeOffsetPromise = null;
     this._resolveTimeOffset = null;
-    this.onMessageReceived = null;
+    this._localClockOffsetTimer = null;
+    this.onOSC = null;
+    this.onMessage = null;
     this.onMessageSent = null;
     this.onMetricsUpdate = null;
     this.onStatusUpdate = null;
@@ -1695,21 +1995,6 @@ var SuperSonic = class {
     });
     console.log("[SuperSonic] Buffer pool initialized: 128MB at offset 64MB");
   }
-  /**
-   * Calculate time offset (AudioContext → NTP conversion)
-   * Called when AudioContext is in 'running' state to ensure accurate timing
-   */
-  #calculateTimeOffset() {
-    const SECONDS_1900_TO_1970 = 2208988800;
-    const audioContextTime = this.audioContext.currentTime;
-    const unixSeconds = Date.now() / 1e3;
-    this.wasmTimeOffset = SECONDS_1900_TO_1970 + unixSeconds - audioContextTime;
-    if (this._resolveTimeOffset) {
-      this._resolveTimeOffset(this.wasmTimeOffset);
-      this._resolveTimeOffset = null;
-    }
-    return this.wasmTimeOffset;
-  }
   /**
    * Initialize AudioContext and set up time offset calculation
    */
@@ -1729,14 +2014,17 @@ var SuperSonic = class {
       document.addEventListener("click", resumeContext, { once: true });
       document.addEventListener("touchstart", resumeContext, { once: true });
     }
-    this.audioContext.addEventListener("statechange", () => {
-      if (this.audioContext.state === "running" && this._resolveTimeOffset) {
-        this.#calculateTimeOffset();
-      }
+    return this.audioContext;
+  }
+  #initializeBufferManager() {
+    this.bufferManager = new BufferManager({
+      audioContext: this.audioContext,
+      sharedBuffer: this.sharedBuffer,
+      bufferPool: this.bufferPool,
+      allocatedBuffers: this.allocatedBuffers,
+      resolveAudioPath: (path) => this._resolveAudioPath(path),
+      registerPendingOp: (uuid, bufnum, timeoutMs) => this.#createPendingBufferOperation(uuid, bufnum, timeoutMs)
     });
-    if (this.audioContext.state === "running") {
-      this.#calculateTimeOffset();
-    }
   }
   /**
    * Load WASM manifest to get the current hashed filename
@@ -1782,12 +2070,10 @@ var SuperSonic = class {
       type: "init",
       sharedBuffer: this.sharedBuffer
     });
-    const timeOffset = await this._timeOffsetPromise;
     this.workletNode.port.postMessage({
       type: "loadWasm",
       wasmBytes,
-      wasmMemory: this.wasmMemory,
-      timeOffset
+      wasmMemory: this.wasmMemory
     });
     await this.#waitForWorkletInit();
   }
@@ -1796,15 +2082,20 @@ var SuperSonic = class {
    */
   async #initializeOSC() {
     this.osc = new ScsynthOSC();
-    this.osc.onOSCMessage((msg) => {
+    this.osc.onRawOSC((msg) => {
+      if (this.onOSC) {
+        this.onOSC(msg);
+      }
+    });
+    this.osc.onParsedOSC((msg) => {
       if (msg.address === "/buffer/freed") {
         this._handleBufferFreed(msg.args);
       } else if (msg.address === "/buffer/allocated") {
         this._handleBufferAllocated(msg.args);
       }
-      if (this.onMessageReceived) {
+      if (this.onMessage) {
         this.stats.messagesReceived++;
-        this.onMessageReceived(msg);
+        this.onMessage(msg);
       }
     });
     this.osc.onDebugMessage((msg) => {
@@ -1867,6 +2158,7 @@ var SuperSonic = class {
       this.checkCapabilities();
       this.#initializeSharedMemory();
       this.#initializeAudioContext();
+      this.#initializeBufferManager();
       const wasmBytes = await this.#loadWasm();
       await this.#initializeAudioWorklet(wasmBytes);
       await this.#initializeOSC();
@@ -1911,10 +2203,20 @@ var SuperSonic = class {
               console.warn("[SuperSonic] Warning: ringBufferBase not provided by worklet");
             }
             if (event.data.bufferConstants !== void 0) {
+              console.log("[SuperSonic] Received bufferConstants from worklet");
               this.bufferConstants = event.data.bufferConstants;
+              console.log("[SuperSonic] Initializing NTP timing");
+              this.initializeNTPTiming();
+              this.#startDriftOffsetTimer();
+              console.log("[SuperSonic] Resolving time offset promise, _resolveTimeOffset=", this._resolveTimeOffset);
+              if (this._resolveTimeOffset) {
+                this._resolveTimeOffset();
+                this._resolveTimeOffset = null;
+              }
             } else {
               console.warn("[SuperSonic] Warning: bufferConstants not provided by worklet");
             }
+            console.log("[SuperSonic] Calling resolve() for worklet initialization");
             resolve();
           } else {
             reject(new Error(event.data.error || "AudioWorklet initialization failed"));
@@ -1997,12 +2299,7 @@ var SuperSonic = class {
    * sonic.send('/n_set', 1000, 'freq', 440.0, 'amp', 0.5);
    */
   async send(address, ...args) {
-    if (!this.initialized) {
-      throw new Error("SuperSonic not initialized. Call init() first.");
-    }
-    if (this._isBufferAllocationCommand(address)) {
-      return await this._handleBufferCommand(address, args);
-    }
+    this.#ensureInitialized("send OSC messages");
     const oscArgs = args.map((arg) => {
       if (typeof arg === "string") {
         return { type: "s", value: arg };
@@ -2014,108 +2311,9 @@ var SuperSonic = class {
         throw new Error(`Unsupported argument type: ${typeof arg}`);
       }
     });
-    const message = {
-      address,
-      args: oscArgs
-    };
-    const oscData = osc_default.writePacket(message);
-    this.sendOSC(oscData);
-  }
-  _isBufferAllocationCommand(address) {
-    return [
-      "/b_allocRead",
-      "/b_allocReadChannel",
-      "/b_read",
-      "/b_readChannel"
-      // NOTE: /b_alloc and /b_free are NOT intercepted
-    ].includes(address);
-  }
-  async _handleBufferCommand(address, args) {
-    switch (address) {
-      case "/b_allocRead":
-        return await this._allocReadBuffer(...args);
-      case "/b_allocReadChannel":
-        return await this._allocReadChannelBuffer(...args);
-      case "/b_read":
-        return await this._readBuffer(...args);
-      case "/b_readChannel":
-        return await this._readChannelBuffer(...args);
-    }
-  }
-  /**
-   * /b_allocRead bufnum path [startFrame numFrames completion]
-   */
-  async _allocReadBuffer(bufnum, path, startFrame = 0, numFrames = 0, completionMsg = null) {
-    let allocatedPtr = null;
-    const GUARD_BEFORE = 3;
-    const GUARD_AFTER = 1;
-    try {
-      const url = this._resolveAudioPath(path);
-      const response = await fetch(url);
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-      const arrayBuffer = await response.arrayBuffer();
-      const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
-      const actualStartFrame = startFrame || 0;
-      const actualNumFrames = numFrames || audioBuffer.length - actualStartFrame;
-      const framesToRead = Math.min(actualNumFrames, audioBuffer.length - actualStartFrame);
-      if (framesToRead <= 0) {
-        throw new Error(`Invalid frame range: start=${actualStartFrame}, numFrames=${actualNumFrames}, fileLength=${audioBuffer.length}`);
-      }
-      const numChannels = audioBuffer.numberOfChannels;
-      const guardSamples = (GUARD_BEFORE + GUARD_AFTER) * numChannels;
-      const interleavedData = new Float32Array(framesToRead * numChannels + guardSamples);
-      const dataOffset = GUARD_BEFORE * numChannels;
-      for (let frame = 0; frame < framesToRead; frame++) {
-        for (let ch = 0; ch < numChannels; ch++) {
-          const channelData = audioBuffer.getChannelData(ch);
-          interleavedData[dataOffset + frame * numChannels + ch] = channelData[actualStartFrame + frame];
-        }
-      }
-      const bytesNeeded = interleavedData.length * 4;
-      allocatedPtr = this.bufferPool.malloc(bytesNeeded);
-      if (allocatedPtr === 0) {
-        throw new Error("Buffer pool allocation failed (out of memory)");
-      }
-      const wasmHeap = new Float32Array(
-        this.sharedBuffer,
-        allocatedPtr,
-        interleavedData.length
-      );
-      wasmHeap.set(interleavedData);
-      this.allocatedBuffers.set(bufnum, {
-        ptr: allocatedPtr,
-        size: bytesNeeded
-      });
-      const uuid = crypto.randomUUID();
-      const allocationComplete = new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
-          this.pendingBufferOps.delete(uuid);
-          reject(new Error(`Timeout waiting for buffer ${bufnum} allocation`));
-        }, 5e3);
-        this.pendingBufferOps.set(uuid, { resolve, reject, timeout });
-      });
-      await this.send(
-        "/b_allocPtr",
-        bufnum,
-        allocatedPtr,
-        framesToRead,
-        numChannels,
-        audioBuffer.sampleRate,
-        uuid
-      );
-      await allocationComplete;
-      if (completionMsg) {
-      }
-    } catch (error) {
-      if (allocatedPtr) {
-        this.bufferPool.free(allocatedPtr);
-        this.allocatedBuffers.delete(bufnum);
-      }
-      console.error(`[SuperSonic] Buffer ${bufnum} load failed:`, error);
-      throw error;
-    }
+    const message = { address, args: oscArgs };
+    const oscData = _SuperSonic.osc.encode(message);
+    return this.sendOSC(oscData);
   }
   /**
    * Resolve audio file path to full URL
@@ -2131,17 +2329,45 @@ var SuperSonic = class {
     }
     return this.sampleBaseURL + scPath;
   }
+  #ensureInitialized(actionDescription = "perform this operation") {
+    if (!this.initialized) {
+      throw new Error(`SuperSonic not initialized. Call init() before attempting to ${actionDescription}.`);
+    }
+  }
+  #createPendingBufferOperation(uuid, bufnum, timeoutMs = 3e4) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingBufferOps.delete(uuid);
+        reject(new Error(`Buffer ${bufnum} allocation timeout (${timeoutMs}ms)`));
+      }, timeoutMs);
+      this.pendingBufferOps.set(uuid, { resolve, reject, timeout });
+    });
+  }
   /**
    * Handle /buffer/freed message from WASM
    */
   _handleBufferFreed(args) {
     const bufnum = args[0];
-    const offset = args[1];
+    const freedPtr = args[1];
     const bufferInfo = this.allocatedBuffers.get(bufnum);
-    if (bufferInfo) {
+    if (!bufferInfo) {
+      if (typeof freedPtr === "number" && freedPtr !== 0) {
+        this.bufferPool.free(freedPtr);
+      }
+      return;
+    }
+    if (typeof freedPtr === "number" && freedPtr === bufferInfo.ptr) {
       this.bufferPool.free(bufferInfo.ptr);
       this.allocatedBuffers.delete(bufnum);
+      return;
+    }
+    if (typeof freedPtr === "number" && bufferInfo.previousAllocation && bufferInfo.previousAllocation.ptr === freedPtr) {
+      this.bufferPool.free(freedPtr);
+      bufferInfo.previousAllocation = null;
+      return;
     }
+    this.bufferPool.free(bufferInfo.ptr);
+    this.allocatedBuffers.delete(bufnum);
   }
   /**
    * Handle /buffer/allocated message with UUID correlation
@@ -2156,134 +2382,26 @@ var SuperSonic = class {
       this.pendingBufferOps.delete(uuid);
     }
   }
-  /**
-   * /b_allocReadChannel bufnum path [startFrame numFrames channel1 channel2 ... completion]
-   * Load specific channels from an audio file
-   */
-  async _allocReadChannelBuffer(bufnum, path, startFrame = 0, numFrames = 0, ...channelsAndCompletion) {
-    let allocatedPtr = null;
-    const GUARD_BEFORE = 3;
-    const GUARD_AFTER = 1;
-    try {
-      const channels = [];
-      let completionMsg = null;
-      for (let i = 0; i < channelsAndCompletion.length; i++) {
-        if (typeof channelsAndCompletion[i] === "number" && Number.isInteger(channelsAndCompletion[i])) {
-          channels.push(channelsAndCompletion[i]);
-        } else {
-          completionMsg = channelsAndCompletion[i];
-          break;
-        }
-      }
-      const url = this._resolveAudioPath(path);
-      const response = await fetch(url);
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-      const arrayBuffer = await response.arrayBuffer();
-      const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
-      const actualStartFrame = startFrame || 0;
-      const actualNumFrames = numFrames || audioBuffer.length - actualStartFrame;
-      const framesToRead = Math.min(actualNumFrames, audioBuffer.length - actualStartFrame);
-      if (framesToRead <= 0) {
-        throw new Error(`Invalid frame range: start=${actualStartFrame}, numFrames=${actualNumFrames}, fileLength=${audioBuffer.length}`);
-      }
-      const fileChannels = audioBuffer.numberOfChannels;
-      const selectedChannels = channels.length > 0 ? channels : Array.from({ length: fileChannels }, (_, i) => i);
-      for (const ch of selectedChannels) {
-        if (ch < 0 || ch >= fileChannels) {
-          throw new Error(`Invalid channel ${ch} (file has ${fileChannels} channels)`);
-        }
-      }
-      const numChannels = selectedChannels.length;
-      const guardSamples = (GUARD_BEFORE + GUARD_AFTER) * numChannels;
-      const interleavedData = new Float32Array(framesToRead * numChannels + guardSamples);
-      const dataOffset = GUARD_BEFORE * numChannels;
-      for (let frame = 0; frame < framesToRead; frame++) {
-        for (let ch = 0; ch < numChannels; ch++) {
-          const fileChannel = selectedChannels[ch];
-          const channelData = audioBuffer.getChannelData(fileChannel);
-          interleavedData[dataOffset + frame * numChannels + ch] = channelData[actualStartFrame + frame];
-        }
-      }
-      const bytesNeeded = interleavedData.length * 4;
-      allocatedPtr = this.bufferPool.malloc(bytesNeeded);
-      if (allocatedPtr === 0) {
-        throw new Error("Buffer pool allocation failed (out of memory)");
-      }
-      const wasmHeap = new Float32Array(this.sharedBuffer, allocatedPtr, interleavedData.length);
-      wasmHeap.set(interleavedData);
-      this.allocatedBuffers.set(bufnum, { ptr: allocatedPtr, size: bytesNeeded });
-      await this.send("/b_allocPtr", bufnum, allocatedPtr, framesToRead, numChannels, audioBuffer.sampleRate);
-      if (completionMsg) {
-      }
-    } catch (error) {
-      if (allocatedPtr) {
-        this.bufferPool.free(allocatedPtr);
-        this.allocatedBuffers.delete(bufnum);
-      }
-      console.error(`[SuperSonic] Buffer ${bufnum} load failed:`, error);
-      throw error;
-    }
-  }
-  /**
-   * /b_read bufnum path [startFrame numFrames bufStartFrame leaveOpen completion]
-   * Read file into existing buffer
-   */
-  async _readBuffer(bufnum, path, startFrame = 0, numFrames = 0, bufStartFrame = 0, leaveOpen = 0, completionMsg = null) {
-    console.warn("[SuperSonic] /b_read requires pre-allocated buffer - not yet implemented");
-    throw new Error("/b_read not yet implemented (requires /b_alloc first)");
-  }
-  /**
-   * /b_readChannel bufnum path [startFrame numFrames bufStartFrame leaveOpen channel1 channel2 ... completion]
-   * Read specific channels into existing buffer
-   */
-  async _readChannelBuffer(bufnum, path, startFrame = 0, numFrames = 0, bufStartFrame = 0, leaveOpen = 0, ...channelsAndCompletion) {
-    console.warn("[SuperSonic] /b_readChannel requires pre-allocated buffer - not yet implemented");
-    throw new Error("/b_readChannel not yet implemented (requires /b_alloc first)");
-  }
   /**
    * Send pre-encoded OSC bytes to scsynth
    * @param {ArrayBuffer|Uint8Array} oscData - Pre-encoded OSC data
    * @param {Object} options - Send options
    */
-  sendOSC(oscData, options = {}) {
-    if (!this.initialized) {
-      throw new Error("Not initialized. Call init() first.");
-    }
-    let uint8Data;
-    if (oscData instanceof ArrayBuffer) {
-      uint8Data = new Uint8Array(oscData);
-    } else if (oscData instanceof Uint8Array) {
-      uint8Data = oscData;
-    } else {
-      throw new Error("oscData must be ArrayBuffer or Uint8Array");
-    }
+  async sendOSC(oscData, options = {}) {
+    this.#ensureInitialized("send OSC data");
+    const uint8Data = this.#toUint8Array(oscData);
+    const preparedData = await this.#prepareOutboundPacket(uint8Data);
     this.stats.messagesSent++;
     if (this.onMessageSent) {
-      this.onMessageSent(uint8Data);
-    }
-    let waitTimeMs = null;
-    if (uint8Data.length >= 16) {
-      const header = String.fromCharCode.apply(null, uint8Data.slice(0, 8));
-      if (header === "#bundle\0") {
-        if (this.wasmTimeOffset === null) {
-          console.warn("[SuperSonic] Time offset not yet calculated, calculating now");
-          this.#calculateTimeOffset();
-        }
-        const view = new DataView(uint8Data.buffer, uint8Data.byteOffset);
-        const ntpSeconds = view.getUint32(8, false);
-        const ntpFraction = view.getUint32(12, false);
-        if (!(ntpSeconds === 0 && (ntpFraction === 0 || ntpFraction === 1))) {
-          const ntpTimeS = ntpSeconds + ntpFraction / 4294967296;
-          const audioTimeS = ntpTimeS - this.wasmTimeOffset;
-          const currentAudioTimeS = this.audioContext.currentTime;
-          const latencyS = 0.05;
-          waitTimeMs = (audioTimeS - currentAudioTimeS - latencyS) * 1e3;
-        }
-      }
+      this.onMessageSent(preparedData);
+    }
+    const timing = this.#calculateBundleWait(preparedData);
+    const sendOptions = { ...options };
+    if (timing) {
+      sendOptions.audioTimeS = timing.audioTimeS;
+      sendOptions.currentTimeS = timing.currentTimeS;
     }
-    this.osc.send(uint8Data, { ...options, waitTimeMs });
+    this.osc.send(preparedData, sendOptions);
   }
   /**
    * Get current status
@@ -2301,6 +2419,7 @@ var SuperSonic = class {
    */
   async destroy() {
     console.log("[SuperSonic] Destroying...");
+    this.#stopDriftOffsetTimer();
     if (this.osc) {
       this.osc.terminate();
       this.osc = null;
@@ -2313,10 +2432,32 @@ var SuperSonic = class {
       await this.audioContext.close();
       this.audioContext = null;
     }
+    for (const [uuid, pending] of this.pendingBufferOps.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("SuperSonic instance destroyed"));
+    }
+    this.pendingBufferOps.clear();
     this.sharedBuffer = null;
     this.initialized = false;
+    this.bufferManager = null;
+    this.allocatedBuffers.clear();
+    this.loadedSynthDefs.clear();
     console.log("[SuperSonic] Destroyed");
   }
+  /**
+   * Wait until NTP timing has been established.
+   * Note: NTP calculation is now done internally in C++ process_audio().
+   * Returns 0 for backward compatibility.
+   */
+  async waitForTimeSync() {
+    if (!this.bufferConstants) {
+      if (this._timeOffsetPromise) {
+        await this._timeOffsetPromise;
+      }
+    }
+    const ntpStartView = new Float64Array(this.sharedBuffer, this.ringBufferBase + this.bufferConstants.NTP_START_TIME_START, 1);
+    return ntpStartView[0];
+  }
   /**
    * Load a sample into a buffer and wait for confirmation
    * @param {number} bufnum - Buffer number
@@ -2324,10 +2465,23 @@ var SuperSonic = class {
    * @returns {Promise} Resolves when buffer is ready
    */
   async loadSample(bufnum, path, startFrame = 0, numFrames = 0) {
-    if (!this.initialized) {
-      throw new Error("SuperSonic not initialized. Call init() first.");
-    }
-    await this._allocReadBuffer(bufnum, path, startFrame, numFrames);
+    this.#ensureInitialized("load samples");
+    const bufferInfo = await this.#requireBufferManager().prepareFromFile({
+      bufnum,
+      path,
+      startFrame,
+      numFrames
+    });
+    await this.send(
+      "/b_allocPtr",
+      bufnum,
+      bufferInfo.ptr,
+      bufferInfo.numFrames,
+      bufferInfo.numChannels,
+      bufferInfo.sampleRate,
+      bufferInfo.uuid
+    );
+    return bufferInfo.allocationComplete;
   }
   /**
    * Load a binary synthdef file and send it to scsynth
@@ -2347,7 +2501,11 @@ var SuperSonic = class {
       }
       const arrayBuffer = await response.arrayBuffer();
       const synthdefData = new Uint8Array(arrayBuffer);
-      this.send("/d_recv", synthdefData);
+      await this.send("/d_recv", synthdefData);
+      const synthName = this.#extractSynthDefName(path);
+      if (synthName) {
+        this.loadedSynthDefs.add(synthName);
+      }
       console.log(`[SuperSonic] Loaded synthdef from ${path} (${synthdefData.length} bytes)`);
     } catch (error) {
       console.error("[SuperSonic] Failed to load synthdef:", error);
@@ -2446,6 +2604,368 @@ var SuperSonic = class {
     }
     return this.bufferPool.stats();
   }
+  getDiagnostics() {
+    this.#ensureInitialized("get diagnostics");
+    const poolStats = this.bufferPool?.stats ? this.bufferPool.stats() : null;
+    let bytesActive = 0;
+    let pendingCount = 0;
+    for (const entry of this.allocatedBuffers.values()) {
+      if (!entry) continue;
+      bytesActive += entry.size || 0;
+      if (entry.pendingToken) {
+        pendingCount++;
+      }
+    }
+    return {
+      buffers: {
+        active: this.allocatedBuffers.size,
+        pending: pendingCount,
+        bytesActive,
+        pool: poolStats ? {
+          total: poolStats.total || 0,
+          available: poolStats.available || 0,
+          freeBytes: poolStats.free?.size || 0,
+          freeBlocks: poolStats.free?.count || 0,
+          usedBytes: poolStats.used?.size || 0,
+          usedBlocks: poolStats.used?.count || 0
+        } : null
+      },
+      synthdefs: {
+        count: this.loadedSynthDefs.size
+      }
+    };
+  }
+  /**
+   * Initialize NTP timing (write-once)
+   * Sets the NTP start time when AudioContext started
+   * @private
+   */
+  initializeNTPTiming() {
+    if (!this.bufferConstants || !this.audioContext) {
+      return;
+    }
+    const perfTimeMs = performance.timeOrigin + performance.now();
+    const currentNTP = perfTimeMs / 1e3 + NTP_EPOCH_OFFSET;
+    const currentAudioCtx = this.audioContext.currentTime;
+    const ntpStartTime = currentNTP - currentAudioCtx;
+    const ntpStartView = new Float64Array(
+      this.sharedBuffer,
+      this.ringBufferBase + this.bufferConstants.NTP_START_TIME_START,
+      1
+    );
+    ntpStartView[0] = ntpStartTime;
+    this._initialNTPStartTime = ntpStartTime;
+    console.log(`[SuperSonic] NTP timing initialized: start=${ntpStartTime.toFixed(6)}s (current NTP=${currentNTP.toFixed(3)}, AudioCtx=${currentAudioCtx.toFixed(3)}), ringBufferBase=${this.ringBufferBase}`);
+  }
+  /**
+   * Update drift offset (AudioContext → NTP drift correction)
+   * CRITICAL: This REPLACES the drift value, does not accumulate
+   * @private
+   */
+  updateDriftOffset() {
+    if (!this.bufferConstants || !this.audioContext || this._initialNTPStartTime === void 0) {
+      return;
+    }
+    const perfTimeMs = performance.timeOrigin + performance.now();
+    const currentNTP = perfTimeMs / 1e3 + NTP_EPOCH_OFFSET;
+    const currentAudioCtx = this.audioContext.currentTime;
+    const currentNTPStartTime = currentNTP - currentAudioCtx;
+    const driftSeconds = currentNTPStartTime - this._initialNTPStartTime;
+    const driftMs = Math.round(driftSeconds * 1e3);
+    const driftView = new Int32Array(
+      this.sharedBuffer,
+      this.ringBufferBase + this.bufferConstants.DRIFT_OFFSET_START,
+      1
+    );
+    Atomics.store(driftView, 0, driftMs);
+    console.log(`[SuperSonic] Drift offset updated: ${driftMs}ms (current NTP start=${currentNTPStartTime.toFixed(6)}, initial=${this._initialNTPStartTime.toFixed(6)})`);
+  }
+  /**
+   * Get current drift offset in milliseconds
+   * @returns {number} Current drift in milliseconds
+   */
+  getDriftOffset() {
+    if (!this.bufferConstants) {
+      return 0;
+    }
+    const driftView = new Int32Array(
+      this.sharedBuffer,
+      this.ringBufferBase + this.bufferConstants.DRIFT_OFFSET_START,
+      1
+    );
+    return Atomics.load(driftView, 0);
+  }
+  /**
+   * Start periodic drift offset updates
+   * @private
+   */
+  #startDriftOffsetTimer() {
+    this.#stopDriftOffsetTimer();
+    this._driftOffsetTimer = setInterval(() => {
+      this.updateDriftOffset();
+    }, DRIFT_UPDATE_INTERVAL_MS);
+    console.log(`[SuperSonic] Started drift offset correction (every ${DRIFT_UPDATE_INTERVAL_MS}ms)`);
+  }
+  /**
+   * Stop periodic drift offset updates
+   * @private
+   */
+  #stopDriftOffsetTimer() {
+    if (this._driftOffsetTimer) {
+      clearInterval(this._driftOffsetTimer);
+      this._driftOffsetTimer = null;
+    }
+  }
+  #extractSynthDefName(path) {
+    if (!path || typeof path !== "string") {
+      return null;
+    }
+    const lastSegment = path.split("/").filter(Boolean).pop() || path;
+    return lastSegment.replace(/\.scsyndef$/i, "");
+  }
+  #toUint8Array(data) {
+    if (data instanceof Uint8Array) {
+      return data;
+    }
+    if (data instanceof ArrayBuffer) {
+      return new Uint8Array(data);
+    }
+    throw new Error("oscData must be ArrayBuffer or Uint8Array");
+  }
+  async #prepareOutboundPacket(uint8Data) {
+    const decodeOptions = { metadata: true, unpackSingleArgs: false };
+    try {
+      const decodedPacket = _SuperSonic.osc.decode(uint8Data, decodeOptions);
+      const { packet, changed } = await this.#rewritePacket(decodedPacket);
+      if (!changed) {
+        return uint8Data;
+      }
+      return _SuperSonic.osc.encode(packet);
+    } catch (error) {
+      console.error("[SuperSonic] Failed to prepare OSC packet:", error);
+      throw error;
+    }
+  }
+  async #rewritePacket(packet) {
+    if (packet && packet.address) {
+      const { message, changed } = await this.#rewriteMessage(packet);
+      return { packet: message, changed };
+    }
+    if (this.#isBundle(packet)) {
+      const subResults = await Promise.all(
+        packet.packets.map((subPacket) => this.#rewritePacket(subPacket))
+      );
+      const changed = subResults.some((result) => result.changed);
+      if (!changed) {
+        return { packet, changed: false };
+      }
+      const rewrittenPackets = subResults.map((result) => result.packet);
+      return {
+        packet: {
+          timeTag: packet.timeTag,
+          packets: rewrittenPackets
+        },
+        changed: true
+      };
+    }
+    return { packet, changed: false };
+  }
+  async #rewriteMessage(message) {
+    switch (message.address) {
+      case "/b_alloc":
+        return {
+          message: await this.#rewriteAlloc(message),
+          changed: true
+        };
+      case "/b_allocRead":
+        return {
+          message: await this.#rewriteAllocRead(message),
+          changed: true
+        };
+      case "/b_allocReadChannel":
+        return {
+          message: await this.#rewriteAllocReadChannel(message),
+          changed: true
+        };
+      default:
+        return { message, changed: false };
+    }
+  }
+  async #rewriteAllocRead(message) {
+    const bufferManager = this.#requireBufferManager();
+    const bufnum = this.#requireIntArg(message.args, 0, "/b_allocRead requires a buffer number");
+    const path = this.#requireStringArg(message.args, 1, "/b_allocRead requires a file path");
+    const startFrame = this.#optionalIntArg(message.args, 2, 0);
+    const numFrames = this.#optionalIntArg(message.args, 3, 0);
+    const bufferInfo = await bufferManager.prepareFromFile({
+      bufnum,
+      path,
+      startFrame,
+      numFrames
+    });
+    this.#detachAllocationPromise(bufferInfo.allocationComplete, `/b_allocRead ${bufnum}`);
+    return this.#buildAllocPtrMessage(bufnum, bufferInfo);
+  }
+  async #rewriteAllocReadChannel(message) {
+    const bufferManager = this.#requireBufferManager();
+    const bufnum = this.#requireIntArg(message.args, 0, "/b_allocReadChannel requires a buffer number");
+    const path = this.#requireStringArg(message.args, 1, "/b_allocReadChannel requires a file path");
+    const startFrame = this.#optionalIntArg(message.args, 2, 0);
+    const numFrames = this.#optionalIntArg(message.args, 3, 0);
+    const channels = [];
+    for (let i = 4; i < (message.args?.length || 0); i++) {
+      if (!this.#isNumericArg(message.args[i])) {
+        break;
+      }
+      channels.push(Math.floor(this.#getArgValue(message.args[i])));
+    }
+    const bufferInfo = await bufferManager.prepareFromFile({
+      bufnum,
+      path,
+      startFrame,
+      numFrames,
+      channels: channels.length > 0 ? channels : null
+    });
+    this.#detachAllocationPromise(bufferInfo.allocationComplete, `/b_allocReadChannel ${bufnum}`);
+    return this.#buildAllocPtrMessage(bufnum, bufferInfo);
+  }
+  async #rewriteAlloc(message) {
+    const bufferManager = this.#requireBufferManager();
+    const bufnum = this.#requireIntArg(message.args, 0, "/b_alloc requires a buffer number");
+    const numFrames = this.#requireIntArg(message.args, 1, "/b_alloc requires a frame count");
+    let argIndex = 2;
+    let numChannels = 1;
+    let sampleRate = this.audioContext?.sampleRate || 44100;
+    if (this.#isNumericArg(this.#argAt(message.args, argIndex))) {
+      numChannels = Math.max(1, this.#optionalIntArg(message.args, argIndex, 1));
+      argIndex++;
+    }
+    if (this.#argAt(message.args, argIndex)?.type === "b") {
+      argIndex++;
+    }
+    if (this.#isNumericArg(this.#argAt(message.args, argIndex))) {
+      sampleRate = this.#getArgValue(this.#argAt(message.args, argIndex));
+    }
+    const bufferInfo = await bufferManager.prepareEmpty({
+      bufnum,
+      numFrames,
+      numChannels,
+      sampleRate
+    });
+    this.#detachAllocationPromise(bufferInfo.allocationComplete, `/b_alloc ${bufnum}`);
+    return this.#buildAllocPtrMessage(bufnum, bufferInfo);
+  }
+  #buildAllocPtrMessage(bufnum, bufferInfo) {
+    return {
+      address: "/b_allocPtr",
+      args: [
+        this.#intArg(bufnum),
+        this.#intArg(bufferInfo.ptr),
+        this.#intArg(bufferInfo.numFrames),
+        this.#intArg(bufferInfo.numChannels),
+        this.#floatArg(bufferInfo.sampleRate),
+        this.#stringArg(bufferInfo.uuid)
+      ]
+    };
+  }
+  #intArg(value) {
+    return { type: "i", value: Math.floor(value) };
+  }
+  #floatArg(value) {
+    return { type: "f", value };
+  }
+  #stringArg(value) {
+    return { type: "s", value: String(value) };
+  }
+  #argAt(args, index) {
+    if (!Array.isArray(args)) {
+      return void 0;
+    }
+    return args[index];
+  }
+  #getArgValue(arg) {
+    if (arg === void 0 || arg === null) {
+      return void 0;
+    }
+    return typeof arg === "object" && Object.prototype.hasOwnProperty.call(arg, "value") ? arg.value : arg;
+  }
+  #requireIntArg(args, index, errorMessage) {
+    const value = this.#getArgValue(this.#argAt(args, index));
+    if (!Number.isFinite(value)) {
+      throw new Error(errorMessage);
+    }
+    return Math.floor(value);
+  }
+  #optionalIntArg(args, index, defaultValue = 0) {
+    const value = this.#getArgValue(this.#argAt(args, index));
+    if (!Number.isFinite(value)) {
+      return defaultValue;
+    }
+    return Math.floor(value);
+  }
+  #requireStringArg(args, index, errorMessage) {
+    const value = this.#getArgValue(this.#argAt(args, index));
+    if (typeof value !== "string") {
+      throw new Error(errorMessage);
+    }
+    return value;
+  }
+  #isNumericArg(arg) {
+    if (!arg) {
+      return false;
+    }
+    const value = this.#getArgValue(arg);
+    return Number.isFinite(value);
+  }
+  #detachAllocationPromise(promise, context) {
+    if (!promise || typeof promise.catch !== "function") {
+      return;
+    }
+    promise.catch((error) => {
+      console.error(`[SuperSonic] ${context} allocation failed:`, error);
+    });
+  }
+  #requireBufferManager() {
+    if (!this.bufferManager) {
+      throw new Error("Buffer manager not ready. Call init() before issuing buffer commands.");
+    }
+    return this.bufferManager;
+  }
+  #isBundle(packet) {
+    return packet && packet.timeTag !== void 0 && Array.isArray(packet.packets);
+  }
+  #calculateBundleWait(uint8Data) {
+    if (uint8Data.length < 16) {
+      return null;
+    }
+    const header = String.fromCharCode.apply(null, uint8Data.slice(0, 8));
+    if (header !== "#bundle\0") {
+      return null;
+    }
+    const ntpStartView = new Float64Array(this.sharedBuffer, this.ringBufferBase + this.bufferConstants.NTP_START_TIME_START, 1);
+    const ntpStartTime = ntpStartView[0];
+    if (ntpStartTime === 0) {
+      console.warn("[SuperSonic] NTP start time not yet initialized");
+      return null;
+    }
+    const driftView = new Int32Array(this.sharedBuffer, this.ringBufferBase + this.bufferConstants.DRIFT_OFFSET_START, 1);
+    const driftMs = Atomics.load(driftView, 0);
+    const driftSeconds = driftMs / 1e3;
+    const globalView = new Int32Array(this.sharedBuffer, this.ringBufferBase + this.bufferConstants.GLOBAL_OFFSET_START, 1);
+    const globalMs = Atomics.load(globalView, 0);
+    const globalSeconds = globalMs / 1e3;
+    const totalOffset = ntpStartTime + driftSeconds + globalSeconds;
+    const view = new DataView(uint8Data.buffer, uint8Data.byteOffset);
+    const ntpSeconds = view.getUint32(8, false);
+    const ntpFraction = view.getUint32(12, false);
+    if (ntpSeconds === 0 && (ntpFraction === 0 || ntpFraction === 1)) {
+      return null;
+    }
+    const ntpTimeS = ntpSeconds + ntpFraction / 4294967296;
+    const audioTimeS = ntpTimeS - totalOffset;
+    const currentTimeS = this.audioContext.currentTime;
+    return { audioTimeS, currentTimeS };
+  }
 };
 export {
   SuperSonic