@libraz/libsonare 1.5.5 → 1.7.0

package/src/worklet/engine-processor.ts

@@ -1,4 +1,4 @@
-import type { EngineClip, EngineScopeTelemetry } from '../index';
+import type { EngineClip } from '../index';
 import { RealtimeEngine } from '../index';
 import type { WorkletInput, WorkletOutput } from './audio_types';
 import {
@@ -6,7 +6,7 @@ import {
   type ResolvedMetronomeConfig,
   resolveMetronomeConfig,
   type SonareEngineCaptureRequestMessage,
-  type SonareEngineCaptureResponseMessage,
+  type SonareEngineCaptureResponseMessageInternal,
   type SonareEngineSyncMessage,
   type SonareEngineTransportRequestMessage,
   type SonareEngineTransportResponseMessage,
@@ -14,12 +14,18 @@ import {
   type WorkletTransport,
 } from './messages';
 import {
+  clipPageRequestRingFromSharedBuffer,
   encodeFrameHi,
   encodeFrameLo,
   engineRingFromSharedBuffer,
+  externalMidiRingFromSharedBuffer,
   meterFromEngine,
   meterRingFromSharedBuffer,
   popSonareEngineCommandRingBuffer,
+  pushSonareClipPageRequestRingBuffer,
+  pushSonareExternalMidiRingBuffer,
+  type SharedClipPageRequestRingWriter,
+  type SharedExternalMidiRingWriter,
   type SharedMeterRingWriter,
   type SharedScopeRingWriter,
   SONARE_ENGINE_COMMAND_RECORD_BYTES,
@@ -36,9 +42,26 @@ import {
   type SonareWorkletMeterSnapshot,
   scopeRingFromSharedBuffer,
   telemetryFromEngine,
+  writeInt64Words,
   writeSonareEngineTelemetryRingBuffer,
 } from './protocol';
 
+function captureTransferList(channels: readonly Float32Array[]): Transferable[] {
+  const transfers: ArrayBuffer[] = [];
+  const seen = new Set<ArrayBuffer>();
+  for (const channel of channels) {
+    const buffer = channel.buffer;
+    if (!(buffer instanceof ArrayBuffer)) {
+      throw new TypeError('capture response channels must use plain ArrayBuffers');
+    }
+    if (!seen.has(buffer)) {
+      seen.add(buffer);
+      transfers.push(buffer);
+    }
+  }
+  return transfers;
+}
+
 /**
  * AudioWorklet-style bridge for the DAW realtime engine facade.
  *
@@ -55,6 +78,8 @@ export class SonareRealtimeEngineWorkletProcessor {
   private telemetryRing?: SonareEngineTelemetryRingBuffer;
   private meterRing?: SharedMeterRingWriter;
   private scopeRing?: SharedScopeRingWriter;
+  private clipPageRequestRing?: SharedClipPageRequestRingWriter;
+  private externalMidiRing?: SharedExternalMidiRingWriter;
   private transport?: WorkletTransport;
   private meterIntervalFrames: number;
   private lastMeterFrame = Number.NEGATIVE_INFINITY;
@@ -71,7 +96,15 @@ export class SonareRealtimeEngineWorkletProcessor {
   private channelBuffers: Float32Array[];
   private readonly liveClips = new Map<number, EngineClip>();
   private readonly pagedClipProviders = new Map<number, number>();
+  private readonly pagedClipPageFrames = new Map<number, number>();
   private readonly pendingPagedClips = new Map<number, EngineClip>();
+  // The worklet drains at most this many distinct page misses per render
+  // quantum. The fixed scalar buffers avoid retaining an unbounded queue on
+  // the audio thread; any remaining native requests stay queued for the next
+  // quantum and render silence meanwhile.
+  private readonly clipPageRequestClipIds = new Float64Array(64);
+  private readonly clipPageRequestPageIndices = new Float64Array(64);
+  private clipPageRequestOverflowReported = 0;
 
   constructor(
     options: SonareRealtimeEngineWorkletProcessorOptions = {},
@@ -101,7 +134,25 @@ export class SonareRealtimeEngineWorkletProcessor {
           options.scopeBands,
         )
       : undefined;
-    this.engine = new RealtimeEngine(this.sampleRate, this.blockSize);
+    this.clipPageRequestRing = options.clipPageRequestSharedBuffer
+      ? clipPageRequestRingFromSharedBuffer(
+          options.clipPageRequestSharedBuffer,
+          options.clipPageRequestRingCapacity,
+        )
+      : undefined;
+    this.externalMidiRing = options.externalMidiSharedBuffer
+      ? externalMidiRingFromSharedBuffer(
+          options.externalMidiSharedBuffer,
+          options.externalMidiRingCapacity,
+        )
+      : undefined;
+    this.engine = new RealtimeEngine(
+      this.sampleRate,
+      this.blockSize,
+      1024,
+      1024,
+      this.channelCount,
+    );
     // Allocate persistent WASM-heap scratch (worst case: channelCount channels x
     // blockSize frames) and acquire the per-channel heap views once.
     this.engine.prepareChannels(this.channelCount, this.blockSize);
@@ -191,6 +242,7 @@ export class SonareRealtimeEngineWorkletProcessor {
         target.fill(0);
       }
     }
+    this.publishClipPageRequests();
     this.publishTelemetry();
     this.publishMeters();
     this.publishScope();
@@ -206,7 +258,7 @@ export class SonareRealtimeEngineWorkletProcessor {
 
   receiveCommand(command: SonareEngineCommandRecord): void {
     if (!this.closed) {
-      this.applyCommand(command);
+      this.safeApplyCommand(command);
     }
   }
 
@@ -218,35 +270,68 @@ export class SonareRealtimeEngineWorkletProcessor {
     if (this.closed) {
       return;
     }
+    try {
+      this.applySync(message);
+    } catch (error) {
+      this.transport?.postMessage?.({
+        type: 'syncError',
+        syncType: message.type,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  private applySync(message: SonareEngineSyncMessage): void {
     switch (message.type) {
-      case 'syncClips':
+      case 'destroy':
+        this.destroy();
+        return;
+      case 'syncClips': {
+        // Commit native state before touching the worklet-side mirrors. A
+        // rejected embind call must leave a later delta based on the previous
+        // clip set, not on a half-applied replacement.
+        this.engine.setClips(message.clips);
+        this.clearPagedClipProviders();
         this.liveClips.clear();
         for (const clip of message.clips) {
           if (clip.id !== undefined) {
             this.liveClips.set(clip.id, clip);
           }
         }
-        this.engine.setClips(message.clips);
         break;
-      case 'syncClipsDelta':
+      }
+      case 'syncClipsDelta': {
+        const nextClips = new Map(this.liveClips);
         for (const clipId of message.removeIds) {
-          this.liveClips.delete(clipId);
+          nextClips.delete(clipId);
         }
         for (const clip of message.upserts) {
           if (clip.id !== undefined) {
-            this.liveClips.set(clip.id, clip);
+            nextClips.set(clip.id, clip);
           }
         }
-        this.engine.setClips(Array.from(this.liveClips.values()));
+        this.engine.setClips(Array.from(nextClips.values()));
+        for (const clipId of message.removeIds) {
+          this.removePagedClipProvider(clipId);
+        }
+        this.liveClips.clear();
+        for (const [clipId, clip] of nextClips) {
+          this.liveClips.set(clipId, clip);
+        }
         break;
+      }
       case 'syncClipPageProvider': {
         const provider = this.engine.createClipPageProvider(
           message.numChannels,
           message.numSamples,
           message.pageFrames,
         );
+        this.removePagedClipProvider(message.clipId);
         this.pagedClipProviders.set(message.clipId, provider.id);
-        this.pendingPagedClips.set(message.clipId, message.clip);
+        this.pagedClipPageFrames.set(message.clipId, message.pageFrames);
+        if (message.clip) {
+          this.pendingPagedClips.set(message.clipId, message.clip);
+        }
         break;
       }
       case 'syncClipPage': {
@@ -256,16 +341,34 @@ export class SonareRealtimeEngineWorkletProcessor {
         }
         break;
       }
+      case 'syncClipPageClear': {
+        const providerId = this.pagedClipProviders.get(message.clipId);
+        if (providerId !== undefined) {
+          this.engine.clearClipPage(providerId, message.pageIndex);
+        }
+        break;
+      }
       case 'syncClipPageCommit': {
         const providerId = this.pagedClipProviders.get(message.clipId);
-        const clip = this.pendingPagedClips.get(message.clipId);
+        const clip = message.clip ?? this.pendingPagedClips.get(message.clipId);
         if (providerId !== undefined && clip) {
-          this.liveClips.set(message.clipId, { ...clip, pageProvider: providerId });
+          const nextClip = { ...clip, pageProvider: providerId };
+          const nextClips = new Map(this.liveClips);
+          nextClips.set(message.clipId, nextClip);
+          this.engine.setClips(Array.from(nextClips.values()));
+          this.liveClips.set(message.clipId, nextClip);
           this.pendingPagedClips.delete(message.clipId);
-          this.engine.setClips(Array.from(this.liveClips.values()));
         }
         break;
       }
+      case 'syncClipPageDestroy': {
+        const nextClips = new Map(this.liveClips);
+        nextClips.delete(message.clipId);
+        this.engine.setClips(Array.from(nextClips.values()));
+        this.liveClips.delete(message.clipId);
+        this.removePagedClipProvider(message.clipId);
+        break;
+      }
       case 'syncMidiClips':
         this.engine.setMidiClips(message.clips);
         break;
@@ -273,12 +376,23 @@ export class SonareRealtimeEngineWorkletProcessor {
         this.engine.setMarkers(message.markers);
         break;
       case 'syncMetronome':
-        this.metronomeConfig = resolveMetronomeConfig(message.config);
-        this.engine.setMetronome(message.config);
+        // Do not publish the cached config until the native engine accepted it.
+        // Otherwise a rejected sync would corrupt the command-side fallback.
+        {
+          const config = resolveMetronomeConfig(message.config);
+          this.engine.setMetronome(message.config);
+          this.metronomeConfig = config;
+        }
         break;
       case 'syncAutomation':
         this.engine.setAutomationLane(message.paramId, message.points);
         break;
+      case 'syncParameters':
+        this.engine.clearParameters();
+        for (const info of message.parameters) {
+          this.engine.addParameter(info);
+        }
+        break;
       case 'syncTempo':
         if (message.tempoSegments) {
           this.engine.setTempoSegments(message.tempoSegments);
@@ -425,6 +539,9 @@ export class SonareRealtimeEngineWorkletProcessor {
           message.renderFrame,
         );
         break;
+      case 'syncMidiUmp':
+        this.engine.pushMidiUmp(message.destinationId, message.word0, message.renderFrame);
+        break;
       case 'syncMidiSysex':
         this.engine.pushMidiSysex(message.destinationId, message.data, message.renderFrame);
         break;
@@ -437,6 +554,45 @@ export class SonareRealtimeEngineWorkletProcessor {
       case 'syncExternalMidiClock':
         this.engine.setExternalMidiClockEnabled(message.enabled);
         break;
+      case 'syncMidiInputSource':
+        this.engine.setMidiInputSource(message.destinationId ?? 0);
+        break;
+      case 'syncClearMidiInputSource':
+        this.engine.clearMidiInputSource();
+        break;
+      case 'syncMidiCcBinding':
+        this.engine.bindMidiCc(message.channel, message.controller, message.paramId, {
+          minValue: message.minValue,
+          maxValue: message.maxValue,
+        });
+        break;
+      case 'syncMidiInputNoteOn':
+        this.engine.pushMidiInputNoteOn(
+          message.group,
+          message.channel,
+          message.data0,
+          message.data1,
+          message.portTimeSamples,
+        );
+        break;
+      case 'syncMidiInputNoteOff':
+        this.engine.pushMidiInputNoteOff(
+          message.group,
+          message.channel,
+          message.data0,
+          message.data1,
+          message.portTimeSamples,
+        );
+        break;
+      case 'syncMidiInputCc':
+        this.engine.pushMidiInputCc(
+          message.group,
+          message.channel,
+          message.data0,
+          message.data1,
+          message.portTimeSamples,
+        );
+        break;
     }
   }
 
@@ -459,26 +615,24 @@ export class SonareRealtimeEngineWorkletProcessor {
             source: status.source,
             recordOffsetSamples: status.recordOffsetSamples,
           },
-        } satisfies SonareEngineCaptureResponseMessage);
+        } satisfies SonareEngineCaptureResponseMessageInternal);
         return;
       }
       if (message.op === 'read') {
-        const captured = this.engine.capturedAudio();
-        const channels: number[][] = [];
-        for (let ch = 0; ch < captured.length; ch++) {
-          const source = captured[ch];
-          const copy: number[] = [];
-          for (let i = 0; i < source.length; i++) {
-            copy.push(Number(source[i]));
-          }
-          channels.push(copy);
-        }
-        this.transport?.postMessage?.({
-          type: 'captureResponse',
-          requestId: message.requestId,
-          ok: true,
-          channels,
-        } satisfies SonareEngineCaptureResponseMessage);
+        // Embind's outer val::array is array-like but not structured-cloneable
+        // in every host. Copy only that tiny container; keep each native
+        // Float32Array intact so the channel payload remains transferable.
+        const channels = Array.from(this.engine.capturedAudio());
+        const transfer = captureTransferList(channels);
+        this.transport?.postMessage?.(
+          {
+            type: 'captureResponse',
+            requestId: message.requestId,
+            ok: true,
+            channels,
+          } satisfies SonareEngineCaptureResponseMessageInternal,
+          transfer,
+        );
         return;
       }
       this.engine.resetCapture();
@@ -486,14 +640,14 @@ export class SonareRealtimeEngineWorkletProcessor {
         type: 'captureResponse',
         requestId: message.requestId,
         ok: true,
-      } satisfies SonareEngineCaptureResponseMessage);
+      } satisfies SonareEngineCaptureResponseMessageInternal);
     } catch (error) {
       this.transport?.postMessage?.({
         type: 'captureResponse',
         requestId: message.requestId,
         ok: false,
         error: error instanceof Error ? error.message : String(error),
-      } satisfies SonareEngineCaptureResponseMessage);
+      } satisfies SonareEngineCaptureResponseMessageInternal);
     }
   }
 
@@ -520,6 +674,7 @@ export class SonareRealtimeEngineWorkletProcessor {
 
   destroy(): void {
     if (!this.closed) {
+      this.clearPagedClipProviders();
       this.engine.destroy();
       this.closed = true;
     }
@@ -534,7 +689,25 @@ export class SonareRealtimeEngineWorkletProcessor {
       if (!command) {
         return;
       }
+      this.safeApplyCommand(command);
+    }
+  }
+
+  private safeApplyCommand(command: SonareEngineCommandRecord): void {
+    try {
       this.applyCommand(command);
+    } catch {
+      // A malformed control command must never escape AudioWorklet.process():
+      // Web Audio permanently stops invoking a processor that throws there.
+      this.publishTelemetryRecord({
+        type: SonareEngineTelemetryType.Error,
+        error: SonareEngineTelemetryError.InvalidCommand,
+        renderFrame: 0,
+        timelineSample: 0,
+        audibleTimelineSample: 0,
+        graphLatencySamplesQ8: 0,
+        value: Number(command.type),
+      });
     }
   }
 
@@ -569,9 +742,6 @@ export class SonareRealtimeEngineWorkletProcessor {
       case SonareEngineCommandType.TransportSeekPpq:
         this.engine.seekPpq(Number(command.argFloat ?? 0), sampleTime);
         break;
-      case SonareEngineCommandType.SetTempoMap:
-        this.engine.setTempo(Number(command.argFloat ?? 120));
-        break;
       case SonareEngineCommandType.SetLoop:
         this.engine.setLoop(
           Number(command.argFloat ?? 0),
@@ -601,6 +771,7 @@ export class SonareRealtimeEngineWorkletProcessor {
           beatGain: this.metronomeConfig.beatGain,
           accentGain: this.metronomeConfig.accentGain,
           clickSamples: this.metronomeConfig.clickSamples,
+          clickSeconds: this.metronomeConfig.clickSeconds,
         });
         break;
       case SonareEngineCommandType.SeekMarker:
@@ -616,6 +787,24 @@ export class SonareRealtimeEngineWorkletProcessor {
           sampleTime,
         );
         break;
+      case SonareEngineCommandType.SetTrackMonitorMode: {
+        const rawMode = command.argInt;
+        const mode = typeof rawMode === 'bigint' ? Number(rawMode) : rawMode;
+        if (typeof mode !== 'number' || !Number.isSafeInteger(mode) || mode < 0 || mode > 2) {
+          throw new RangeError(`Invalid track monitor mode: ${String(rawMode)}`);
+        }
+        const laneIndex = command.targetId;
+        if (
+          typeof laneIndex !== 'number' ||
+          !Number.isSafeInteger(laneIndex) ||
+          laneIndex < 0 ||
+          laneIndex > 0xffff_ffff
+        ) {
+          throw new RangeError(`Invalid track monitor lane index: ${String(laneIndex)}`);
+        }
+        this.engine.setTrackMonitorMode(laneIndex, mode as 0 | 1 | 2, sampleTime);
+        break;
+      }
       default:
         this.publishTelemetryRecord({
           type: SonareEngineTelemetryType.Error,
@@ -631,11 +820,36 @@ export class SonareRealtimeEngineWorkletProcessor {
   }
 
   private publishTelemetry(): void {
+    const ring = this.telemetryRing;
+    if (ring) {
+      for (let count = 0; count < 64 && this.engine.popTelemetryToScratch(); count++) {
+        this.writeTelemetryScratch(ring);
+      }
+      return;
+    }
     for (const item of this.engine.drainTelemetry(64)) {
       this.publishTelemetryRecord(telemetryFromEngine(item));
     }
   }
 
+  private writeTelemetryScratch(ring: SonareEngineTelemetryRingBuffer): void {
+    const writeIndex = Atomics.load(ring.header, 0);
+    const offset = (writeIndex % ring.capacity) * SONARE_ENGINE_TELEMETRY_RECORD_BYTES;
+    ring.view.setUint32(offset, this.engine.telemetryScratchType(), true);
+    ring.view.setUint32(offset + 4, this.engine.telemetryScratchError(), true);
+    writeInt64Words(ring.view, offset + 8, this.engine.telemetryScratchRenderFrame());
+    writeInt64Words(ring.view, offset + 16, this.engine.telemetryScratchTimelineSample());
+    writeInt64Words(ring.view, offset + 24, this.engine.telemetryScratchAudibleTimelineSample());
+    ring.view.setInt32(offset + 32, this.engine.telemetryScratchGraphLatencySamplesQ8(), true);
+    ring.view.setUint32(offset + 36, this.engine.telemetryScratchValue(), true);
+    ring.view.setUint32(offset + 40, 0, true);
+    ring.view.setUint32(offset + 44, 0, true);
+    Atomics.store(ring.header, 0, writeIndex + 1);
+    if (writeIndex + 1 > ring.capacity) {
+      Atomics.store(ring.header, 4, writeIndex + 1 - ring.capacity);
+    }
+  }
+
   private publishTelemetryRecord(record: SonareEngineTelemetryRecord): void {
     if (this.telemetryRing) {
       writeSonareEngineTelemetryRingBuffer(this.telemetryRing, record);
@@ -659,6 +873,22 @@ export class SonareRealtimeEngineWorkletProcessor {
     if (this.meterIntervalFrames <= 0 || (!this.transport && !this.meterRing)) {
       return;
     }
+    if (this.meterRing) {
+      for (let count = 0; count < 64 && this.engine.popMeterTelemetryToScratch(); count++) {
+        const frame = this.engine.meterScratchRenderFrame();
+        if (
+          frame !== this.lastMeterFrame &&
+          frame - this.lastMeterFrame < this.meterIntervalFrames
+        ) {
+          continue;
+        }
+        if (frame !== this.lastMeterFrame) {
+          this.lastMeterFrame = frame;
+        }
+        this.writeMeterScratch(this.meterRing);
+      }
+      return;
+    }
     for (const item of this.engine.drainMeterTelemetry(64)) {
       const meter = meterFromEngine(item);
       if (
@@ -683,6 +913,19 @@ export class SonareRealtimeEngineWorkletProcessor {
     }
   }
 
+  private writeMeterScratch(ring: SharedMeterRingWriter): void {
+    const writeIndex = Atomics.load(ring.header, 0);
+    const offset = (writeIndex % ring.capacity) * SONARE_METER_RING_RECORD_FLOATS;
+    const frame = Number(this.engine.meterScratchRenderFrame());
+    ring.records[offset] = encodeFrameLo(frame);
+    ring.records[offset + 1] = encodeFrameHi(frame);
+    ring.records[offset + 2] = this.engine.meterScratchTargetId();
+    for (let field = 0; field < 11; field++) {
+      ring.records[offset + 3 + field] = this.engine.meterScratchValue(field);
+    }
+    Atomics.store(ring.header, 0, writeIndex + 1);
+  }
+
   private writeMeterRing(meter: SonareWorkletMeterSnapshot): void {
     const ring = this.meterRing;
     if (!ring) {
@@ -720,19 +963,59 @@ export class SonareRealtimeEngineWorkletProcessor {
     if (!ring) {
       return;
     }
-    for (const item of this.engine.drainScopeTelemetry(64)) {
-      this.writeScopeRing(ring, item);
+    for (let count = 0; count < 64 && this.engine.popScopeTelemetryToScratch(); count++) {
+      this.writeScopeScratch(ring);
     }
   }
 
+  private writeScopeScratch(ring: SharedScopeRingWriter): void {
+    const writeIndex = Atomics.load(ring.header, 0);
+    const base = (writeIndex % ring.capacity) * ring.recordFloats;
+    const frame = Number(this.engine.scopeScratchRenderFrame());
+    ring.records[base] = encodeFrameLo(frame);
+    ring.records[base + 1] = encodeFrameHi(frame);
+    ring.records[base + 2] = this.engine.scopeScratchTargetId();
+    const bandCount = Math.min(ring.bands, this.engine.scopeScratchBandCount());
+    ring.records[base + 3] = bandCount;
+    const pointCount = Math.min(ring.maxPoints, this.engine.scopeScratchPointCount());
+    ring.records[base + 4] = pointCount;
+    const bandsBase = base + SONARE_SCOPE_RING_RECORD_PREFIX_FLOATS;
+    for (let i = 0; i < bandCount; i++) {
+      ring.records[bandsBase + i] = this.engine.scopeScratchBand(i);
+    }
+    const pointsBase = bandsBase + ring.bands;
+    for (let i = 0; i < pointCount; i++) {
+      ring.records[pointsBase + 2 * i] = this.engine.scopeScratchPointLeft(i);
+      ring.records[pointsBase + 2 * i + 1] = this.engine.scopeScratchPointRight(i);
+    }
+    Atomics.store(ring.header, 0, writeIndex + 1);
+  }
+
   // Drains queued external-MIDI events (already lowered to MIDI 1.0 bytes) and
   // forwards them to the main thread for delivery to Web MIDI output ports.
   // One batch per render block; skipped entirely when nothing is queued, so an
   // all-internal project never allocates or posts here.
   private publishExternalMidi(): void {
+    const ring = this.externalMidiRing;
+    if (ring) {
+      for (let count = 0; count < 256 && this.engine.popExternalMidiToScratch(); count++) {
+        pushSonareExternalMidiRingBuffer(
+          ring,
+          this.engine.externalMidiScratchDestinationId(),
+          this.engine.externalMidiScratchRenderFrame(),
+          this.engine.externalMidiScratchByteWord(),
+          this.engine.externalMidiScratchByteCount(),
+        );
+        this.engine.consumeExternalMidiScratch();
+      }
+      return;
+    }
     if (!this.transport?.postMessage) {
       return;
     }
+    if (this.engine.externalMidiPendingCount() === 0) {
+      return;
+    }
     const events = this.engine.drainExternalMidi(256);
     if (events.length === 0) {
       return;
@@ -740,30 +1023,120 @@ export class SonareRealtimeEngineWorkletProcessor {
     this.transport.postMessage({ type: 'externalMidi', events });
   }
 
-  private writeScopeRing(ring: SharedScopeRingWriter, record: EngineScopeTelemetry): void {
-    const writeIndex = Atomics.load(ring.header, 0);
-    const base = (writeIndex % ring.capacity) * ring.recordFloats;
-    ring.records[base] = encodeFrameLo(record.renderFrame);
-    ring.records[base + 1] = encodeFrameHi(record.renderFrame);
-    ring.records[base + 2] = record.targetId;
-    const bandCount = Math.min(ring.bands, record.bands.length);
-    ring.records[base + 3] = bandCount;
-    const pointCount = Math.min(ring.maxPoints, record.points.length);
-    ring.records[base + 4] = pointCount;
-    const bandsBase = base + SONARE_SCOPE_RING_RECORD_PREFIX_FLOATS;
-    for (let i = 0; i < bandCount; i++) {
-      ring.records[bandsBase + i] = record.bands[i];
+  /**
+   * Forward a bounded batch of native page misses to the main thread. This
+   * deliberately runs after audio rendering: a cache miss is silence for this
+   * block, and OPFS I/O must never delay `process()`.
+   */
+  private publishClipPageRequests(): void {
+    const ring = this.clipPageRequestRing;
+    const transport = this.transport;
+    if (!ring && !transport?.postMessage) {
+      return;
     }
-    const pointsBase = bandsBase + ring.bands;
-    for (let i = 0; i < pointCount; i++) {
-      const point = record.points[i];
-      ring.records[pointsBase + 2 * i] = point.left;
-      ring.records[pointsBase + 2 * i + 1] = point.right;
+    let count = 0;
+    let drained = 0;
+    while (drained < this.clipPageRequestClipIds.length) {
+      drained += 1;
+      let clipId: number;
+      let sample: number;
+      if (ring) {
+        // This scalar scratch API is intentionally used only on the SAB path:
+        // it avoids embind materialising one JS object for every page miss in
+        // AudioWorklet process().
+        if (!this.engine.popClipPageRequestToScratch()) {
+          break;
+        }
+        clipId = this.engine.clipPageRequestScratchClipId();
+        sample = this.engine.clipPageRequestScratchSample();
+      } else {
+        // postMessage fallback is explicitly non-RT-safe; retain the public
+        // object-returning API only for that degraded control-plane path.
+        const request = this.engine.popClipPageRequest();
+        if (!request) {
+          break;
+        }
+        clipId = request.clipId;
+        sample = request.sample;
+      }
+      const pageFrames = this.pagedClipPageFrames.get(clipId);
+      if (!pageFrames) {
+        continue;
+      }
+      const pageIndex = Math.floor(sample / pageFrames);
+      let duplicate = false;
+      for (let i = 0; i < count; ++i) {
+        if (
+          this.clipPageRequestClipIds[i] === clipId &&
+          this.clipPageRequestPageIndices[i] === pageIndex
+        ) {
+          duplicate = true;
+          break;
+        }
+      }
+      if (!duplicate) {
+        this.clipPageRequestClipIds[count] = clipId;
+        this.clipPageRequestPageIndices[count] = pageIndex;
+        count += 1;
+      }
+    }
+    const overflowCount = this.engine.clipPageRequestOverflowCount();
+    // The native counter is uint32_t; preserve a correct delta across its
+    // defined unsigned wraparound instead of emitting a negative count.
+    const dropped = (overflowCount - this.clipPageRequestOverflowReported) >>> 0;
+    this.clipPageRequestOverflowReported = overflowCount;
+    if (ring) {
+      // Preserve native-queue loss in the same cumulative counter used for a
+      // full SAB request ring. No object, structured clone, or postMessage is
+      // created on this path.
+      if (dropped > 0) {
+        Atomics.add(ring.header, 4, dropped);
+      }
+      for (let i = 0; i < count; ++i) {
+        pushSonareClipPageRequestRingBuffer(
+          ring,
+          this.clipPageRequestClipIds[i],
+          this.clipPageRequestPageIndices[i],
+        );
+      }
+      return;
+    }
+    if (count === 0 && dropped === 0) {
+      return;
+    }
+    if (!transport?.postMessage) {
+      return;
+    }
+    // A message is necessarily allocated by postMessage; the hot path's
+    // resident queue remains fixed-size and no message is built without a miss.
+    const requests = new Array<{ clipId: number; pageIndex: number }>(count);
+    for (let i = 0; i < count; ++i) {
+      requests[i] = {
+        clipId: this.clipPageRequestClipIds[i],
+        pageIndex: this.clipPageRequestPageIndices[i],
+      };
+    }
+    transport.postMessage({
+      type: 'clipPageRequest',
+      requests,
+      ...(dropped > 0 ? { dropped } : {}),
+    });
+  }
+
+  private removePagedClipProvider(clipId: number): void {
+    const providerId = this.pagedClipProviders.get(clipId);
+    if (providerId !== undefined) {
+      this.engine.destroyClipPageProvider(providerId);
+    }
+    this.pagedClipProviders.delete(clipId);
+    this.pagedClipPageFrames.delete(clipId);
+    this.pendingPagedClips.delete(clipId);
+  }
+
+  private clearPagedClipProviders(): void {
+    for (const clipId of this.pagedClipProviders.keys()) {
+      this.removePagedClipProvider(clipId);
     }
-    Atomics.store(ring.header, 0, writeIndex + 1);
-    // Like writeMeterRing, writeIndex is a free-running monotonic counter; the
-    // reader detects silent overrun via firstReadable, so the overflow slot
-    // (header[5]) stays at its initial 0.
   }
 
   private commandRingFromSharedBuffer(