@libraz/libsonare 1.5.5 → 1.7.0

package/src/worker_protocol.ts

@@ -0,0 +1,59 @@
+/**
+ * Internal structured-clone protocol for the offline Web Worker bridge.
+ *
+ * Keep this deliberately limited to one-shot operations. Embind handles own
+ * native resources and cannot safely cross a worker boundary.
+ */
+
+export type OfflineWorkerOperation =
+  | 'analyze'
+  | 'detectBpm'
+  | 'detectKey'
+  | 'detectChords'
+  | 'masterAudio'
+  | 'masterAudioStereo';
+
+export interface OfflineWorkerRunMessage {
+  type: 'sonare:offline-run';
+  id: number;
+  operation: OfflineWorkerOperation;
+  request: Record<string, unknown>;
+  /** A shared flag lets cancellation reach synchronous WASM progress callbacks. */
+  cancelBuffer?: SharedArrayBuffer;
+}
+
+export interface OfflineWorkerCancelMessage {
+  type: 'sonare:offline-cancel';
+  id: number;
+}
+
+export type OfflineWorkerRequestMessage = OfflineWorkerRunMessage | OfflineWorkerCancelMessage;
+
+export interface OfflineWorkerProgressMessage {
+  type: 'sonare:offline-progress';
+  id: number;
+  progress: number;
+  stage: string;
+}
+
+export interface OfflineWorkerResultMessage {
+  type: 'sonare:offline-result';
+  id: number;
+  result: unknown;
+}
+
+export interface OfflineWorkerErrorMessage {
+  type: 'sonare:offline-error';
+  id: number;
+  error: {
+    name: string;
+    message: string;
+    code?: number;
+    codeName?: string;
+  };
+}
+
+export type OfflineWorkerResponseMessage =
+  | OfflineWorkerProgressMessage
+  | OfflineWorkerResultMessage
+  | OfflineWorkerErrorMessage;

package/src/worklet/engine-automation.ts

@@ -31,7 +31,8 @@ export function scheduleParam(
   // Mirror the lane to the live worklet engine so scheduled automation plays
   // back in real time, not just in renderOffline(). Lanes can exceed the
   // fixed-size SAB command record, so they ride an out-of-band 'syncAutomation'
-  // message applied outside process() (like syncClips/syncMarkers).
+  // message whose port handler publishes the bounded snapshot consumed by
+  // process() (like syncClips/syncMarkers).
   ctx.postSync({ type: 'syncAutomation', paramId, points: lane });
 }
 

package/src/worklet/engine-capture-facade.ts

@@ -15,11 +15,17 @@ type CaptureConfig = Omit<SonareEngineSyncCaptureMessage, 'type'>;
 export interface EngineCaptureContext {
   readonly offlineEngine: RealtimeEngine;
   readonly realtimeNode: SonareRealtimeEngineNode;
+  sendCommand(command: {
+    type: SonareEngineCommandType;
+    targetId?: number;
+    sampleTime?: number;
+    argFloat?: number;
+    argInt?: number;
+  }): boolean;
   readonly offlineChannelCount: number;
   postSync(message: SonareEngineSyncMessage): void;
   getCaptureConfig(): CaptureConfig | undefined;
   setCaptureConfig(config: CaptureConfig): void;
-  resolveTargetId(target: string | number): number;
 }
 
 export function configureCapture(ctx: EngineCaptureContext, options: CaptureOptions): void {
@@ -37,13 +43,16 @@ export function armRecord(
   trackId: string | number,
   enabled: boolean,
 ): boolean {
+  if (trackId !== 0) {
+    throw new RangeError('Capture is global; armRecord only accepts trackId 0');
+  }
   if (enabled && !ctx.getCaptureConfig()) {
     throw new Error('Capture buffer is not configured');
   }
   ctx.offlineEngine.armCapture(enabled);
-  return ctx.realtimeNode.sendCommand({
+  return ctx.sendCommand({
     type: SonareEngineCommandType.ArmRecord,
-    targetId: ctx.resolveTargetId(trackId),
+    targetId: 0,
     sampleTime: -1,
     argInt: enabled ? 1 : 0,
   });
@@ -58,7 +67,7 @@ export function punch(ctx: EngineCaptureContext, inPpq: number, outPpq: number):
   // point and let the consumer multiply by sampleRate (treating PPQ as
   // seconds), which ignored tempo and produced a punch-out ~2x too large at
   // 120 BPM. argInt = in sample, argFloat = out sample (full-precision double).
-  return ctx.realtimeNode.sendCommand({
+  return ctx.sendCommand({
     type: SonareEngineCommandType.Punch,
     sampleTime: -1,
     argInt: inSample,

package/src/worklet/engine-clips.ts

@@ -1,4 +1,5 @@
 import type { EngineClip, EngineMidiClipSchedule, RealtimeEngine } from '../index';
+import type { ClipPageProvider } from '../realtime_engine';
 import type { SonareEngineSyncMessage } from './messages';
 
 /**
@@ -14,6 +15,8 @@ export interface EngineClipContext {
   postSync(message: SonareEngineSyncMessage, transfer?: Transferable[]): void;
   resolveTargetId(target: string | number): number;
   ensureTrackLane(target: string | number): number;
+  /** Commits a provider already primed through the worklet's OPFS pull bridge. */
+  commitWorkletClipPageProvider(clip: EngineClip): boolean;
 }
 
 // Keep control-message work bounded even for long tempo-synced clips. The
@@ -25,15 +28,15 @@ const PREBAKED_CLIP_PAGE_FRAMES = 4_096;
 export function addClip(
   ctx: EngineClipContext,
   trackId: string | number,
-  buffer: Float32Array[],
+  buffer: Float32Array[] | ClipPageProvider,
   startPpq: number,
-  opts: Partial<Omit<EngineClip, 'channels' | 'startPpq'>> = {},
+  opts: Partial<Omit<EngineClip, 'channels' | 'pageProvider' | 'startPpq'>> = {},
 ): number {
   const id = opts.id ?? ctx.allocateClipId();
   const clip: EngineClip = {
     ...opts,
     id,
-    channels: buffer,
+    ...(Array.isArray(buffer) ? { channels: buffer } : { pageProvider: buffer }),
     startPpq,
     trackId: ctx.resolveTargetId(trackId),
   };
@@ -88,6 +91,12 @@ function syncClipsDelta(ctx: EngineClipContext, upserts: EngineClip[], removeIds
   for (const clip of upserts) {
     const prepared = clip.id === undefined ? clip : (preparedById.get(clip.id) ?? clip);
     const channels = prepared.channels;
+    if (!channels && prepared.pageProvider !== undefined) {
+      if (ctx.commitWorkletClipPageProvider(prepared)) {
+        continue;
+      }
+      throw new Error('A pageProvider on SonareEngine must be created by attachOpfsClipStream().');
+    }
     if (
       prepared.id === undefined ||
       prepared.warpMode !== 'off' ||

package/src/worklet/engine-node.ts

@@ -1,6 +1,9 @@
 import type { EngineCaptureStatus, EngineTransportState } from '../index';
 import { engineCapabilities } from '../index';
 import {
+  engineCaptureResponseRequestId,
+  isClipPageRequestMessage,
+  isEngineCaptureResponseForOperation,
   isEngineCaptureResponseMessage,
   isEngineTelemetryRecord,
   isEngineTransportResponseMessage,
@@ -9,7 +12,9 @@ import {
 } from './guards';
 import type {
   SonareEngineCaptureRequestMessage,
-  SonareEngineCaptureResponseMessage,
+  SonareEngineCaptureResponseMessageInternal,
+  SonareEngineClipPageRequestMessage,
+  SonareEngineSyncErrorMessage,
   SonareEngineTransportResponseMessage,
   SonareRealtimeEngineNodeCapabilities,
   SonareRealtimeEngineNodeOptions,
@@ -17,26 +22,86 @@ import type {
   SonareWorkletExternalMidiEvent,
 } from './messages';
 import {
+  createSonareClipPageRequestRingBuffer,
   createSonareEngineCommandRingBuffer,
   createSonareEngineTelemetryRingBuffer,
+  createSonareExternalMidiRingBuffer,
   createSonareMeterRingBuffer,
   createSonareScopeRingBuffer,
   isRecord,
   pushSonareEngineCommandRingBuffer,
+  readSonareClipPageRequestRingBuffer,
   readSonareEngineTelemetryRingBuffer,
+  readSonareExternalMidiRingBuffer,
   readSonareMeterRingBuffer,
   readSonareScopeRingBuffer,
+  type SonareClipPageRequestRingBuffer,
   type SonareEngineCommandRecord,
   type SonareEngineCommandRingBuffer,
   SonareEngineCommandType,
   type SonareEngineTelemetryRecord,
   type SonareEngineTelemetryRingBuffer,
+  type SonareExternalMidiRingBuffer,
   type SonareMeterRingBuffer,
   type SonareScopeRingBuffer,
   type SonareWorkletMeterSnapshot,
   type SonareWorkletScopeSnapshot,
 } from './protocol';
 
+function isFiniteInteger(value: number | bigint | undefined): boolean {
+  if (value === undefined) {
+    return true;
+  }
+  return typeof value === 'bigint' || (Number.isFinite(value) && Number.isSafeInteger(value));
+}
+
+function isTrackMonitorMode(value: number | bigint | undefined): boolean {
+  if (value === undefined) {
+    return false;
+  }
+  const mode = typeof value === 'bigint' ? Number(value) : value;
+  return typeof mode === 'number' && Number.isSafeInteger(mode) && mode >= 0 && mode <= 2;
+}
+
+/** A track-monitor command cannot infer a lane: its target is a uint32 index. */
+function isTrackMonitorLaneIndex(value: number | undefined): boolean {
+  return (
+    typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= 0xffff_ffff
+  );
+}
+
+function isValidCommandRecord(command: SonareEngineCommandRecord): boolean {
+  const type = Number(command.type);
+  if (
+    !Number.isSafeInteger(type) ||
+    type < SonareEngineCommandType.SetParam ||
+    (type > SonareEngineCommandType.SeekMarker &&
+      type !== SonareEngineCommandType.SetTrackMonitorMode)
+  ) {
+    return false;
+  }
+  return (
+    (command.targetId === undefined || Number.isSafeInteger(command.targetId)) &&
+    (command.argFloat === undefined || Number.isFinite(command.argFloat)) &&
+    isFiniteInteger(command.argInt) &&
+    isFiniteInteger(command.sampleTime) &&
+    (type !== SonareEngineCommandType.SetTrackMonitorMode ||
+      (isTrackMonitorLaneIndex(command.targetId) && isTrackMonitorMode(command.argInt)))
+  );
+}
+
+const AUDIO_WORKLET_RENDER_QUANTUM = 128;
+
+function workletBlockSize(blockSize: number | undefined): number {
+  const resolved = blockSize ?? AUDIO_WORKLET_RENDER_QUANTUM;
+  if (!Number.isSafeInteger(resolved) || resolved < AUDIO_WORKLET_RENDER_QUANTUM) {
+    throw new RangeError(
+      `blockSize must be an integer of at least ${AUDIO_WORKLET_RENDER_QUANTUM} frames`,
+    );
+  }
+  return resolved;
+}
+
 export class SonareRealtimeEngineNode {
   readonly node: AudioWorkletNode;
   readonly capabilities: SonareRealtimeEngineNodeCapabilities;
@@ -44,19 +109,28 @@ export class SonareRealtimeEngineNode {
   readonly telemetryRing?: SonareEngineTelemetryRingBuffer;
   readonly meterRing?: SonareMeterRingBuffer;
   readonly scopeRing?: SonareScopeRingBuffer;
+  readonly clipPageRequestRing?: SonareClipPageRequestRingBuffer;
+  readonly externalMidiRing?: SonareExternalMidiRingBuffer;
   readonly ready: Promise<void>;
   private telemetryReadIndex = 0;
   private meterReadIndex = 0;
   private scopeReadIndex = 0;
+  private clipPageRequestDroppedRead = 0;
+  private ringPollTimer: ReturnType<typeof setInterval> | undefined;
   private telemetryListeners = new Set<(telemetry: SonareEngineTelemetryRecord) => void>();
   private meterListeners = new Set<(meter: SonareWorkletMeterSnapshot) => void>();
   private scopeListeners = new Set<(scope: SonareWorkletScopeSnapshot) => void>();
   private midiOutListeners = new Set<(events: SonareWorkletExternalMidiEvent[]) => void>();
+  private clipPageRequestListeners = new Set<
+    (message: SonareEngineClipPageRequestMessage) => void
+  >();
+  private syncErrorListeners = new Set<(message: SonareEngineSyncErrorMessage) => void>();
   private captureRequestId = 1;
   private readonly captureRequests = new Map<
     number,
     {
-      resolve: (response: SonareEngineCaptureResponseMessage) => void;
+      op: SonareEngineCaptureRequestMessage['op'];
+      resolve: (response: SonareEngineCaptureResponseMessageInternal) => void;
       reject: (reason?: unknown) => void;
     }
   >();
@@ -79,6 +153,8 @@ export class SonareRealtimeEngineNode {
     telemetryRing?: SonareEngineTelemetryRingBuffer,
     meterRing?: SonareMeterRingBuffer,
     scopeRing?: SonareScopeRingBuffer,
+    clipPageRequestRing?: SonareClipPageRequestRingBuffer,
+    externalMidiRing?: SonareExternalMidiRingBuffer,
   ) {
     this.node = node;
     this.capabilities = capabilities;
@@ -86,6 +162,8 @@ export class SonareRealtimeEngineNode {
     this.telemetryRing = telemetryRing;
     this.meterRing = meterRing;
     this.scopeRing = scopeRing;
+    this.clipPageRequestRing = clipPageRequestRing;
+    this.externalMidiRing = externalMidiRing;
     this.ready = new Promise((resolve, reject) => {
       this.resolveReady = resolve;
       this.rejectReady = reject;
@@ -94,14 +172,19 @@ export class SonareRealtimeEngineNode {
       this.resolveReady();
     }
     this.node.port.onmessage = (event: MessageEvent<unknown>) => {
-      if (isEngineCaptureResponseMessage(event.data)) {
-        const pending = this.captureRequests.get(event.data.requestId);
+      const captureRequestId = engineCaptureResponseRequestId(event.data);
+      if (captureRequestId !== undefined) {
+        const pending = this.captureRequests.get(captureRequestId);
         if (pending) {
-          this.captureRequests.delete(event.data.requestId);
-          if (event.data.ok) {
+          this.captureRequests.delete(captureRequestId);
+          if (!isEngineCaptureResponseMessage(event.data)) {
+            pending.reject(new Error('Malformed capture response.'));
+          } else if (!isEngineCaptureResponseForOperation(event.data, pending.op)) {
+            pending.reject(new Error('Capture response does not match request operation.'));
+          } else if (event.data.ok) {
             pending.resolve(event.data);
           } else {
-            pending.reject(new Error(event.data.error ?? 'Capture request failed'));
+            pending.reject(new Error(event.data.error));
           }
         }
       } else if (isEngineTransportResponseMessage(event.data)) {
@@ -120,6 +203,17 @@ export class SonareRealtimeEngineNode {
         this.emitMeter(event.data);
       } else if (isExternalMidiBatchMessage(event.data)) {
         this.emitMidiOut(event.data.events);
+      } else if (isClipPageRequestMessage(event.data)) {
+        this.emitClipPageRequests(event.data);
+      } else if (isRecord(event.data) && event.data.type === 'syncError') {
+        const syncError: SonareEngineSyncErrorMessage = {
+          type: 'syncError',
+          syncType: String(event.data.syncType) as SonareEngineSyncErrorMessage['syncType'],
+          message: String(event.data.message ?? 'AudioWorklet sync failed'),
+        };
+        for (const listener of this.syncErrorListeners) {
+          listener(syncError);
+        }
       } else if (isRecord(event.data) && event.data.type === 'ready') {
         this.resolveReady();
       } else if (isRecord(event.data) && event.data.type === 'error') {
@@ -128,10 +222,17 @@ export class SonareRealtimeEngineNode {
     };
   }
 
+  /** Subscribes to control-plane sync rejections reported by the worklet. */
+  onSyncError(listener: (message: SonareEngineSyncErrorMessage) => void): () => void {
+    this.syncErrorListeners.add(listener);
+    return () => this.syncErrorListeners.delete(listener);
+  }
+
   static async create(
     context: BaseAudioContext,
     options: SonareRealtimeEngineNodeOptions = {},
   ): Promise<SonareRealtimeEngineNode> {
+    const blockSize = workletBlockSize(options.blockSize);
     const processorName = options.processorName ?? 'sonare-realtime-engine-processor';
     const moduleUrl = options.moduleUrl;
     if (moduleUrl && context.audioWorklet?.addModule) {
@@ -188,10 +289,21 @@ export class SonareRealtimeEngineNode {
       mode === 'sab' && scopeIntervalFrames > 0
         ? createSonareScopeRingBuffer(options.scopeRingCapacity ?? 64, options.scopeBands ?? 48)
         : undefined;
+    // Paged-clip cache misses are a worklet-to-main-thread control signal. A
+    // dedicated SPSC SAB ring keeps process() free of both embind request
+    // objects and postMessage structured cloning.
+    const clipPageRequestRing =
+      mode === 'sab'
+        ? createSonareClipPageRequestRingBuffer(options.clipPageRequestRingCapacity ?? 128)
+        : undefined;
+    const externalMidiRing =
+      mode === 'sab'
+        ? createSonareExternalMidiRingBuffer(options.externalMidiRingCapacity ?? 256)
+        : undefined;
     const channelCount = Math.max(1, Math.floor(options.channelCount ?? 2));
     const processorOptions: SonareRealtimeEngineWorkletProcessorOptions = {
       sampleRate: options.sampleRate ?? context.sampleRate,
-      blockSize: options.blockSize,
+      blockSize,
       channelCount,
       commandSharedBuffer: commandRing?.sharedBuffer,
       commandRingCapacity: commandRing?.capacity,
@@ -203,6 +315,10 @@ export class SonareRealtimeEngineNode {
       scopeRingCapacity: scopeRing?.capacity,
       scopeBands: scopeRing?.bands,
       scopeIntervalFrames: scopeRing ? scopeIntervalFrames : undefined,
+      clipPageRequestSharedBuffer: clipPageRequestRing?.sharedBuffer,
+      clipPageRequestRingCapacity: clipPageRequestRing?.capacity,
+      externalMidiSharedBuffer: externalMidiRing?.sharedBuffer,
+      externalMidiRingCapacity: externalMidiRing?.capacity,
       wasmBinary: options.wasmBinary,
       initialSyncMessages: options.initialSyncMessages,
       initialCommands: options.initialCommands,
@@ -225,16 +341,23 @@ export class SonareRealtimeEngineNode {
         sharedArrayBuffer,
         atomics,
         audioWorklet,
+        clipPageRequestsRealtimeSafe: mode === 'sab',
+        externalMidiRealtimeSafe: mode === 'sab',
         engineAbiVersion: detectedCapabilities?.engineAbiVersion,
         expectedEngineAbiVersion: detectedCapabilities?.expectedEngineAbiVersion,
         abiCompatible: detectedCapabilities?.abiCompatible,
         degradedReason,
-        readyMessage: moduleUrl !== undefined && !options.nodeFactory,
+        // A processor posts ready/error irrespective of whether its module was
+        // loaded here or registered by the host beforehand. Waiting in both
+        // cases is the only way to surface a failed worklet-side WASM init.
+        readyMessage: true,
       },
       commandRing,
       telemetryRing,
       meterRing,
       scopeRing,
+      clipPageRequestRing,
+      externalMidiRing,
     );
   }
 
@@ -255,6 +378,9 @@ export class SonareRealtimeEngineNode {
   }
 
   seekPpq(ppq: number, sampleTime = -1): boolean {
+    if (!Number.isFinite(ppq) || !Number.isSafeInteger(sampleTime)) {
+      return false;
+    }
     return this.sendCommand({
       type: SonareEngineCommandType.TransportSeekPpq,
       sampleTime,
@@ -263,7 +389,7 @@ export class SonareRealtimeEngineNode {
   }
 
   sendCommand(command: SonareEngineCommandRecord): boolean {
-    if (this.destroyed) {
+    if (this.destroyed || !isValidCommandRecord(command)) {
       return false;
     }
     if (this.commandRing) {
@@ -275,7 +401,7 @@ export class SonareRealtimeEngineNode {
 
   requestCaptureStatus(): Promise<EngineCaptureStatus> {
     return this.sendCaptureRequest('status').then((response) => {
-      if (!response.status) {
+      if (!response.ok || !('status' in response)) {
         throw new Error('Capture status response is missing status.');
       }
       return response.status;
@@ -283,11 +409,12 @@ export class SonareRealtimeEngineNode {
   }
 
   requestCapturedAudio(): Promise<Float32Array[]> {
-    return this.sendCaptureRequest('read').then((response) =>
-      (response.channels ?? []).map((channel) =>
-        channel instanceof Float32Array ? channel : new Float32Array(channel),
-      ),
-    );
+    return this.sendCaptureRequest('read').then((response) => {
+      if (!response.ok || !('channels' in response)) {
+        throw new Error('Capture read response is missing channels.');
+      }
+      return response.channels;
+    });
   }
 
   requestCaptureReset(): Promise<void> {
@@ -345,24 +472,77 @@ export class SonareRealtimeEngineNode {
     return read.scopes;
   }
 
+  /** Drain lowered MIDI-1 records from the SAB ring on the main thread. */
+  pollMidiOut(): SonareWorkletExternalMidiEvent[] {
+    if (!this.externalMidiRing) {
+      return [];
+    }
+    const read = readSonareExternalMidiRingBuffer(this.externalMidiRing);
+    const events = read.events.map((event) => {
+      const bytes: number[] = [];
+      for (let index = 0; index < event.byteCount; index++) {
+        bytes.push((event.byteWord >>> (8 * index)) & 0xff);
+      }
+      return {
+        destinationId: event.destinationId,
+        renderFrame: event.renderFrame,
+        bytes,
+      };
+    });
+    if (events.length > 0) {
+      this.emitMidiOut(events);
+    }
+    return events;
+  }
+
+  /**
+   * Drains bounded paged-clip misses from the SAB ring and forwards one batch
+   * to subscribers. In postMessage mode the legacy handler remains available,
+   * but that degraded path is not realtime-safe for OPFS streaming.
+   */
+  pollClipPageRequests(): SonareEngineClipPageRequestMessage | undefined {
+    if (!this.clipPageRequestRing) {
+      return undefined;
+    }
+    const read = readSonareClipPageRequestRingBuffer(this.clipPageRequestRing);
+    const dropped = (read.dropped - this.clipPageRequestDroppedRead) >>> 0;
+    this.clipPageRequestDroppedRead = read.dropped;
+    if (read.requests.length === 0 && dropped === 0) {
+      return undefined;
+    }
+    const message: SonareEngineClipPageRequestMessage = {
+      type: 'clipPageRequest',
+      requests: read.requests,
+      ...(dropped > 0 ? { dropped } : {}),
+    };
+    this.emitClipPageRequests(message);
+    return message;
+  }
+
   onTelemetry(callback: (telemetry: SonareEngineTelemetryRecord) => void): () => void {
     this.telemetryListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.telemetryListeners.delete(callback);
+      this.stopRingPollingIfUnused();
     };
   }
 
   onMeter(callback: (meter: SonareWorkletMeterSnapshot) => void): () => void {
     this.meterListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.meterListeners.delete(callback);
+      this.stopRingPollingIfUnused();
     };
   }
 
   onScope(callback: (scope: SonareWorkletScopeSnapshot) => void): () => void {
     this.scopeListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.scopeListeners.delete(callback);
+      this.stopRingPollingIfUnused();
     };
   }
 
@@ -373,8 +553,21 @@ export class SonareRealtimeEngineNode {
    */
   onMidiOut(callback: (events: SonareWorkletExternalMidiEvent[]) => void): () => void {
     this.midiOutListeners.add(callback);
+    this.startRingPolling();
     return () => {
       this.midiOutListeners.delete(callback);
+      this.stopRingPollingIfUnused();
+    };
+  }
+
+  /**
+   * Subscribe to bounded batches of paged-clip misses from the worklet. The
+   * callback runs on the main thread and may initiate asynchronous OPFS I/O.
+   */
+  onClipPageRequests(callback: (message: SonareEngineClipPageRequestMessage) => void): () => void {
+    this.clipPageRequestListeners.add(callback);
+    return () => {
+      this.clipPageRequestListeners.delete(callback);
     };
   }
 
@@ -383,7 +576,11 @@ export class SonareRealtimeEngineNode {
       return;
     }
     this.destroyed = true;
-    this.node.port.postMessage({ type: SonareEngineCommandType.TransportStop, sampleTime: -1 });
+    if (this.ringPollTimer !== undefined) {
+      clearInterval(this.ringPollTimer);
+      this.ringPollTimer = undefined;
+    }
+    this.node.port.postMessage({ type: 'destroy' });
     this.node.disconnect();
     for (const pending of this.captureRequests.values()) {
       pending.reject(new Error('Realtime engine node is destroyed.'));
@@ -397,6 +594,7 @@ export class SonareRealtimeEngineNode {
     this.meterListeners.clear();
     this.scopeListeners.clear();
     this.midiOutListeners.clear();
+    this.clipPageRequestListeners.clear();
   }
 
   private emitTelemetry(telemetry: SonareEngineTelemetryRecord): void {
@@ -405,6 +603,38 @@ export class SonareRealtimeEngineNode {
     }
   }
 
+  private startRingPolling(): void {
+    if (
+      this.ringPollTimer !== undefined ||
+      (!this.telemetryRing && !this.meterRing && !this.scopeRing && !this.externalMidiRing)
+    ) {
+      return;
+    }
+    const poll = () => {
+      if (!this.destroyed) {
+        this.pollTelemetry();
+        this.pollMeters();
+        this.pollScope();
+        this.pollMidiOut();
+      }
+    };
+    poll();
+    this.ringPollTimer = setInterval(poll, 16);
+  }
+
+  private stopRingPollingIfUnused(): void {
+    if (
+      this.ringPollTimer !== undefined &&
+      this.telemetryListeners.size === 0 &&
+      this.meterListeners.size === 0 &&
+      this.scopeListeners.size === 0 &&
+      this.midiOutListeners.size === 0
+    ) {
+      clearInterval(this.ringPollTimer);
+      this.ringPollTimer = undefined;
+    }
+  }
+
   private emitMeter(meter: SonareWorkletMeterSnapshot): void {
     for (const listener of this.meterListeners) {
       listener(meter);
@@ -417,6 +647,12 @@ export class SonareRealtimeEngineNode {
     }
   }
 
+  private emitClipPageRequests(message: SonareEngineClipPageRequestMessage): void {
+    for (const listener of this.clipPageRequestListeners) {
+      listener(message);
+    }
+  }
+
   private emitScope(scope: SonareWorkletScopeSnapshot): void {
     for (const listener of this.scopeListeners) {
       listener(scope);
@@ -425,15 +661,22 @@ export class SonareRealtimeEngineNode {
 
   private sendCaptureRequest(
     op: SonareEngineCaptureRequestMessage['op'],
-  ): Promise<SonareEngineCaptureResponseMessage> {
+  ): Promise<SonareEngineCaptureResponseMessageInternal> {
     if (this.destroyed) {
       return Promise.reject(new Error('Realtime engine node is destroyed.'));
     }
     const requestId = this.captureRequestId++;
-    const promise = new Promise<SonareEngineCaptureResponseMessage>((resolve, reject) => {
-      this.captureRequests.set(requestId, { resolve, reject });
+    let rejectRequest!: (reason?: unknown) => void;
+    const promise = new Promise<SonareEngineCaptureResponseMessageInternal>((resolve, reject) => {
+      rejectRequest = reject;
+      this.captureRequests.set(requestId, { op, resolve, reject });
     });
-    this.node.port.postMessage({ type: 'captureRequest', requestId, op });
+    try {
+      this.node.port.postMessage({ type: 'captureRequest', requestId, op });
+    } catch (error) {
+      this.captureRequests.delete(requestId);
+      rejectRequest(error);
+    }
     return promise;
   }