supersonic-scsynth 0.4.0 → 0.6.0

package/dist/supersonic.js

@@ -993,44 +993,6 @@ var ScsynthOSC = class {
       type: "clear"
     });
   }
-  /**
-   * Get statistics from all workers
-   */
-  async getStats() {
-    if (!this.initialized) {
-      return null;
-    }
-    const statsPromises = [
-      this.getWorkerStats(this.workers.oscOut, "oscOut"),
-      this.getWorkerStats(this.workers.oscIn, "oscIn"),
-      this.getWorkerStats(this.workers.debug, "debug")
-    ];
-    const results = await Promise.all(statsPromises);
-    return {
-      oscOut: results[0],
-      oscIn: results[1],
-      debug: results[2]
-    };
-  }
-  /**
-   * Get stats from a single worker
-   */
-  getWorkerStats(worker, name) {
-    return new Promise((resolve) => {
-      const timeout = setTimeout(() => {
-        resolve({ error: "Timeout getting stats" });
-      }, 1e3);
-      const handler = (event) => {
-        if (event.data.type === "stats") {
-          clearTimeout(timeout);
-          worker.removeEventListener("message", handler);
-          resolve(event.data.stats);
-        }
-      };
-      worker.addEventListener("message", handler);
-      worker.postMessage({ type: "getStats" });
-    });
-  }
   /**
    * Set callback for raw binary OSC messages received from scsynth
    */
@@ -1601,37 +1563,145 @@ 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
+// js/lib/buffer_manager.js
+var BUFFER_POOL_ALIGNMENT = 8;
 var BufferManager = class {
+  // Private configuration
+  #sampleBaseURL;
+  #audioPathMap;
+  // Private implementation
+  #audioContext;
+  #sharedBuffer;
+  #bufferPool;
+  #allocatedBuffers;
+  #pendingBufferOps;
+  #bufferLocks;
   constructor(options) {
     const {
       audioContext,
       sharedBuffer,
-      bufferPool,
-      allocatedBuffers,
-      resolveAudioPath,
-      registerPendingOp
+      bufferPoolConfig,
+      sampleBaseURL,
+      audioPathMap = {},
+      maxBuffers = 1024
     } = options;
-    this.audioContext = audioContext;
-    this.sharedBuffer = sharedBuffer;
-    this.bufferPool = bufferPool;
-    this.allocatedBuffers = allocatedBuffers;
-    this.resolveAudioPath = resolveAudioPath;
-    this.registerPendingOp = registerPendingOp;
-    this.bufferLocks = /* @__PURE__ */ new Map();
+    if (!audioContext) {
+      throw new Error("BufferManager requires audioContext");
+    }
+    if (!sharedBuffer || !(sharedBuffer instanceof SharedArrayBuffer)) {
+      throw new Error("BufferManager requires sharedBuffer (SharedArrayBuffer)");
+    }
+    if (!bufferPoolConfig || typeof bufferPoolConfig !== "object") {
+      throw new Error("BufferManager requires bufferPoolConfig (object with start, size, align)");
+    }
+    if (!Number.isFinite(bufferPoolConfig.start) || bufferPoolConfig.start < 0) {
+      throw new Error("bufferPoolConfig.start must be a non-negative number");
+    }
+    if (!Number.isFinite(bufferPoolConfig.size) || bufferPoolConfig.size <= 0) {
+      throw new Error("bufferPoolConfig.size must be a positive number");
+    }
+    if (audioPathMap && typeof audioPathMap !== "object") {
+      throw new Error("audioPathMap must be an object");
+    }
+    if (!Number.isInteger(maxBuffers) || maxBuffers <= 0) {
+      throw new Error("maxBuffers must be a positive integer");
+    }
+    this.#audioContext = audioContext;
+    this.#sharedBuffer = sharedBuffer;
+    this.#sampleBaseURL = sampleBaseURL;
+    this.#audioPathMap = audioPathMap;
+    this.#bufferPool = new MemPool({
+      buf: sharedBuffer,
+      start: bufferPoolConfig.start,
+      size: bufferPoolConfig.size,
+      align: BUFFER_POOL_ALIGNMENT
+    });
+    this.#allocatedBuffers = /* @__PURE__ */ new Map();
+    this.#pendingBufferOps = /* @__PURE__ */ new Map();
+    this.#bufferLocks = /* @__PURE__ */ new Map();
     this.GUARD_BEFORE = 3;
     this.GUARD_AFTER = 1;
-    this.MAX_BUFFERS = 1024;
+    this.MAX_BUFFERS = maxBuffers;
+    const poolSizeMB = (bufferPoolConfig.size / (1024 * 1024)).toFixed(0);
+    const poolOffsetMB = (bufferPoolConfig.start / (1024 * 1024)).toFixed(0);
+    console.log(`[BufferManager] Initialized: ${poolSizeMB}MB pool at offset ${poolOffsetMB}MB`);
+  }
+  #resolveAudioPath(scPath) {
+    if (typeof scPath !== "string" || scPath.length === 0) {
+      throw new Error(`Invalid audio path: must be a non-empty string`);
+    }
+    if (scPath.includes("..")) {
+      throw new Error(`Invalid audio path: path cannot contain '..' (got: ${scPath})`);
+    }
+    if (scPath.startsWith("/") || /^[a-zA-Z]:/.test(scPath)) {
+      throw new Error(`Invalid audio path: path must be relative (got: ${scPath})`);
+    }
+    if (scPath.includes("%2e") || scPath.includes("%2E")) {
+      throw new Error(`Invalid audio path: path cannot contain URL-encoded characters (got: ${scPath})`);
+    }
+    if (scPath.includes("\\")) {
+      throw new Error(`Invalid audio path: use forward slashes only (got: ${scPath})`);
+    }
+    if (this.#audioPathMap[scPath]) {
+      return this.#audioPathMap[scPath];
+    }
+    if (!this.#sampleBaseURL) {
+      throw new Error(
+        '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;
   }
   #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})`);
     }
   }
+  /**
+   * Execute a buffer operation with proper locking, registration, and cleanup
+   * @private
+   * @param {number} bufnum - Buffer number
+   * @param {number} timeoutMs - Operation timeout
+   * @param {Function} operation - Async function that performs the actual buffer work
+   *                                Should return {ptr, sizeBytes, ...extraProps}
+   * @returns {Promise<Object>} Result object with ptr, uuid, allocationComplete, and extra props
+   */
+  async #executeBufferOperation(bufnum, timeoutMs, operation) {
+    let allocatedPtr = null;
+    let pendingToken = null;
+    let allocationRegistered = false;
+    const releaseLock = await this.#acquireBufferLock(bufnum);
+    let lockReleased = false;
+    try {
+      await this.#awaitPendingReplacement(bufnum);
+      const { ptr, sizeBytes, ...extraProps } = await operation();
+      allocatedPtr = ptr;
+      const { uuid, allocationComplete } = this.#registerPending(bufnum, timeoutMs);
+      pendingToken = uuid;
+      this.#recordAllocation(bufnum, allocatedPtr, sizeBytes, uuid, allocationComplete);
+      allocationRegistered = true;
+      const managedCompletion = this.#attachFinalizer(bufnum, uuid, allocationComplete);
+      releaseLock();
+      lockReleased = true;
+      return {
+        ptr: allocatedPtr,
+        uuid,
+        allocationComplete: managedCompletion,
+        ...extraProps
+      };
+    } catch (error) {
+      if (allocationRegistered && pendingToken) {
+        this.#finalizeReplacement(bufnum, pendingToken, false);
+      } else if (allocatedPtr) {
+        this.#bufferPool.free(allocatedPtr);
+      }
+      throw error;
+    } finally {
+      if (!lockReleased) {
+        releaseLock();
+      }
+    }
+  }
   async prepareFromFile(params) {
     const {
       bufnum,
@@ -1641,20 +1711,14 @@ var BufferManager = class {
       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);
+    return this.#executeBufferOperation(bufnum, 6e4, async () => {
+      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 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;
@@ -1664,7 +1728,7 @@ var BufferManager = class {
       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 ptr = this.#malloc(totalSamples);
       const interleaved = new Float32Array(totalSamples);
       const dataOffset = this.GUARD_BEFORE * numChannels;
       for (let frame = 0; frame < framesRequested; frame++) {
@@ -1674,35 +1738,16 @@ var BufferManager = class {
           interleaved[dataOffset + frame * numChannels + ch] = channelData[start + frame];
         }
       }
-      this.#writeToSharedBuffer(allocatedPtr, interleaved);
+      this.#writeToSharedBuffer(ptr, 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,
+        ptr,
+        sizeBytes,
         numFrames: framesRequested,
         numChannels,
-        sampleRate: audioBuffer.sampleRate,
-        uuid,
-        allocationComplete: managedCompletion
+        sampleRate: audioBuffer.sampleRate
       };
-    } 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 {
@@ -1712,9 +1757,6 @@ var BufferManager = class {
       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})`);
     }
@@ -1723,42 +1765,20 @@ var BufferManager = class {
     }
     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);
+    return this.#executeBufferOperation(bufnum, 5e3, async () => {
+      const totalSamples = roundedFrames * roundedChannels + (this.GUARD_BEFORE + this.GUARD_AFTER) * roundedChannels;
+      const ptr = this.#malloc(totalSamples);
       const interleaved = new Float32Array(totalSamples);
-      this.#writeToSharedBuffer(allocatedPtr, interleaved);
+      this.#writeToSharedBuffer(ptr, 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,
+        ptr,
+        sizeBytes,
         numFrames: roundedFrames,
         numChannels: roundedChannels,
-        sampleRate: sampleRate || this.audioContext.sampleRate,
-        uuid,
-        allocationComplete: managedCompletion
+        sampleRate: sampleRate || this.#audioContext.sampleRate
       };
-    } 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) {
@@ -1773,9 +1793,9 @@ var BufferManager = class {
   }
   #malloc(totalSamples) {
     const bytesNeeded = totalSamples * 4;
-    const ptr = this.bufferPool.malloc(bytesNeeded);
+    const ptr = this.#bufferPool.malloc(bytesNeeded);
     if (ptr === 0) {
-      const stats = this.bufferPool.stats();
+      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);
@@ -1786,40 +1806,43 @@ var BufferManager = class {
     return ptr;
   }
   #writeToSharedBuffer(ptr, data) {
-    const heap = new Float32Array(this.sharedBuffer, ptr, data.length);
+    const heap = new Float32Array(this.#sharedBuffer, ptr, data.length);
     heap.set(data);
   }
-  #registerPending(bufnum) {
-    if (!this.registerPendingOp) {
-      return {
-        uuid: crypto.randomUUID(),
-        allocationComplete: Promise.resolve()
-      };
-    }
+  #createPendingOperation(uuid, bufnum, timeoutMs) {
+    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 });
+    });
+  }
+  #registerPending(bufnum, timeoutMs) {
     const uuid = crypto.randomUUID();
-    const allocationComplete = this.registerPendingOp(uuid, bufnum);
+    const allocationComplete = this.#createPendingOperation(uuid, bufnum, timeoutMs);
     return { uuid, allocationComplete };
   }
   async #acquireBufferLock(bufnum) {
-    const prev = this.bufferLocks.get(bufnum) || Promise.resolve();
+    const prev = this.#bufferLocks.get(bufnum) || Promise.resolve();
     let releaseLock;
     const current = new Promise((resolve) => {
       releaseLock = resolve;
     });
-    this.bufferLocks.set(bufnum, prev.then(() => current));
+    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);
+      if (this.#bufferLocks.get(bufnum) === current) {
+        this.#bufferLocks.delete(bufnum);
       }
     };
   }
   #recordAllocation(bufnum, ptr, sizeBytes, pendingToken, pendingPromise) {
-    const previousEntry = this.allocatedBuffers.get(bufnum);
+    const previousEntry = this.#allocatedBuffers.get(bufnum);
     const entry = {
       ptr,
       size: sizeBytes,
@@ -1827,11 +1850,11 @@ var BufferManager = class {
       pendingPromise,
       previousAllocation: previousEntry ? { ptr: previousEntry.ptr, size: previousEntry.size } : null
     };
-    this.allocatedBuffers.set(bufnum, entry);
+    this.#allocatedBuffers.set(bufnum, entry);
     return entry;
   }
   async #awaitPendingReplacement(bufnum) {
-    const existing = this.allocatedBuffers.get(bufnum);
+    const existing = this.#allocatedBuffers.get(bufnum);
     if (existing && existing.pendingToken && existing.pendingPromise) {
       try {
         await existing.pendingPromise;
@@ -1853,7 +1876,7 @@ var BufferManager = class {
     });
   }
   #finalizeReplacement(bufnum, pendingToken, success) {
-    const entry = this.allocatedBuffers.get(bufnum);
+    const entry = this.#allocatedBuffers.get(bufnum);
     if (!entry || entry.pendingToken !== pendingToken) {
       return;
     }
@@ -1863,57 +1886,382 @@ var BufferManager = class {
       entry.pendingPromise = null;
       entry.previousAllocation = null;
       if (previous?.ptr) {
-        this.bufferPool.free(previous.ptr);
+        this.#bufferPool.free(previous.ptr);
       }
       return;
     }
     if (entry.ptr) {
-      this.bufferPool.free(entry.ptr);
+      this.#bufferPool.free(entry.ptr);
     }
     entry.pendingPromise = null;
     if (previous?.ptr) {
-      this.allocatedBuffers.set(bufnum, {
+      this.#allocatedBuffers.set(bufnum, {
         ptr: previous.ptr,
         size: previous.size,
         pendingToken: null,
         previousAllocation: null
       });
     } else {
-      this.allocatedBuffers.delete(bufnum);
+      this.#allocatedBuffers.delete(bufnum);
+    }
+  }
+  /**
+   * Handle /buffer/freed notification from scsynth
+   * Called by SuperSonic when /buffer/freed OSC message is received
+   * @param {Array} args - [bufnum, freedPtr]
+   */
+  handleBufferFreed(args) {
+    const bufnum = args[0];
+    const freedPtr = args[1];
+    const bufferInfo = this.#allocatedBuffers.get(bufnum);
+    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 notification from scsynth
+   * Called by SuperSonic when /buffer/allocated OSC message is received
+   * @param {Array} args - [uuid, bufnum]
+   */
+  handleBufferAllocated(args) {
+    const uuid = args[0];
+    const bufnum = args[1];
+    const pending = this.#pendingBufferOps.get(uuid);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      pending.resolve({ bufnum });
+      this.#pendingBufferOps.delete(uuid);
+    }
+  }
+  /**
+   * Allocate raw buffer memory
+   * @param {number} numSamples - Number of Float32 samples
+   * @returns {number} Byte offset, or 0 if failed
+   */
+  allocate(numSamples) {
+    const sizeBytes = numSamples * 4;
+    const addr = this.#bufferPool.malloc(sizeBytes);
+    if (addr === 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 = (sizeBytes / (1024 * 1024)).toFixed(2);
+      console.error(
+        `[BufferManager] Allocation failed: requested ${requestedMB}MB, available ${availableMB}MB of ${totalMB}MB total`
+      );
     }
+    return addr;
+  }
+  /**
+   * Free previously allocated buffer
+   * @param {number} addr - Buffer address
+   * @returns {boolean} true if freed successfully
+   */
+  free(addr) {
+    return this.#bufferPool.free(addr);
+  }
+  /**
+   * Get Float32Array view of buffer
+   * @param {number} addr - Buffer address
+   * @param {number} numSamples - Number of samples
+   * @returns {Float32Array} Typed array view
+   */
+  getView(addr, numSamples) {
+    return new Float32Array(this.#sharedBuffer, addr, numSamples);
+  }
+  /**
+   * Get buffer pool statistics
+   * @returns {Object} Stats including total, available, used
+   */
+  getStats() {
+    return this.#bufferPool.stats();
+  }
+  /**
+   * Get buffer diagnostics
+   * @returns {Object} Buffer state and pool statistics
+   */
+  getDiagnostics() {
+    const poolStats = this.#bufferPool.stats();
+    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 {
+      active: this.#allocatedBuffers.size,
+      pending: pendingCount,
+      bytesActive,
+      pool: {
+        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
+      }
+    };
+  }
+  /**
+   * Clean up resources
+   */
+  destroy() {
+    for (const [uuid, pending] of this.#pendingBufferOps.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error("BufferManager destroyed"));
+    }
+    this.#pendingBufferOps.clear();
+    for (const [bufnum, entry] of this.#allocatedBuffers.entries()) {
+      if (entry.ptr) {
+        this.#bufferPool.free(entry.ptr);
+      }
+    }
+    this.#allocatedBuffers.clear();
+    this.#bufferLocks.clear();
+    console.log("[BufferManager] Destroyed");
   }
 };
+
+// js/timing_constants.js
+var NTP_EPOCH_OFFSET = 2208988800;
+var DRIFT_UPDATE_INTERVAL_MS = 15e3;
+
+// js/memory_layout.js
+var MemoryLayout = {
+  /**
+   * Total WebAssembly memory in pages (1 page = 64KB)
+   * Current: 1280 pages = 80MB
+   *
+   * This value is used by build.sh to set -sINITIAL_MEMORY
+   * Must match: totalPages * 65536 = bufferPoolOffset + bufferPoolSize
+   */
+  totalPages: 1280,
+  /**
+   * WASM heap size (implicit, first section of memory)
+   * Not directly configurable here - defined by bufferPoolOffset - ringBufferReserved
+   * Current: 0-16MB (16 * 1024 * 1024 = 16777216 bytes)
+   */
+  // wasmHeapSize is implicitly: bufferPoolOffset - ringBufferReserved
+  /**
+   * Ring buffer reserved space (between WASM heap and buffer pool)
+   * Actual ring buffer usage: IN: 768KB, OUT: 128KB, DEBUG: 64KB = 960KB
+   * Plus control structures: CONTROL_SIZE (40B) + METRICS_SIZE (48B) + NTP_START_TIME_SIZE (8B) ≈ 96B
+   * Total actual usage: ~960KB
+   * Reserved: 1MB (provides ~64KB headroom for alignment and future expansion)
+   * Current: 1MB reserved (starts where WASM heap ends at 16MB)
+   */
+  ringBufferReserved: 1 * 1024 * 1024,
+  // 1MB reserved
+  /**
+   * Buffer pool byte offset from start of SharedArrayBuffer
+   * Audio samples are allocated from this pool using @thi.ng/malloc
+   * Must be after WASM heap + ring buffer area
+   * Current: 17MB offset = after 16MB heap + 1MB ring buffers
+   */
+  bufferPoolOffset: 17 * 1024 * 1024,
+  // 17825792 bytes
+  /**
+   * Buffer pool size in bytes
+   * Used for audio sample storage (loaded files + allocated buffers)
+   * Current: 63MB (enough for ~3.5 minutes of stereo at 48kHz uncompressed)
+   */
+  bufferPoolSize: 63 * 1024 * 1024,
+  // 66060288 bytes
+  /**
+   * Total memory calculation (should equal totalPages * 65536)
+   * wasmHeap (16MB) + ringReserve (1MB) + bufferPool (63MB) = 80MB
+   */
+  get totalMemory() {
+    return this.bufferPoolOffset + this.bufferPoolSize;
+  },
+  /**
+   * Effective WASM heap size (derived)
+   * This is the space available for scsynth C++ allocations
+   */
+  get wasmHeapSize() {
+    return this.bufferPoolOffset - this.ringBufferReserved;
+  }
+};
+
+// js/scsynth_options.js
+var defaultWorldOptions = {
+  /**
+   * Maximum number of audio buffers (SndBuf slots)
+   * Each buffer slot: 104 bytes overhead (2x SndBuf + SndBufUpdates structs)
+   * Actual audio data is stored in buffer pool (separate from heap)
+   * Default: 1024 (matching SuperCollider default)
+   * Range: 1-65535 (limited by practical memory constraints)
+   */
+  numBuffers: 1024,
+  /**
+   * Maximum number of synthesis nodes (synths + groups)
+   * Each node: ~200-500 bytes depending on synth complexity
+   * Default: 1024 (matching SuperCollider default)
+   */
+  maxNodes: 1024,
+  /**
+   * Maximum number of synth definitions (SynthDef count)
+   * Each definition: variable size (typically 1-10KB)
+   * Default: 1024 (matching SuperCollider default)
+   */
+  maxGraphDefs: 1024,
+  /**
+   * Maximum wire buffers for internal audio routing
+   * Wire buffers: temporary buffers for UGen connections
+   * Each: bufLength * 8 bytes (128 samples * 8 = 1024 bytes)
+   * Default: 64 (matching SuperCollider default)
+   */
+  maxWireBufs: 64,
+  /**
+   * Number of audio bus channels
+   * Audio buses: real-time audio routing between synths
+   * Memory: bufLength * numChannels * 4 bytes (128 * 128 * 4 = 64KB)
+   * Default: 128 (SuperSonic default, SC uses 1024)
+   */
+  numAudioBusChannels: 128,
+  /**
+   * Number of input bus channels (hardware audio input)
+   * AudioWorklet can support input, but SuperSonic doesn't currently route it
+   * Default: 0 (audio input not implemented)
+   */
+  numInputBusChannels: 0,
+  /**
+   * Number of output bus channels (hardware audio output)
+   * WebAudio/AudioWorklet output
+   * Default: 2 (stereo)
+   */
+  numOutputBusChannels: 2,
+  /**
+   * Number of control bus channels
+   * Control buses: control-rate data sharing between synths
+   * Memory: numChannels * 4 bytes (4096 * 4 = 16KB)
+   * Default: 4096 (SuperSonic default, SC uses 16384)
+   */
+  numControlBusChannels: 4096,
+  /**
+   * Audio buffer length in samples (AudioWorklet quantum)
+   *
+   * FIXED at 128 (WebAudio API spec - cannot be changed)
+   * Unlike SuperCollider (configurable 32/64/128), AudioWorklet has a fixed quantum.
+   * Overriding this value will cause initialization to fail.
+   *
+   * Default: 128
+   */
+  bufLength: 128,
+  /**
+   * Real-time memory pool size in kilobytes
+   * AllocPool for synthesis-time allocations (UGen memory, etc.)
+   * This is the largest single allocation from WASM heap
+   * Memory: realTimeMemorySize * 1024 bytes (8192 * 1024 = 8MB)
+   * Default: 8192 KB (8MB, matching Sonic Pi and SuperCollider defaults)
+   */
+  realTimeMemorySize: 8192,
+  /**
+   * Number of random number generators
+   * Each synth can have its own RNG for reproducible randomness
+   * Default: 64 (matching SuperCollider default)
+   */
+  numRGens: 64,
+  /**
+   * Clock source mode
+   * false = Externally clocked (driven by AudioWorklet process() callback)
+   * true = Internally clocked (not applicable in WebAudio context)
+   * Note: In SC terminology, this is "NRT mode" but we're still doing real-time audio
+   * Default: false (SuperSonic is always externally clocked by AudioWorklet)
+   */
+  realTime: false,
+  /**
+   * Memory locking (mlock)
+   * Not applicable in WebAssembly/browser environment
+   * Default: false
+   */
+  memoryLocking: false,
+  /**
+   * Auto-load SynthDefs from disk
+   * 0 = don't auto-load (synths sent via /d_recv)
+   * 1 = auto-load from plugin path
+   * Default: 0 (SuperSonic loads synthdefs via network)
+   */
+  loadGraphDefs: 0,
+  /**
+   * Preferred sample rate (if not specified, uses AudioContext.sampleRate)
+   * Common values: 44100, 48000, 96000
+   * Default: 0 (use AudioContext default, typically 48000)
+   */
+  preferredSampleRate: 0,
+  /**
+   * Debug verbosity level
+   * 0 = quiet, 1 = errors, 2 = warnings, 3 = info, 4 = debug
+   * Default: 0
+   */
+  verbosity: 0
+};
+
+// js/supersonic.js
 var SuperSonic = class _SuperSonic {
   // Expose OSC utilities as static methods
   static osc = {
     encode: (message) => osc_default.writePacket(message),
     decode: (data, options = { metadata: false }) => osc_default.readPacket(data, options)
   };
+  // Private implementation
+  #audioContext;
+  #workletNode;
+  #osc;
+  #wasmMemory;
+  #sharedBuffer;
+  #ringBufferBase;
+  #bufferConstants;
+  #bufferManager;
+  #driftOffsetTimer;
+  #syncListeners;
+  #initialNTPStartTime;
+  #sampleBaseURL;
+  #synthdefBaseURL;
+  #audioPathMap;
+  #initialized;
+  #initializing;
+  #capabilities;
+  // Runtime metrics (private counters)
+  #metrics_messagesSent = 0;
+  #metrics_messagesReceived = 0;
+  #metrics_errors = 0;
+  #metricsIntervalId = null;
+  #metricsGatherInProgress = false;
   constructor(options = {}) {
-    this.initialized = false;
-    this.initializing = false;
-    this.capabilities = {};
-    this.sharedBuffer = null;
-    this.ringBufferBase = null;
-    this.bufferConstants = null;
-    this.audioContext = null;
-    this.workletNode = null;
-    this.osc = null;
-    this.wasmModule = null;
-    this.wasmInstance = null;
-    this.bufferPool = null;
-    this.bufferManager = null;
+    this.#initialized = false;
+    this.#initializing = false;
+    this.#capabilities = {};
+    this.#sharedBuffer = null;
+    this.#ringBufferBase = null;
+    this.#bufferConstants = null;
+    this.#audioContext = null;
+    this.#workletNode = null;
+    this.#osc = null;
+    this.#bufferManager = null;
     this.loadedSynthDefs = /* @__PURE__ */ new Set();
-    this.pendingBufferOps = /* @__PURE__ */ new Map();
-    this._timeOffsetPromise = null;
-    this._resolveTimeOffset = null;
-    this._localClockOffsetTimer = null;
     this.onOSC = null;
     this.onMessage = null;
     this.onMessageSent = null;
     this.onMetricsUpdate = null;
-    this.onStatusUpdate = null;
-    this.onSendError = null;
     this.onDebugMessage = null;
     this.onInitialized = null;
     this.onError = null;
@@ -1922,38 +2270,58 @@ var SuperSonic = class _SuperSonic {
     }
     const workerBaseURL = options.workerBaseURL;
     const wasmBaseURL = options.wasmBaseURL;
+    const worldOptions = { ...defaultWorldOptions, ...options.scsynthOptions };
     this.config = {
       wasmUrl: options.wasmUrl || wasmBaseURL + "scsynth-nrt.wasm",
+      wasmBaseURL,
       workletUrl: options.workletUrl || workerBaseURL + "scsynth_audio_worklet.js",
       workerBaseURL,
-      // Store for worker creation
       development: false,
       audioContextOptions: {
         latencyHint: "interactive",
+        // hint to push for lowest latency possible
         sampleRate: 48e3
-      }
+        // only requested rate - actual rate is determined by hardware
+      },
+      // Build-time memory layout (constant)
+      memory: MemoryLayout,
+      // Runtime world options (merged defaults + user overrides)
+      worldOptions
     };
-    this.sampleBaseURL = options.sampleBaseURL || null;
-    this.synthdefBaseURL = options.synthdefBaseURL || null;
-    this.audioPathMap = options.audioPathMap || {};
-    this.allocatedBuffers = /* @__PURE__ */ new Map();
-    this.stats = {
+    this.#sampleBaseURL = options.sampleBaseURL || null;
+    this.#synthdefBaseURL = options.synthdefBaseURL || null;
+    this.#audioPathMap = options.audioPathMap || {};
+    this.bootStats = {
       initStartTime: null,
-      initDuration: null,
-      messagesSent: 0,
-      messagesReceived: 0,
-      errors: 0
+      initDuration: null
     };
   }
   /**
-   * Check browser capabilities for required features
+   * Get initialization status (read-only)
+   */
+  get initialized() {
+    return this.#initialized;
+  }
+  /**
+   * Get initialization in-progress status (read-only)
+   */
+  get initializing() {
+    return this.#initializing;
+  }
+  /**
+   * Get browser capabilities (read-only)
    */
-  checkCapabilities() {
-    this.capabilities = {
-      audioWorklet: "AudioWorklet" in window,
+  get capabilities() {
+    return this.#capabilities;
+  }
+  /**
+   * Set and validate browser capabilities for required features
+   */
+  setAndValidateCapabilities() {
+    this.#capabilities = {
+      audioWorklet: typeof AudioWorklet !== "undefined",
       sharedArrayBuffer: typeof SharedArrayBuffer !== "undefined",
       crossOriginIsolated: window.crossOriginIsolated === true,
-      wasmThreads: typeof WebAssembly !== "undefined" && typeof WebAssembly.Memory !== "undefined" && WebAssembly.Memory.prototype.hasOwnProperty("shared"),
       atomics: typeof Atomics !== "undefined",
       webWorker: typeof Worker !== "undefined"
     };
@@ -1964,11 +2332,11 @@ var SuperSonic = class _SuperSonic {
       "atomics",
       "webWorker"
     ];
-    const missing = required.filter((f) => !this.capabilities[f]);
+    const missing = required.filter((f) => !this.#capabilities[f]);
     if (missing.length > 0) {
       const error = new Error(`Missing required features: ${missing.join(", ")}`);
-      if (!this.capabilities.crossOriginIsolated) {
-        if (this.capabilities.sharedArrayBuffer) {
+      if (!this.#capabilities.crossOriginIsolated) {
+        if (this.#capabilities.sharedArrayBuffer) {
           error.message += "\n\nSharedArrayBuffer is available but cross-origin isolation is not enabled. Please ensure COOP and COEP headers are set correctly:\n  Cross-Origin-Opener-Policy: same-origin\n  Cross-Origin-Embedder-Policy: require-corp";
         } else {
           error.message += "\n\nSharedArrayBuffer is not available. This may be due to:\n1. Missing COOP/COEP headers\n2. Browser doesn't support SharedArrayBuffer\n3. Browser security settings";
@@ -1976,78 +2344,54 @@ var SuperSonic = class _SuperSonic {
       }
       throw error;
     }
-    return this.capabilities;
+    return this.#capabilities;
   }
+  /**
+   * Merge user-provided world options with defaults
+   * @private
+   */
   /**
    * Initialize shared WebAssembly memory
    */
   #initializeSharedMemory() {
-    const TOTAL_PAGES = 3072;
-    this.wasmMemory = new WebAssembly.Memory({
-      initial: TOTAL_PAGES,
-      maximum: TOTAL_PAGES,
+    const memConfig = this.config.memory;
+    this.#wasmMemory = new WebAssembly.Memory({
+      initial: memConfig.totalPages,
+      maximum: memConfig.totalPages,
       shared: true
     });
-    this.sharedBuffer = this.wasmMemory.buffer;
-    const BUFFER_POOL_OFFSET = 64 * 1024 * 1024;
-    const BUFFER_POOL_SIZE = 128 * 1024 * 1024;
-    this.bufferPool = new MemPool({
-      buf: this.sharedBuffer,
-      start: BUFFER_POOL_OFFSET,
-      size: BUFFER_POOL_SIZE,
-      align: 8
-      // 8-byte alignment (minimum required by MemPool)
-    });
-    console.log("[SuperSonic] Buffer pool initialized: 128MB at offset 64MB");
+    this.#sharedBuffer = this.#wasmMemory.buffer;
   }
-  /**
-   * Initialize AudioContext and set up time offset calculation
-   */
   #initializeAudioContext() {
-    this.audioContext = new (window.AudioContext || window.webkitAudioContext)(
-      this.config.audioContextOptions
-    );
-    this._timeOffsetPromise = new Promise((resolve) => {
-      this._resolveTimeOffset = resolve;
-    });
-    if (this.audioContext.state === "suspended") {
-      const resumeContext = async () => {
-        if (this.audioContext.state === "suspended") {
-          await this.audioContext.resume();
-        }
-      };
-      document.addEventListener("click", resumeContext, { once: true });
-      document.addEventListener("touchstart", resumeContext, { once: true });
-    }
-    return this.audioContext;
+    this.#audioContext = new AudioContext(this.config.audioContextOptions);
+    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)
+    this.#bufferManager = new BufferManager({
+      audioContext: this.#audioContext,
+      sharedBuffer: this.#sharedBuffer,
+      bufferPoolConfig: {
+        start: this.config.memory.bufferPoolOffset,
+        size: this.config.memory.bufferPoolSize
+      },
+      sampleBaseURL: this.#sampleBaseURL,
+      audioPathMap: this.#audioPathMap,
+      maxBuffers: this.config.worldOptions.numBuffers
     });
   }
-  /**
-   * Load WASM manifest to get the current hashed filename
-   */
   async #loadWasmManifest() {
+    const manifestUrl = this.config.wasmBaseURL + "manifest.json";
     try {
-      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 = wasmBaseURL + wasmFile;
-        console.log(`[SuperSonic] Using WASM build: ${wasmFile}`);
-        console.log(`[SuperSonic] Build: ${manifest.buildId} (git: ${manifest.gitHash})`);
+      if (!response.ok) {
+        console.warn(`[SuperSonic] WASM manifest not found (${response.status}), using default`);
+        return;
       }
+      const manifest = await response.json();
+      this.config.wasmUrl = this.config.wasmBaseURL + manifest.wasmFile;
+      console.log(`[SuperSonic] WASM: ${manifest.wasmFile} (${manifest.buildId}, git: ${manifest.gitHash})`);
     } catch (error) {
-      console.warn("[SuperSonic] WASM manifest not found, using default filename");
+      console.warn("[SuperSonic] Failed to load WASM manifest, using default");
     }
   }
   /**
@@ -2065,21 +2409,24 @@ var SuperSonic = class _SuperSonic {
    * Initialize AudioWorklet with WASM
    */
   async #initializeAudioWorklet(wasmBytes) {
-    await this.audioContext.audioWorklet.addModule(this.config.workletUrl);
-    this.workletNode = new AudioWorkletNode(this.audioContext, "scsynth-processor", {
+    await this.#audioContext.audioWorklet.addModule(this.config.workletUrl);
+    this.#workletNode = new AudioWorkletNode(this.#audioContext, "scsynth-processor", {
       numberOfInputs: 0,
       numberOfOutputs: 1,
       outputChannelCount: [2]
     });
-    this.workletNode.connect(this.audioContext.destination);
-    this.workletNode.port.postMessage({
+    this.#workletNode.connect(this.#audioContext.destination);
+    this.#workletNode.port.postMessage({
       type: "init",
-      sharedBuffer: this.sharedBuffer
+      sharedBuffer: this.#sharedBuffer
     });
-    this.workletNode.port.postMessage({
+    this.#workletNode.port.postMessage({
       type: "loadWasm",
       wasmBytes,
-      wasmMemory: this.wasmMemory
+      wasmMemory: this.#wasmMemory,
+      worldOptions: this.config.worldOptions,
+      sampleRate: this.#audioContext.sampleRate
+      // Pass actual AudioContext sample rate
     });
     await this.#waitForWorkletInit();
   }
@@ -2087,55 +2434,55 @@ var SuperSonic = class _SuperSonic {
    * Initialize OSC communication layer
    */
   async #initializeOSC() {
-    this.osc = new ScsynthOSC(this.config.workerBaseURL);
-    this.osc.onRawOSC((msg) => {
+    this.#osc = new ScsynthOSC(this.config.workerBaseURL);
+    this.#osc.onRawOSC((msg) => {
       if (this.onOSC) {
         this.onOSC(msg);
       }
     });
-    this.osc.onParsedOSC((msg) => {
+    this.#osc.onParsedOSC((msg) => {
       if (msg.address === "/buffer/freed") {
-        this._handleBufferFreed(msg.args);
+        this.#bufferManager?.handleBufferFreed(msg.args);
       } else if (msg.address === "/buffer/allocated") {
-        this._handleBufferAllocated(msg.args);
+        this.#bufferManager?.handleBufferAllocated(msg.args);
       } else if (msg.address === "/synced" && msg.args.length > 0) {
         const syncId = msg.args[0];
-        if (this._syncListeners && this._syncListeners.has(syncId)) {
-          const listener = this._syncListeners.get(syncId);
+        if (this.#syncListeners && this.#syncListeners.has(syncId)) {
+          const listener = this.#syncListeners.get(syncId);
           listener(msg);
         }
       }
       if (this.onMessage) {
-        this.stats.messagesReceived++;
+        this.#metrics_messagesReceived++;
         this.onMessage(msg);
       }
     });
-    this.osc.onDebugMessage((msg) => {
+    this.#osc.onDebugMessage((msg) => {
       if (this.onDebugMessage) {
         this.onDebugMessage(msg);
       }
     });
-    this.osc.onError((error, workerName) => {
+    this.#osc.onError((error, workerName) => {
       console.error(`[SuperSonic] ${workerName} error:`, error);
-      this.stats.errors++;
+      this.#metrics_errors++;
       if (this.onError) {
         this.onError(new Error(`${workerName}: ${error}`));
       }
     });
-    await this.osc.init(this.sharedBuffer, this.ringBufferBase, this.bufferConstants);
+    await this.#osc.init(this.#sharedBuffer, this.#ringBufferBase, this.#bufferConstants);
   }
   /**
    * Complete initialization and trigger callbacks
    */
   #finishInitialization() {
-    this.initialized = true;
-    this.initializing = false;
-    this.stats.initDuration = performance.now() - this.stats.initStartTime;
-    console.log(`[SuperSonic] Initialization complete in ${this.stats.initDuration.toFixed(2)}ms`);
+    this.#initialized = true;
+    this.#initializing = false;
+    this.bootStats.initDuration = performance.now() - this.bootStats.initStartTime;
+    console.log(`[SuperSonic] Initialization complete in ${this.bootStats.initDuration.toFixed(2)}ms`);
     if (this.onInitialized) {
       this.onInitialized({
-        capabilities: this.capabilities,
-        stats: this.stats
+        capabilities: this.#capabilities,
+        bootStats: this.bootStats
       });
     }
   }
@@ -2148,11 +2495,11 @@ var SuperSonic = class _SuperSonic {
    * @param {Object} config.audioContextOptions - AudioContext options
    */
   async init(config = {}) {
-    if (this.initialized) {
+    if (this.#initialized) {
       console.warn("[SuperSonic] Already initialized");
       return;
     }
-    if (this.initializing) {
+    if (this.#initializing) {
       console.warn("[SuperSonic] Initialization already in progress");
       return;
     }
@@ -2164,10 +2511,10 @@ var SuperSonic = class _SuperSonic {
         ...config.audioContextOptions || {}
       }
     };
-    this.initializing = true;
-    this.stats.initStartTime = performance.now();
+    this.#initializing = true;
+    this.bootStats.initStartTime = performance.now();
     try {
-      this.checkCapabilities();
+      this.setAndValidateCapabilities();
       this.#initializeSharedMemory();
       this.#initializeAudioContext();
       this.#initializeBufferManager();
@@ -2178,7 +2525,7 @@ var SuperSonic = class _SuperSonic {
       this.#startPerformanceMonitoring();
       this.#finishInitialization();
     } catch (error) {
-      this.initializing = false;
+      this.#initializing = false;
       console.error("[SuperSonic] Initialization failed:", error);
       if (this.onError) {
         this.onError(error);
@@ -2201,30 +2548,25 @@ var SuperSonic = class _SuperSonic {
         if (event.data.type === "error") {
           console.error("[AudioWorklet] Error:", event.data.error);
           clearTimeout(timeout);
-          this.workletNode.port.removeEventListener("message", messageHandler);
+          this.#workletNode.port.removeEventListener("message", messageHandler);
           reject(new Error(event.data.error || "AudioWorklet error"));
           return;
         }
         if (event.data.type === "initialized") {
           clearTimeout(timeout);
-          this.workletNode.port.removeEventListener("message", messageHandler);
+          this.#workletNode.port.removeEventListener("message", messageHandler);
           if (event.data.success) {
             if (event.data.ringBufferBase !== void 0) {
-              this.ringBufferBase = event.data.ringBufferBase;
+              this.#ringBufferBase = event.data.ringBufferBase;
             } else {
               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;
+              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");
             }
@@ -2235,34 +2577,24 @@ var SuperSonic = class _SuperSonic {
           }
         }
       };
-      this.workletNode.port.addEventListener("message", messageHandler);
-      this.workletNode.port.start();
+      this.#workletNode.port.addEventListener("message", messageHandler);
+      this.#workletNode.port.start();
     });
   }
   /**
    * Set up message handlers for worklet
    */
   #setupMessageHandlers() {
-    this.workletNode.port.onmessage = (event) => {
+    this.#workletNode.port.onmessage = (event) => {
       const { data } = event;
       switch (data.type) {
-        case "status":
-          if (this.onStatusUpdate) {
-            this.onStatusUpdate(data);
-          }
-          break;
-        case "metrics":
-          if (this.onMetricsUpdate) {
-            this.onMetricsUpdate(data.metrics);
-          }
-          break;
         case "error":
           console.error("[Worklet] Error:", data.error);
           if (data.diagnostics) {
             console.error("[Worklet] Diagnostics:", data.diagnostics);
             console.table(data.diagnostics);
           }
-          this.stats.errors++;
+          this.#metrics_errors++;
           if (this.onError) {
             this.onError(new Error(data.error));
           }
@@ -2285,21 +2617,173 @@ var SuperSonic = class _SuperSonic {
     };
   }
   /**
-   * Start performance monitoring
+   * Get metrics from SharedArrayBuffer (worklet metrics written by WASM)
+   * @returns {Object|null}
+   * @private
+   */
+  #getWorkletMetrics() {
+    if (!this.#sharedBuffer || !this.#bufferConstants || !this.#ringBufferBase) {
+      return null;
+    }
+    const metricsBase = this.#ringBufferBase + this.#bufferConstants.METRICS_START;
+    const metricsCount = this.#bufferConstants.METRICS_SIZE / 4;
+    const metricsView = new Uint32Array(this.#sharedBuffer, metricsBase, metricsCount);
+    return {
+      processCount: Atomics.load(metricsView, 0),
+      // PROCESS_COUNT offset / 4
+      bufferOverruns: Atomics.load(metricsView, 1),
+      // BUFFER_OVERRUNS offset / 4
+      messagesProcessed: Atomics.load(metricsView, 2),
+      // MESSAGES_PROCESSED offset / 4
+      messagesDropped: Atomics.load(metricsView, 3),
+      // MESSAGES_DROPPED offset / 4
+      schedulerQueueDepth: Atomics.load(metricsView, 4),
+      // SCHEDULER_QUEUE_DEPTH offset / 4
+      schedulerQueueMax: Atomics.load(metricsView, 5),
+      // SCHEDULER_QUEUE_MAX offset / 4
+      schedulerQueueDropped: Atomics.load(metricsView, 6)
+      // SCHEDULER_QUEUE_DROPPED offset / 4
+    };
+  }
+  /**
+   * Get buffer usage statistics from SAB head/tail pointers
+   * @returns {Object|null}
+   * @private
+   */
+  #getBufferUsage() {
+    if (!this.#sharedBuffer || !this.#bufferConstants || !this.#ringBufferBase) {
+      return null;
+    }
+    const atomicView = new Int32Array(this.#sharedBuffer);
+    const controlBase = this.#ringBufferBase + this.#bufferConstants.CONTROL_START;
+    const inHead = Atomics.load(atomicView, (controlBase + 0) / 4);
+    const inTail = Atomics.load(atomicView, (controlBase + 4) / 4);
+    const outHead = Atomics.load(atomicView, (controlBase + 8) / 4);
+    const outTail = Atomics.load(atomicView, (controlBase + 12) / 4);
+    const debugHead = Atomics.load(atomicView, (controlBase + 16) / 4);
+    const debugTail = Atomics.load(atomicView, (controlBase + 20) / 4);
+    const inUsed = (inHead - inTail + this.#bufferConstants.IN_BUFFER_SIZE) % this.#bufferConstants.IN_BUFFER_SIZE;
+    const outUsed = (outHead - outTail + this.#bufferConstants.OUT_BUFFER_SIZE) % this.#bufferConstants.OUT_BUFFER_SIZE;
+    const debugUsed = (debugHead - debugTail + this.#bufferConstants.DEBUG_BUFFER_SIZE) % this.#bufferConstants.DEBUG_BUFFER_SIZE;
+    return {
+      inBufferUsed: {
+        bytes: inUsed,
+        percentage: Math.round(inUsed / this.#bufferConstants.IN_BUFFER_SIZE * 100)
+      },
+      outBufferUsed: {
+        bytes: outUsed,
+        percentage: Math.round(outUsed / this.#bufferConstants.OUT_BUFFER_SIZE * 100)
+      },
+      debugBufferUsed: {
+        bytes: debugUsed,
+        percentage: Math.round(debugUsed / this.#bufferConstants.DEBUG_BUFFER_SIZE * 100)
+      }
+    };
+  }
+  /**
+   * Get OSC worker metrics from SharedArrayBuffer (written by OSC workers)
+   * @returns {Object|null}
+   * @private
+   */
+  #getOSCMetrics() {
+    if (!this.#sharedBuffer || !this.#bufferConstants || !this.#ringBufferBase) {
+      return null;
+    }
+    const metricsBase = this.#ringBufferBase + this.#bufferConstants.METRICS_START;
+    const metricsCount = this.#bufferConstants.METRICS_SIZE / 4;
+    const metricsView = new Uint32Array(this.#sharedBuffer, metricsBase, metricsCount);
+    return {
+      // OSC Out (prescheduler) - offsets 7-18
+      preschedulerPending: metricsView[7],
+      preschedulerPeak: metricsView[8],
+      preschedulerSent: metricsView[9],
+      bundlesDropped: metricsView[10],
+      retriesSucceeded: metricsView[11],
+      retriesFailed: metricsView[12],
+      bundlesScheduled: metricsView[13],
+      eventsCancelled: metricsView[14],
+      totalDispatches: metricsView[15],
+      messagesRetried: metricsView[16],
+      retryQueueSize: metricsView[17],
+      retryQueueMax: metricsView[18],
+      // OSC In - offsets 19-22
+      oscInMessagesReceived: metricsView[19],
+      oscInDroppedMessages: metricsView[20],
+      oscInWakeups: metricsView[21],
+      oscInTimeouts: metricsView[22],
+      // Debug - offsets 23-26
+      debugMessagesReceived: metricsView[23],
+      debugWakeups: metricsView[24],
+      debugTimeouts: metricsView[25],
+      debugBytesRead: metricsView[26]
+    };
+  }
+  /**
+   * Gather metrics from all sources (worklet, OSC, internal counters)
+   * All metrics are read synchronously from SAB
+   * @returns {SuperSonicMetrics}
+   * @private
+   */
+  #gatherMetrics() {
+    const startTime = performance.now();
+    const metrics = {
+      // SuperSonic counters (in-memory, fast)
+      messagesSent: this.#metrics_messagesSent,
+      messagesReceived: this.#metrics_messagesReceived,
+      errors: this.#metrics_errors
+    };
+    const workletMetrics = this.#getWorkletMetrics();
+    if (workletMetrics) {
+      Object.assign(metrics, workletMetrics);
+    }
+    const bufferUsage = this.#getBufferUsage();
+    if (bufferUsage) {
+      Object.assign(metrics, bufferUsage);
+    }
+    const oscMetrics = this.#getOSCMetrics();
+    if (oscMetrics) {
+      Object.assign(metrics, oscMetrics);
+    }
+    const totalDuration = performance.now() - startTime;
+    if (totalDuration > 1) {
+      console.warn(`[SuperSonic] Slow metrics gathering: ${totalDuration.toFixed(2)}ms`);
+    }
+    return metrics;
+  }
+  /**
+   * Start performance monitoring - gathers metrics from all sources
+   * and calls onMetricsUpdate with consolidated snapshot
    */
   #startPerformanceMonitoring() {
-    setInterval(() => {
-      if (this.osc) {
-        this.osc.getStats().then((stats) => {
-          if (stats && this.onMetricsUpdate) {
-            this.onMetricsUpdate(stats);
-          }
-        });
+    if (this.#metricsIntervalId) {
+      clearInterval(this.#metricsIntervalId);
+    }
+    this.#metricsIntervalId = setInterval(() => {
+      if (!this.onMetricsUpdate) return;
+      if (this.#metricsGatherInProgress) {
+        console.warn("[SuperSonic] Metrics gathering took >100ms, skipping this interval");
+        return;
       }
-      if (this.workletNode) {
-        this.workletNode.port.postMessage({ type: "getMetrics" });
+      this.#metricsGatherInProgress = true;
+      try {
+        const metrics = this.#gatherMetrics();
+        this.onMetricsUpdate(metrics);
+      } catch (error) {
+        console.error("[SuperSonic] Metrics gathering failed:", error);
+      } finally {
+        this.#metricsGatherInProgress = false;
       }
-    }, 50);
+    }, 100);
+  }
+  /**
+   * Stop performance monitoring
+   * @private
+   */
+  #stopPerformanceMonitoring() {
+    if (this.#metricsIntervalId) {
+      clearInterval(this.#metricsIntervalId);
+      this.#metricsIntervalId = null;
+    }
   }
   /**
    * Send OSC message with simplified syntax (auto-detects types)
@@ -2327,73 +2811,11 @@ var SuperSonic = class _SuperSonic {
     const oscData = _SuperSonic.osc.encode(message);
     return this.sendOSC(oscData);
   }
-  /**
-   * Resolve audio file path to full URL
-   */
-  _resolveAudioPath(scPath) {
-    if (this.audioPathMap[scPath]) {
-      return this.audioPathMap[scPath];
-    }
-    if (!this.sampleBaseURL) {
-      throw new Error(
-        '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;
-  }
   #ensureInitialized(actionDescription = "perform this operation") {
-    if (!this.initialized) {
+    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 freedPtr = args[1];
-    const bufferInfo = this.allocatedBuffers.get(bufnum);
-    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
-   */
-  _handleBufferAllocated(args) {
-    const uuid = args[0];
-    const bufnum = args[1];
-    const pending = this.pendingBufferOps.get(uuid);
-    if (pending) {
-      clearTimeout(pending.timeout);
-      pending.resolve({ bufnum });
-      this.pendingBufferOps.delete(uuid);
-    }
-  }
   /**
    * Send pre-encoded OSC bytes to scsynth
    * @param {ArrayBuffer|Uint8Array} oscData - Pre-encoded OSC data
@@ -2403,7 +2825,7 @@ var SuperSonic = class _SuperSonic {
     this.#ensureInitialized("send OSC data");
     const uint8Data = this.#toUint8Array(oscData);
     const preparedData = await this.#prepareOutboundPacket(uint8Data);
-    this.stats.messagesSent++;
+    this.#metrics_messagesSent++;
     if (this.onMessageSent) {
       this.onMessageSent(preparedData);
     }
@@ -2413,17 +2835,56 @@ var SuperSonic = class _SuperSonic {
       sendOptions.audioTimeS = timing.audioTimeS;
       sendOptions.currentTimeS = timing.currentTimeS;
     }
-    this.osc.send(preparedData, sendOptions);
+    this.#osc.send(preparedData, sendOptions);
+  }
+  /**
+   * Get AudioContext instance (read-only)
+   * @returns {AudioContext} The AudioContext instance
+   */
+  get audioContext() {
+    return this.#audioContext;
+  }
+  /**
+   * Get AudioWorkletNode instance (read-only)
+   * @returns {AudioWorkletNode} The AudioWorkletNode instance
+   */
+  get workletNode() {
+    return this.#workletNode;
+  }
+  /**
+   * Get ScsynthOSC instance (read-only)
+   * @returns {ScsynthOSC} The OSC communication layer instance
+   */
+  get osc() {
+    return this.#osc;
   }
   /**
    * Get current status
    */
   getStatus() {
     return {
-      initialized: this.initialized,
-      capabilities: this.capabilities,
-      stats: this.stats,
-      audioContextState: this.audioContext?.state
+      initialized: this.#initialized,
+      capabilities: this.#capabilities,
+      bootStats: this.bootStats,
+      audioContextState: this.#audioContext?.state
+    };
+  }
+  /**
+   * Get current configuration (merged defaults + user overrides)
+   * Useful for debugging and displaying in UI
+   * @returns {Object} Current scsynth configuration
+   * @example
+   * const config = sonic.getConfig();
+   * console.log('Buffer limit:', config.worldOptions.numBuffers);
+   * console.log('Memory layout:', config.memory);
+   */
+  getConfig() {
+    if (!this.config) {
+      return null;
+    }
+    return {
+      memory: { ...this.config.memory },
+      worldOptions: { ...this.config.worldOptions }
     };
   }
   /**
@@ -2432,42 +2893,36 @@ var SuperSonic = class _SuperSonic {
   async destroy() {
     console.log("[SuperSonic] Destroying...");
     this.#stopDriftOffsetTimer();
-    if (this.osc) {
-      this.osc.terminate();
-      this.osc = null;
+    this.#stopPerformanceMonitoring();
+    if (this.#osc) {
+      this.#osc.terminate();
+      this.#osc = null;
     }
-    if (this.workletNode) {
-      this.workletNode.disconnect();
-      this.workletNode = null;
+    if (this.#workletNode) {
+      this.#workletNode.disconnect();
+      this.#workletNode = null;
     }
-    if (this.audioContext) {
-      await this.audioContext.close();
-      this.audioContext = null;
+    if (this.#audioContext) {
+      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"));
+    if (this.#bufferManager) {
+      this.#bufferManager.destroy();
+      this.#bufferManager = null;
     }
-    this.pendingBufferOps.clear();
-    this.sharedBuffer = null;
-    this.initialized = false;
-    this.bufferManager = null;
-    this.allocatedBuffers.clear();
+    this.#sharedBuffer = null;
+    this.#initialized = false;
     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.
+   * Get NTP start time for bundle creation.
+   * This is the NTP timestamp when AudioContext.currentTime was 0.
+   * Bundles should have timestamp = audioContextTime + ntpStartTime
    */
-  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);
+  waitForTimeSync() {
+    this.#ensureInitialized("wait for time sync");
+    const ntpStartView = new Float64Array(this.#sharedBuffer, this.#ringBufferBase + this.#bufferConstants.NTP_START_TIME_START, 1);
     return ntpStartView[0];
   }
   /**
@@ -2503,7 +2958,7 @@ var SuperSonic = class _SuperSonic {
    * await sonic.loadSynthDef('./extra/synthdefs/sonic-pi-beep.scsyndef');
    */
   async loadSynthDef(path) {
-    if (!this.initialized) {
+    if (!this.#initialized) {
       throw new Error("SuperSonic not initialized. Call init() first.");
     }
     try {
@@ -2532,10 +2987,10 @@ var SuperSonic = class _SuperSonic {
    * const results = await sonic.loadSynthDefs(['sonic-pi-beep', 'sonic-pi-tb303']);
    */
   async loadSynthDefs(names) {
-    if (!this.initialized) {
+    if (!this.#initialized) {
       throw new Error("SuperSonic not initialized. Call init() first.");
     }
-    if (!this.synthdefBaseURL) {
+    if (!this.#synthdefBaseURL) {
       throw new Error(
         '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'
       );
@@ -2544,7 +2999,7 @@ var SuperSonic = class _SuperSonic {
     await Promise.all(
       names.map(async (name) => {
         try {
-          const path = `${this.synthdefBaseURL}${name}.scsyndef`;
+          const path = `${this.#synthdefBaseURL}${name}.scsyndef`;
           await this.loadSynthDef(path);
           results[name] = { success: true };
         } catch (error) {
@@ -2567,7 +3022,7 @@ var SuperSonic = class _SuperSonic {
    * await sonic.sync(12345); // Wait for all synthdefs to be processed
    */
   async sync(syncId) {
-    if (!this.initialized) {
+    if (!this.#initialized) {
       throw new Error("SuperSonic not initialized. Call init() first.");
     }
     if (!Number.isInteger(syncId)) {
@@ -2575,20 +3030,20 @@ var SuperSonic = class _SuperSonic {
     }
     const syncPromise = new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
-        if (this._syncListeners) {
-          this._syncListeners.delete(syncId);
+        if (this.#syncListeners) {
+          this.#syncListeners.delete(syncId);
         }
         reject(new Error("Timeout waiting for /synced response"));
       }, 1e4);
       const messageHandler = (msg) => {
         clearTimeout(timeout);
-        this._syncListeners.delete(syncId);
+        this.#syncListeners.delete(syncId);
         resolve();
       };
-      if (!this._syncListeners) {
-        this._syncListeners = /* @__PURE__ */ new Map();
+      if (!this.#syncListeners) {
+        this.#syncListeners = /* @__PURE__ */ new Map();
       }
-      this._syncListeners.set(syncId, messageHandler);
+      this.#syncListeners.set(syncId, messageHandler);
     });
     await this.send("/sync", syncId);
     await syncPromise;
@@ -2601,15 +3056,8 @@ var SuperSonic = class _SuperSonic {
    * const bufferAddr = sonic.allocBuffer(44100);  // Allocate 1 second at 44.1kHz
    */
   allocBuffer(numSamples) {
-    if (!this.initialized) {
-      throw new Error("SuperSonic not initialized. Call init() first.");
-    }
-    const sizeBytes = numSamples * 4;
-    const addr = this.bufferPool.malloc(sizeBytes);
-    if (addr === 0) {
-      console.error(`[SuperSonic] Buffer allocation failed: ${numSamples} samples (${sizeBytes} bytes)`);
-    }
-    return addr;
+    this.#ensureInitialized("allocate buffers");
+    return this.#bufferManager.allocate(numSamples);
   }
   /**
    * Free a previously allocated buffer
@@ -2619,10 +3067,8 @@ var SuperSonic = class _SuperSonic {
    * sonic.freeBuffer(bufferAddr);
    */
   freeBuffer(addr) {
-    if (!this.initialized) {
-      throw new Error("SuperSonic not initialized. Call init() first.");
-    }
-    return this.bufferPool.free(addr);
+    this.#ensureInitialized("free buffers");
+    return this.#bufferManager.free(addr);
   }
   /**
    * Get a Float32Array view of an allocated buffer
@@ -2634,10 +3080,8 @@ var SuperSonic = class _SuperSonic {
    * view[0] = 1.0;  // Write to buffer
    */
   getBufferView(addr, numSamples) {
-    if (!this.initialized) {
-      throw new Error("SuperSonic not initialized. Call init() first.");
-    }
-    return new Float32Array(this.sharedBuffer, addr, numSamples);
+    this.#ensureInitialized("get buffer views");
+    return this.#bufferManager.getView(addr, numSamples);
   }
   /**
    * Get buffer pool statistics
@@ -2647,37 +3091,13 @@ var SuperSonic = class _SuperSonic {
    * console.log(`Available: ${stats.available} bytes`);
    */
   getBufferPoolStats() {
-    if (!this.initialized) {
-      throw new Error("SuperSonic not initialized. Call init() first.");
-    }
-    return this.bufferPool.stats();
+    this.#ensureInitialized("get buffer pool stats");
+    return this.#bufferManager.getStats();
   }
   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
-      },
+      buffers: this.#bufferManager.getDiagnostics(),
       synthdefs: {
         count: this.loadedSynthDefs.size
       }
@@ -2689,21 +3109,21 @@ var SuperSonic = class _SuperSonic {
    * @private
    */
   initializeNTPTiming() {
-    if (!this.bufferConstants || !this.audioContext) {
+    if (!this.#bufferConstants || !this.#audioContext) {
       return;
     }
-    const perfTimeMs = performance.timeOrigin + performance.now();
+    const timestamp = this.#audioContext.getOutputTimestamp();
+    const perfTimeMs = performance.timeOrigin + timestamp.performanceTime;
     const currentNTP = perfTimeMs / 1e3 + NTP_EPOCH_OFFSET;
-    const currentAudioCtx = this.audioContext.currentTime;
-    const ntpStartTime = currentNTP - currentAudioCtx;
+    const ntpStartTime = currentNTP - timestamp.contextTime;
     const ntpStartView = new Float64Array(
-      this.sharedBuffer,
-      this.ringBufferBase + this.bufferConstants.NTP_START_TIME_START,
+      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}`);
+    this.#initialNTPStartTime = ntpStartTime;
+    console.log(`[SuperSonic] NTP timing initialized: start=${ntpStartTime.toFixed(6)}s (NTP=${currentNTP.toFixed(3)}s, contextTime=${timestamp.contextTime.toFixed(3)}s)`);
   }
   /**
    * Update drift offset (AudioContext → NTP drift correction)
@@ -2711,34 +3131,34 @@ var SuperSonic = class _SuperSonic {
    * @private
    */
   updateDriftOffset() {
-    if (!this.bufferConstants || !this.audioContext || this._initialNTPStartTime === void 0) {
+    if (!this.#bufferConstants || !this.#audioContext || this.#initialNTPStartTime === void 0) {
       return;
     }
-    const perfTimeMs = performance.timeOrigin + performance.now();
+    const timestamp = this.#audioContext.getOutputTimestamp();
+    const perfTimeMs = performance.timeOrigin + timestamp.performanceTime;
     const currentNTP = perfTimeMs / 1e3 + NTP_EPOCH_OFFSET;
-    const currentAudioCtx = this.audioContext.currentTime;
-    const currentNTPStartTime = currentNTP - currentAudioCtx;
-    const driftSeconds = currentNTPStartTime - this._initialNTPStartTime;
+    const expectedContextTime = currentNTP - this.#initialNTPStartTime;
+    const driftSeconds = expectedContextTime - timestamp.contextTime;
     const driftMs = Math.round(driftSeconds * 1e3);
     const driftView = new Int32Array(
-      this.sharedBuffer,
-      this.ringBufferBase + this.bufferConstants.DRIFT_OFFSET_START,
+      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)})`);
+    console.log(`[SuperSonic] Drift offset: ${driftMs}ms (expected=${expectedContextTime.toFixed(3)}s, actual=${timestamp.contextTime.toFixed(3)}s, NTP=${currentNTP.toFixed(3)}s)`);
   }
   /**
    * Get current drift offset in milliseconds
    * @returns {number} Current drift in milliseconds
    */
   getDriftOffset() {
-    if (!this.bufferConstants) {
+    if (!this.#bufferConstants) {
       return 0;
     }
     const driftView = new Int32Array(
-      this.sharedBuffer,
-      this.ringBufferBase + this.bufferConstants.DRIFT_OFFSET_START,
+      this.#sharedBuffer,
+      this.#ringBufferBase + this.#bufferConstants.DRIFT_OFFSET_START,
       1
     );
     return Atomics.load(driftView, 0);
@@ -2749,7 +3169,7 @@ var SuperSonic = class _SuperSonic {
    */
   #startDriftOffsetTimer() {
     this.#stopDriftOffsetTimer();
-    this._driftOffsetTimer = setInterval(() => {
+    this.#driftOffsetTimer = setInterval(() => {
       this.updateDriftOffset();
     }, DRIFT_UPDATE_INTERVAL_MS);
     console.log(`[SuperSonic] Started drift offset correction (every ${DRIFT_UPDATE_INTERVAL_MS}ms)`);
@@ -2759,9 +3179,9 @@ var SuperSonic = class _SuperSonic {
    * @private
    */
   #stopDriftOffsetTimer() {
-    if (this._driftOffsetTimer) {
-      clearInterval(this._driftOffsetTimer);
-      this._driftOffsetTimer = null;
+    if (this.#driftOffsetTimer) {
+      clearInterval(this.#driftOffsetTimer);
+      this.#driftOffsetTimer = null;
     }
   }
   #extractSynthDefName(path) {
@@ -2883,7 +3303,7 @@ var SuperSonic = class _SuperSonic {
     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;
+    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++;
@@ -2974,10 +3394,10 @@ var SuperSonic = class _SuperSonic {
     });
   }
   #requireBufferManager() {
-    if (!this.bufferManager) {
+    if (!this.#bufferManager) {
       throw new Error("Buffer manager not ready. Call init() before issuing buffer commands.");
     }
-    return this.bufferManager;
+    return this.#bufferManager;
   }
   #isBundle(packet) {
     return packet && packet.timeTag !== void 0 && Array.isArray(packet.packets);
@@ -2990,16 +3410,16 @@ var SuperSonic = class _SuperSonic {
     if (header !== "#bundle\0") {
       return null;
     }
-    const ntpStartView = new Float64Array(this.sharedBuffer, this.ringBufferBase + this.bufferConstants.NTP_START_TIME_START, 1);
+    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 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 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;
@@ -3011,7 +3431,7 @@ var SuperSonic = class _SuperSonic {
     }
     const ntpTimeS = ntpSeconds + ntpFraction / 4294967296;
     const audioTimeS = ntpTimeS - totalOffset;
-    const currentTimeS = this.audioContext.currentTime;
+    const currentTimeS = this.#audioContext.currentTime;
     return { audioTimeS, currentTimeS };
   }
 };