@libraz/libsonare 1.5.4 → 1.6.0

package/src/worklet/messages.ts

@@ -6,11 +6,13 @@ import type {
   EngineMarker,
   EngineMetronomeConfig,
   EngineMidiClipSchedule,
+  EngineParameterInfo,
   EngineTempoSegment,
   EngineTimeSignatureSegment,
   EngineTrackLane,
   EngineTransportState,
   RealtimeVoiceChangerConfigInput,
+  RealtimeVoiceChangerPodConfig,
 } from '../index';
 import type { AutomationCurve } from '../public_types';
 import type {
@@ -55,6 +57,16 @@ export interface SonareRealtimeEngineWorkletProcessorOptions {
   scopeBands?: number;
   scopeSharedBuffer?: SharedArrayBuffer;
   scopeRingCapacity?: number;
+  /**
+   * Lock-free SPSC queue for clip-page cache misses. Supplying this is required
+   * for realtime-safe OPFS streaming: it avoids both embind object creation and
+   * postMessage structured cloning from AudioWorklet process().
+   */
+  clipPageRequestSharedBuffer?: SharedArrayBuffer;
+  clipPageRequestRingCapacity?: number;
+  /** Lock-free worklet-to-main-thread MIDI-1 output ring. */
+  externalMidiSharedBuffer?: SharedArrayBuffer;
+  externalMidiRingCapacity?: number;
 }
 
 export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
@@ -66,7 +78,8 @@ export interface SonareRealtimeVoiceChangerWorkletProcessorOptions {
 
 export interface SonareRealtimeVoiceChangerSetConfigMessage {
   type: 'setConfig';
-  preset: RealtimeVoiceChangerConfigInput;
+  /** Pre-normalized by the main thread; never JSON parsed in the worklet. */
+  config: RealtimeVoiceChangerPodConfig;
 }
 
 export interface SonareRealtimeVoiceChangerResetMessage {
@@ -88,6 +101,10 @@ export interface SonareRealtimeEngineNodeCapabilities {
   sharedArrayBuffer: boolean;
   atomics: boolean;
   audioWorklet: boolean;
+  /** True only when clip-page misses use the bounded SAB ring. */
+  clipPageRequestsRealtimeSafe: boolean;
+  /** True when external MIDI uses the SAB output ring rather than postMessage. */
+  externalMidiRealtimeSafe: boolean;
   engineAbiVersion?: number;
   expectedEngineAbiVersion?: number;
   abiCompatible?: boolean;
@@ -161,10 +178,18 @@ export interface SonareWorkletExternalMidiMessage {
   events: SonareWorkletExternalMidiEvent[];
 }
 
+/** A control-plane sync message that the worklet rejected without crashing. */
+export interface SonareEngineSyncErrorMessage {
+  type: 'syncError';
+  syncType: SonareEngineSyncMessage['type'];
+  message: string;
+}
+
 export type SonareWorkletTransportMessage =
   | SonareWorkletMeterSnapshot
   | SonareWorkletSpectrumSnapshot
   | SonareWorkletExternalMidiMessage
+  | SonareEngineClipPageRequestMessage
   | SonareEngineTelemetryRecord;
 
 export interface WorkletTransport {
@@ -172,7 +197,8 @@ export interface WorkletTransport {
     message:
       | SonareWorkletTransportMessage
       | SonareEngineCaptureResponseMessage
-      | SonareEngineTransportResponseMessage,
+      | SonareEngineTransportResponseMessage
+      | SonareEngineSyncErrorMessage,
     transfer?: Transferable[],
   ) => void;
   onMeter?: (meter: SonareWorkletMeterSnapshot) => void;
@@ -183,6 +209,7 @@ export interface ResolvedMetronomeConfig {
   beatGain: number;
   accentGain: number;
   clickSamples: number;
+  clickSeconds: number;
 }
 
 // Fallback metronome gains/click length used by the worklet consumer until the
@@ -191,23 +218,42 @@ export interface ResolvedMetronomeConfig {
 export const DEFAULT_METRONOME_CONFIG: ResolvedMetronomeConfig = {
   beatGain: 0.35,
   accentGain: 0.7,
-  clickSamples: 96,
+  clickSamples: 0,
+  clickSeconds: 0,
 };
 
 export function resolveMetronomeConfig(config: EngineMetronomeConfig): ResolvedMetronomeConfig {
-  return {
+  const resolved = {
     beatGain: config.beatGain ?? DEFAULT_METRONOME_CONFIG.beatGain,
     accentGain: config.accentGain ?? DEFAULT_METRONOME_CONFIG.accentGain,
     clickSamples: config.clickSamples ?? DEFAULT_METRONOME_CONFIG.clickSamples,
+    clickSeconds: config.clickSeconds ?? DEFAULT_METRONOME_CONFIG.clickSeconds,
   };
+  if (
+    !Number.isFinite(resolved.beatGain) ||
+    resolved.beatGain < 0 ||
+    !Number.isFinite(resolved.accentGain) ||
+    resolved.accentGain < 0 ||
+    !Number.isInteger(resolved.clickSamples) ||
+    resolved.clickSamples < 0 ||
+    !Number.isFinite(resolved.clickSeconds) ||
+    resolved.clickSeconds < 0 ||
+    resolved.clickSamples > 384000 ||
+    (config.clickSeconds !== undefined &&
+      (!Number.isFinite(config.clickSeconds) || config.clickSeconds < 0 || config.clickSeconds > 1))
+  ) {
+    throw new RangeError('invalid metronome gains or click length');
+  }
+  return resolved;
 }
 
 // Out-of-band control messages posted from the main-thread SonareEngine facade
 // to the worklet engine processor over node.port. Unlike SonareEngineCommandRecord
 // (a small POD POSTed/ringed every block) these carry bulk/structured payloads
 // (clip audio buffers, marker lists, metronome config) that cannot fit the
-// fixed-size SAB command record, so they are applied OUTSIDE process() — the
-// audio-thread equivalent of the engine's control-thread RtPublisher setters.
+// fixed-size SAB command record. Their port handlers still execute on the
+// AudioWorklet rendering thread, so consumers must validate them without
+// allocation and publish bounded snapshots for process() to consume.
 export interface SonareEngineSyncClipsMessage {
   type: 'syncClips';
   clips: EngineClip[];
@@ -223,7 +269,8 @@ export interface SonareEngineSyncClipsDeltaMessage {
 export interface SonareEngineSyncClipPageProviderMessage {
   type: 'syncClipPageProvider';
   clipId: number;
-  clip: EngineClip;
+  /** Omitted when an OPFS stream is primed before its clip is scheduled. */
+  clip?: EngineClip;
   numChannels: number;
   numSamples: number;
   pageFrames: number;
@@ -237,10 +284,41 @@ export interface SonareEngineSyncClipPageMessage {
   channels: Float32Array[];
 }
 
+/** Evicts one page after the main-thread sliding window advances. */
+export interface SonareEngineSyncClipPageClearMessage {
+  type: 'syncClipPageClear';
+  clipId: number;
+  pageIndex: number;
+}
+
+/** Releases a provider whose clip was removed or whose stream was closed. */
+export interface SonareEngineSyncClipPageDestroyMessage {
+  type: 'syncClipPageDestroy';
+  clipId: number;
+}
+
 /** Makes a fully supplied paged clip visible to the audio engine. */
 export interface SonareEngineSyncClipPageCommitMessage {
   type: 'syncClipPageCommit';
   clipId: number;
+  /**
+   * Clip schedule to publish with a provider that was primed before its
+   * schedule was known. The original pre-baked push path supplies it on the
+   * provider message instead.
+   */
+  clip?: EngineClip;
+}
+
+/**
+ * A bounded batch of page misses emitted by the AudioWorklet. The main thread
+ * resolves these from OPFS and responds with `syncClipPage`; a missing page is
+ * silent until that response arrives.
+ */
+export interface SonareEngineClipPageRequestMessage {
+  type: 'clipPageRequest';
+  requests: Array<{ clipId: number; pageIndex: number }>;
+  /** Number of misses dropped because a bounded native or SAB request queue was full. */
+  dropped?: number;
 }
 
 export interface SonareEngineSyncMidiClipsMessage {
@@ -264,6 +342,12 @@ export interface SonareEngineSyncAutomationMessage {
   points: EngineAutomationPoint[];
 }
 
+/** Replaces the live engine's registered custom-parameter set. */
+export interface SonareEngineSyncParametersMessage {
+  type: 'syncParameters';
+  parameters: EngineParameterInfo[];
+}
+
 export interface SonareEngineSyncTempoMessage {
   type: 'syncTempo';
   bpm: number;
@@ -389,7 +473,12 @@ export interface SonareEngineSyncSynthInstrumentMessage {
 export interface SonareEngineSyncSf2InstrumentMessage {
   type: 'syncSf2Instrument';
   destinationId: number;
-  config: { destinationId?: number; gain?: number; polyphony?: number };
+  config: {
+    destinationId?: number;
+    gain?: number;
+    polyphony?: number;
+    preferModelForModeledFamilies?: boolean;
+  };
 }
 
 export interface SonareEngineSyncLoadSoundFontMessage {
@@ -424,6 +513,13 @@ export interface SonareEngineSyncMidiCcMessage {
   renderFrame: number;
 }
 
+export interface SonareEngineSyncMidiUmpMessage {
+  type: 'syncMidiUmp';
+  destinationId: number;
+  word0: number;
+  renderFrame: number;
+}
+
 export interface SonareEngineSyncMidiSysexMessage {
   type: 'syncMidiSysex';
   destinationId: number;
@@ -447,6 +543,34 @@ export interface SonareEngineSyncExternalMidiClockMessage {
   enabled: boolean;
 }
 
+export interface SonareEngineSyncMidiInputSourceMessage {
+  type: 'syncMidiInputSource' | 'syncClearMidiInputSource';
+  destinationId?: number;
+}
+
+export interface SonareEngineSyncMidiCcBindingMessage {
+  type: 'syncMidiCcBinding';
+  channel: number;
+  controller: number;
+  paramId: number;
+  minValue: number;
+  maxValue: number;
+}
+
+export interface SonareEngineSyncMidiInputEventMessage {
+  type: 'syncMidiInputNoteOn' | 'syncMidiInputNoteOff' | 'syncMidiInputCc';
+  group: number;
+  channel: number;
+  data0: number;
+  data1: number;
+  portTimeSamples: number;
+}
+
+/** Releases the realtime engine and all worklet-owned clip buffers. */
+export interface SonareEngineDestroyMessage {
+  type: 'destroy';
+}
+
 export type SonareEngineInstrumentSyncMessage =
   | SonareEngineSyncBuiltinInstrumentMessage
   | SonareEngineSyncSynthInstrumentMessage
@@ -459,11 +583,14 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncClipsDeltaMessage
   | SonareEngineSyncClipPageProviderMessage
   | SonareEngineSyncClipPageMessage
+  | SonareEngineSyncClipPageClearMessage
   | SonareEngineSyncClipPageCommitMessage
+  | SonareEngineSyncClipPageDestroyMessage
   | SonareEngineSyncMidiClipsMessage
   | SonareEngineSyncMarkersMessage
   | SonareEngineSyncMetronomeMessage
   | SonareEngineSyncAutomationMessage
+  | SonareEngineSyncParametersMessage
   | SonareEngineSyncTempoMessage
   | SonareEngineSyncMixerMessage
   | SonareEngineSyncCaptureMessage
@@ -486,10 +613,15 @@ export type SonareEngineSyncMessage =
   | SonareEngineSyncMidiFxMessage
   | SonareEngineSyncMidiNoteMessage
   | SonareEngineSyncMidiCcMessage
+  | SonareEngineSyncMidiUmpMessage
   | SonareEngineSyncMidiSysexMessage
   | SonareEngineSyncMidiPanicMessage
   | SonareEngineSyncMidiDestinationExternalMessage
-  | SonareEngineSyncExternalMidiClockMessage;
+  | SonareEngineSyncExternalMidiClockMessage
+  | SonareEngineSyncMidiInputSourceMessage
+  | SonareEngineSyncMidiCcBindingMessage
+  | SonareEngineSyncMidiInputEventMessage
+  | SonareEngineDestroyMessage;
 
 export interface WorkletPort {
   postMessage?: (message: unknown, transfer?: Transferable[]) => void;

package/src/worklet/protocol.ts

@@ -77,6 +77,17 @@ export function decodeFrame(lo: number, hi: number): number {
 export const SONARE_ENGINE_RING_HEADER_INTS = 5;
 export const SONARE_ENGINE_COMMAND_RECORD_BYTES = 32;
 export const SONARE_ENGINE_TELEMETRY_RECORD_BYTES = 48;
+// Clip-page request ring header: [writeIndex, readIndex, capacity,
+// recordUint32s, dropped]. Records are [clipId, pageIndex]. This is an SPSC
+// queue: the AudioWorklet is the sole writer and the main thread is the sole
+// reader. Unlike the telemetry rings, it must not overwrite unread requests:
+// the producer increments `dropped` when the fixed queue is full.
+export const SONARE_CLIP_PAGE_REQUEST_RING_HEADER_INTS = 5;
+export const SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S = 2;
+// External MIDI records: destination ID, render-frame offset, packed MIDI-1
+// bytes (little-endian), and byte count. SPSC worklet -> main-thread ring.
+export const SONARE_EXTERNAL_MIDI_RING_HEADER_INTS = 5;
+export const SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S = 4;
 
 export enum SonareEngineCommandType {
   SetParam = 0,
@@ -122,6 +133,9 @@ export enum SonareEngineTelemetryError {
   CommandBacklogDeferred = 14,
   ClipPageUnderrun = 15,
   InsertAutomationOverflow = 16,
+  MidiClockOverflow = 17,
+  MetronomeOverflow = 18,
+  InvalidCommand = 19,
 }
 
 export interface SonareMeterRingBuffer {
@@ -180,6 +194,31 @@ export interface SonareScopeRingReadResult {
   scopes: SonareWorkletScopeSnapshot[];
 }
 
+export interface SonareExternalMidiRingEvent {
+  destinationId: number;
+  renderFrame: number;
+  byteWord: number;
+  byteCount: number;
+}
+
+export interface SonareExternalMidiRingBuffer {
+  sharedBuffer: SharedArrayBuffer;
+  header: Int32Array;
+  records: Uint32Array;
+  capacity: number;
+}
+
+export interface SharedExternalMidiRingWriter {
+  header: Int32Array;
+  records: Uint32Array;
+  capacity: number;
+}
+
+export interface SonareExternalMidiRingReadResult {
+  events: SonareExternalMidiRingEvent[];
+  dropped: number;
+}
+
 export interface SharedScopeRingWriter {
   header: Int32Array;
   records: Float32Array;
@@ -226,6 +265,30 @@ export interface SonareEngineTelemetryRingReadResult {
   telemetry: SonareEngineTelemetryRecord[];
 }
 
+export interface SonareClipPageRequest {
+  clipId: number;
+  pageIndex: number;
+}
+
+export interface SonareClipPageRequestRingBuffer {
+  sharedBuffer: SharedArrayBuffer;
+  header: Int32Array;
+  records: Uint32Array;
+  capacity: number;
+}
+
+export interface SharedClipPageRequestRingWriter {
+  header: Int32Array;
+  records: Uint32Array;
+  capacity: number;
+}
+
+export interface SonareClipPageRequestRingReadResult {
+  requests: SonareClipPageRequest[];
+  /** Cumulative uint32 drop count for native and SAB-ring overflows. */
+  dropped: number;
+}
+
 export interface SharedMeterRingWriter {
   header: Int32Array;
   records: Float32Array;
@@ -495,6 +558,190 @@ export function sonareEngineTelemetryRingBufferByteLength(capacity: number): num
   );
 }
 
+export function sonareClipPageRequestRingBufferByteLength(capacity: number): number {
+  const clampedCapacity = Math.max(1, Math.floor(capacity));
+  return (
+    SONARE_CLIP_PAGE_REQUEST_RING_HEADER_INTS * Int32Array.BYTES_PER_ELEMENT +
+    clampedCapacity * SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S * Uint32Array.BYTES_PER_ELEMENT
+  );
+}
+
+export function sonareExternalMidiRingBufferByteLength(capacity: number): number {
+  const clampedCapacity = Math.max(1, Math.floor(capacity));
+  return (
+    SONARE_EXTERNAL_MIDI_RING_HEADER_INTS * Int32Array.BYTES_PER_ELEMENT +
+    clampedCapacity * SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S * Uint32Array.BYTES_PER_ELEMENT
+  );
+}
+
+export function externalMidiRingFromSharedBuffer(
+  sharedBuffer: SharedArrayBuffer,
+  fallbackCapacity?: number,
+): SharedExternalMidiRingWriter {
+  const headerBytes = SONARE_EXTERNAL_MIDI_RING_HEADER_INTS * Int32Array.BYTES_PER_ELEMENT;
+  const header = new Int32Array(sharedBuffer, 0, SONARE_EXTERNAL_MIDI_RING_HEADER_INTS);
+  const existingCapacity = Atomics.load(header, 2);
+  const capacity = Math.max(1, Math.floor(existingCapacity || fallbackCapacity || 1));
+  if (sharedBuffer.byteLength < sonareExternalMidiRingBufferByteLength(capacity)) {
+    throw new Error('externalMidiSharedBuffer is too small for the requested ring capacity.');
+  }
+  Atomics.store(header, 2, capacity);
+  Atomics.store(header, 3, SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S);
+  return {
+    header,
+    records: new Uint32Array(
+      sharedBuffer,
+      headerBytes,
+      capacity * SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S,
+    ),
+    capacity,
+  };
+}
+
+export function createSonareExternalMidiRingBuffer(capacity = 256): SonareExternalMidiRingBuffer {
+  const clampedCapacity = Math.max(1, Math.floor(capacity));
+  const sharedBuffer = new SharedArrayBuffer(
+    sonareExternalMidiRingBufferByteLength(clampedCapacity),
+  );
+  const ring = externalMidiRingFromSharedBuffer(sharedBuffer, clampedCapacity);
+  Atomics.store(ring.header, 0, 0);
+  Atomics.store(ring.header, 1, 0);
+  Atomics.store(ring.header, 4, 0);
+  return { sharedBuffer, header: ring.header, records: ring.records, capacity: ring.capacity };
+}
+
+/** Write one lowered MIDI-1 event without allocations from the audio worklet. */
+export function pushSonareExternalMidiRingBuffer(
+  ring: SharedExternalMidiRingWriter,
+  destinationId: number,
+  renderFrame: number,
+  byteWord: number,
+  byteCount: number,
+): boolean {
+  // Emscripten can expose an int64 render-frame scalar as bigint when the
+  // host enables WASM_BIGINT. Normalize at this fixed-record boundary.
+  const destination = Number(destinationId);
+  const frame = Number(renderFrame);
+  const packedBytes = Number(byteWord);
+  const count = Number(byteCount);
+  if (
+    !Number.isSafeInteger(destination) ||
+    !Number.isSafeInteger(frame) ||
+    frame < 0 ||
+    !Number.isSafeInteger(packedBytes) ||
+    packedBytes < 0 ||
+    packedBytes > 0xff_ffff ||
+    !Number.isSafeInteger(count) ||
+    count < 1 ||
+    count > 3
+  ) {
+    Atomics.add(ring.header, 4, 1);
+    return false;
+  }
+  const writeIndex = Atomics.load(ring.header, 0);
+  const readIndex = Atomics.load(ring.header, 1);
+  if (writeIndex - readIndex >= ring.capacity) {
+    Atomics.add(ring.header, 4, 1);
+    return false;
+  }
+  const offset = (writeIndex % ring.capacity) * SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S;
+  Atomics.store(ring.records, offset, destination);
+  Atomics.store(ring.records, offset + 1, frame);
+  Atomics.store(ring.records, offset + 2, packedBytes);
+  Atomics.store(ring.records, offset + 3, count);
+  Atomics.store(ring.header, 0, writeIndex + 1);
+  return true;
+}
+
+/** Main-thread drain. It is intentionally the only place MIDI byte arrays are built. */
+export function readSonareExternalMidiRingBuffer(
+  ring: SonareExternalMidiRingBuffer,
+): SonareExternalMidiRingReadResult {
+  const readIndex = Atomics.load(ring.header, 1);
+  const writeIndex = Atomics.load(ring.header, 0);
+  const events: SonareExternalMidiRingEvent[] = [];
+  for (let index = readIndex; index < writeIndex; index++) {
+    const offset = (index % ring.capacity) * SONARE_EXTERNAL_MIDI_RING_RECORD_UINT32S;
+    events.push({
+      destinationId: Atomics.load(ring.records, offset) >>> 0,
+      renderFrame: Atomics.load(ring.records, offset + 1) >>> 0,
+      byteWord: Atomics.load(ring.records, offset + 2) >>> 0,
+      byteCount: Atomics.load(ring.records, offset + 3) >>> 0,
+    });
+  }
+  Atomics.store(ring.header, 1, writeIndex);
+  return { events, dropped: Atomics.load(ring.header, 4) >>> 0 };
+}
+
+export function createSonareClipPageRequestRingBuffer(
+  capacity = 128,
+): SonareClipPageRequestRingBuffer {
+  const clampedCapacity = Math.max(1, Math.floor(capacity));
+  const sharedBuffer = new SharedArrayBuffer(
+    sonareClipPageRequestRingBufferByteLength(clampedCapacity),
+  );
+  const ring = clipPageRequestRingFromSharedBuffer(sharedBuffer, clampedCapacity);
+  Atomics.store(ring.header, 0, 0);
+  Atomics.store(ring.header, 1, 0);
+  Atomics.store(ring.header, 2, ring.capacity);
+  Atomics.store(ring.header, 3, SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S);
+  Atomics.store(ring.header, 4, 0);
+  return { sharedBuffer, header: ring.header, records: ring.records, capacity: ring.capacity };
+}
+
+/**
+ * Writes one request without allocating. Invalid uint32 coordinates and a full
+ * ring are counted as drops so the main thread can surface a bounded-loss
+ * diagnostic without receiving a worklet postMessage.
+ */
+export function pushSonareClipPageRequestRingBuffer(
+  ring: SharedClipPageRequestRingWriter,
+  clipId: number,
+  pageIndex: number,
+): boolean {
+  if (
+    !Number.isSafeInteger(clipId) ||
+    clipId < 0 ||
+    clipId > 0xffff_ffff ||
+    !Number.isSafeInteger(pageIndex) ||
+    pageIndex < 0 ||
+    pageIndex > 0xffff_ffff
+  ) {
+    Atomics.add(ring.header, 4, 1);
+    return false;
+  }
+  const writeIndex = Atomics.load(ring.header, 0);
+  const readIndex = Atomics.load(ring.header, 1);
+  if (writeIndex - readIndex >= ring.capacity) {
+    Atomics.add(ring.header, 4, 1);
+    return false;
+  }
+  const offset = (writeIndex % ring.capacity) * SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S;
+  Atomics.store(ring.records, offset, clipId);
+  Atomics.store(ring.records, offset + 1, pageIndex);
+  // Publish only after both scalar fields have been written.
+  Atomics.store(ring.header, 0, writeIndex + 1);
+  return true;
+}
+
+/** Drains the SPSC request ring on the main thread. Object creation is here, never in process(). */
+export function readSonareClipPageRequestRingBuffer(
+  ring: SonareClipPageRequestRingBuffer,
+): SonareClipPageRequestRingReadResult {
+  const readIndex = Atomics.load(ring.header, 1);
+  const writeIndex = Atomics.load(ring.header, 0);
+  const requests: SonareClipPageRequest[] = [];
+  for (let index = readIndex; index < writeIndex; index++) {
+    const offset = (index % ring.capacity) * SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S;
+    requests.push({
+      clipId: Atomics.load(ring.records, offset),
+      pageIndex: Atomics.load(ring.records, offset + 1),
+    });
+  }
+  Atomics.store(ring.header, 1, writeIndex);
+  return { requests, dropped: Atomics.load(ring.header, 4) >>> 0 };
+}
+
 export function createSonareEngineCommandRingBuffer(capacity = 128): SonareEngineCommandRingBuffer {
   const clampedCapacity = Math.max(1, Math.floor(capacity));
   const sharedBuffer = new SharedArrayBuffer(
@@ -668,18 +915,56 @@ export function engineRingFromSharedBuffer(
   };
 }
 
+export function clipPageRequestRingFromSharedBuffer(
+  sharedBuffer: SharedArrayBuffer,
+  fallbackCapacity?: number,
+): SharedClipPageRequestRingWriter {
+  const headerBytes = SONARE_CLIP_PAGE_REQUEST_RING_HEADER_INTS * Int32Array.BYTES_PER_ELEMENT;
+  const header = new Int32Array(sharedBuffer, 0, SONARE_CLIP_PAGE_REQUEST_RING_HEADER_INTS);
+  const existingCapacity = Atomics.load(header, 2);
+  const capacity = Math.max(1, Math.floor(existingCapacity || fallbackCapacity || 1));
+  const minBytes = sonareClipPageRequestRingBufferByteLength(capacity);
+  if (sharedBuffer.byteLength < minBytes) {
+    throw new Error('clipPageRequestSharedBuffer is too small for the requested ring capacity.');
+  }
+  Atomics.store(header, 2, capacity);
+  Atomics.store(header, 3, SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S);
+  return {
+    header,
+    records: new Uint32Array(
+      sharedBuffer,
+      headerBytes,
+      capacity * SONARE_CLIP_PAGE_REQUEST_RING_RECORD_UINT32S,
+    ),
+    capacity,
+  };
+}
+
 function recordOffset(index: number, capacity: number, recordBytes: number): number {
   return (index % capacity) * recordBytes;
 }
 
-export function toBigInt64(value: number | bigint | undefined, fallback: bigint): bigint {
-  if (typeof value === 'bigint') {
-    return value;
+function toSafeInteger(value: number | bigint | undefined, fallback: number): number {
+  const resolved = typeof value === 'bigint' ? Number(value) : value;
+  if (resolved === undefined) {
+    return fallback;
   }
-  if (typeof value === 'number') {
-    return BigInt(Math.trunc(value));
+  if (!Number.isSafeInteger(resolved)) {
+    throw new RangeError('64-bit ring values must be safe integers');
   }
-  return fallback;
+  return resolved;
+}
+
+/** Store a signed 64-bit safe integer as two 32-bit words without BigInt. */
+export function writeInt64Words(view: DataView, offset: number, value: number): void {
+  const integer = toSafeInteger(value, 0);
+  view.setUint32(offset, integer >>> 0, true);
+  view.setInt32(offset + 4, Math.floor(integer / 0x100000000), true);
+}
+
+/** Reconstruct a signed 64-bit safe integer stored by {@link writeInt64Words}. */
+export function readInt64Words(view: DataView, offset: number): number {
+  return view.getInt32(offset + 4, true) * 0x100000000 + view.getUint32(offset, true);
 }
 
 function writeEngineCommandRecord(
@@ -689,21 +974,21 @@ function writeEngineCommandRecord(
 ): void {
   view.setUint32(offset, command.type, true);
   view.setUint32(offset + 4, command.targetId ?? 0, true);
-  view.setBigInt64(offset + 8, toBigInt64(command.sampleTime, -1n), true);
+  writeInt64Words(view, offset + 8, toSafeInteger(command.sampleTime, -1));
   // argFloat occupies a full 8-byte Float64 slot (replacing the old Float32 +
   // 4-byte pad) so PPQ scalars carried here keep full double precision over the
   // SAB transport, matching the engine's double-precision seek/loop contract.
   view.setFloat64(offset + 16, command.argFloat ?? 0, true);
-  view.setBigInt64(offset + 24, toBigInt64(command.argInt, 0n), true);
+  writeInt64Words(view, offset + 24, toSafeInteger(command.argInt, 0));
 }
 
 function readEngineCommandRecord(view: DataView, offset: number): SonareEngineCommandRecord {
   return {
     type: view.getUint32(offset, true),
     targetId: view.getUint32(offset + 4, true),
-    sampleTime: Number(view.getBigInt64(offset + 8, true)),
+    sampleTime: readInt64Words(view, offset + 8),
     argFloat: view.getFloat64(offset + 16, true),
-    argInt: Number(view.getBigInt64(offset + 24, true)),
+    argInt: readInt64Words(view, offset + 24),
   };
 }
 
@@ -714,21 +999,22 @@ function writeEngineTelemetryRecord(
 ): void {
   view.setUint32(offset, telemetry.type, true);
   view.setUint32(offset + 4, telemetry.error, true);
-  view.setBigInt64(offset + 8, BigInt(Math.trunc(telemetry.renderFrame)), true);
-  view.setBigInt64(offset + 16, BigInt(Math.trunc(telemetry.timelineSample)), true);
-  view.setBigInt64(offset + 24, BigInt(Math.trunc(telemetry.audibleTimelineSample)), true);
+  writeInt64Words(view, offset + 8, telemetry.renderFrame);
+  writeInt64Words(view, offset + 16, telemetry.timelineSample);
+  writeInt64Words(view, offset + 24, telemetry.audibleTimelineSample);
   view.setInt32(offset + 32, telemetry.graphLatencySamplesQ8, true);
   view.setUint32(offset + 36, telemetry.value, true);
-  view.setBigInt64(offset + 40, 0n, true);
+  view.setUint32(offset + 40, 0, true);
+  view.setUint32(offset + 44, 0, true);
 }
 
 function readEngineTelemetryRecord(view: DataView, offset: number): SonareEngineTelemetryRecord {
   return {
     type: view.getUint32(offset, true),
     error: view.getUint32(offset + 4, true),
-    renderFrame: Number(view.getBigInt64(offset + 8, true)),
-    timelineSample: Number(view.getBigInt64(offset + 16, true)),
-    audibleTimelineSample: Number(view.getBigInt64(offset + 24, true)),
+    renderFrame: readInt64Words(view, offset + 8),
+    timelineSample: readInt64Words(view, offset + 16),
+    audibleTimelineSample: readInt64Words(view, offset + 24),
     graphLatencySamplesQ8: view.getInt32(offset + 32, true),
     value: view.getUint32(offset + 36, true),
   };