@libraz/libsonare 1.8.0 → 1.8.1

package/src/worklet/engine-node.ts

@@ -9,8 +9,10 @@ import {
   isEngineTransportResponseMessage,
   isExternalMidiBatchMessage,
   isMeterSnapshot,
+  isScopeSnapshot,
   requireChannelCount,
   requireIntegerOption,
+  resolveScopeBandCount,
 } from './guards';
 import type {
   SonareEngineCaptureRequestMessage,
@@ -72,7 +74,8 @@ function isValidCommandRecord(command: SonareEngineCommandRecord): boolean {
     !Number.isSafeInteger(type) ||
     type < SonareEngineCommandType.SetParam ||
     (type > SonareEngineCommandType.SeekMarker &&
-      type !== SonareEngineCommandType.SetTrackMonitorMode)
+      type !== SonareEngineCommandType.SetTrackMonitorMode &&
+      type !== SonareEngineCommandType.ResetMasterLoudnessMeter)
   ) {
     return false;
   }
@@ -206,6 +209,8 @@ export class SonareRealtimeEngineNode {
         this.emitTelemetry(event.data);
       } else if (isMeterSnapshot(event.data)) {
         this.emitMeter(event.data);
+      } else if (isScopeSnapshot(event.data)) {
+        this.emitScope(event.data);
       } else if (isExternalMidiBatchMessage(event.data)) {
         this.emitMidiOut(event.data.events);
       } else if (isClipPageRequestMessage(event.data)) {
@@ -273,6 +278,13 @@ export class SonareRealtimeEngineNode {
       );
     }
 
+    const meterIntervalFrames = requireIntegerOption(
+      options.meterIntervalFrames,
+      2048,
+      'meterIntervalFrames',
+      0,
+    );
+
     // Resolved before the transport branch, so a capacity the ring could not
     // hold is refused by name whichever transport the caller ends up with.
     const commandRingCapacity = requireIntegerOption(
@@ -302,7 +314,7 @@ export class SonareRealtimeEngineNode {
       'scopeRingCapacity',
       1,
     );
-    const scopeBands = requireIntegerOption(options.scopeBands, 48, 'scopeBands', 1);
+    const scopeBands = resolveScopeBandCount(options.scopeBands);
     const clipPageRequestRingCapacity = requireIntegerOption(
       options.clipPageRequestRingCapacity,
       128,
@@ -352,6 +364,7 @@ export class SonareRealtimeEngineNode {
       sampleRate: options.sampleRate ?? context.sampleRate,
       blockSize,
       channelCount,
+      meterIntervalFrames,
       cueOutput,
       commandSharedBuffer: commandRing?.sharedBuffer,
       commandRingCapacity: commandRing?.capacity,
@@ -361,8 +374,8 @@ export class SonareRealtimeEngineNode {
       meterRingCapacity: meterRing?.capacity,
       scopeSharedBuffer: scopeRing?.sharedBuffer,
       scopeRingCapacity: scopeRing?.capacity,
-      scopeBands: scopeRing?.bands,
-      scopeIntervalFrames: scopeRing ? scopeIntervalFrames : undefined,
+      scopeBands: scopeIntervalFrames > 0 ? (scopeRing?.bands ?? scopeBands) : undefined,
+      scopeIntervalFrames: scopeIntervalFrames > 0 ? scopeIntervalFrames : undefined,
       clipPageRequestSharedBuffer: clipPageRequestRing?.sharedBuffer,
       clipPageRequestRingCapacity: clipPageRequestRing?.capacity,
       externalMidiSharedBuffer: externalMidiRing?.sharedBuffer,
@@ -416,6 +429,11 @@ export class SonareRealtimeEngineNode {
     return this.sendCommand({ type: SonareEngineCommandType.TransportPlay, sampleTime });
   }
 
+  /** Queues a reset of the master's integrated-loudness accumulator. */
+  resetMasterLoudnessMeter(sampleTime = -1): boolean {
+    return this.sendCommand({ type: SonareEngineCommandType.ResetMasterLoudnessMeter, sampleTime });
+  }
+
   stop(sampleTime = -1): boolean {
     return this.sendCommand({ type: SonareEngineCommandType.TransportStop, sampleTime });
   }

package/src/worklet/engine-processor.ts

@@ -1,8 +1,13 @@
 import type { EngineClip } from '../index';
 import { RealtimeEngine } from '../index';
 import { copyPlanesToOutput, type WorkletInput, type WorkletOutput } from './audio_types';
-import { emptyStripJson } from './engine-mixer-facade';
-import { requireChannelCount, requireIntegerOption } from './guards';
+import {
+  requireChannelCount,
+  requireIntegerOption,
+  resolveScopeBandCount,
+  SONARE_SCOPE_MAX_BANDS,
+  SONARE_SCOPE_MAX_POINTS,
+} from './guards';
 import {
   DEFAULT_METRONOME_CONFIG,
   type ResolvedMetronomeConfig,
@@ -41,6 +46,7 @@ import {
   type SonareEngineTelemetryRecord,
   type SonareEngineTelemetryRingBuffer,
   SonareEngineTelemetryType,
+  type SonareWorkletScopeSnapshot,
   scopeRingFromSharedBuffer,
   telemetryFromEngine,
   writeInt64Words,
@@ -84,6 +90,9 @@ export class SonareRealtimeEngineWorkletProcessor {
   private transport?: WorkletTransport;
   private meterIntervalFrames: number;
   private lastMeterFrame = Number.NEGATIVE_INFINITY;
+  private scopeIntervalFrames: number;
+  private scopeEnabled: boolean;
+  private scopeBands: number;
   // Latest metronome gains/click length pushed via 'syncMetronome'. The
   // SetMetronome command only toggles enabled state; the config arrives here.
   private metronomeConfig: ResolvedMetronomeConfig = { ...DEFAULT_METRONOME_CONFIG };
@@ -146,6 +155,16 @@ export class SonareRealtimeEngineWorkletProcessor {
           options.scopeBands,
         )
       : undefined;
+    this.scopeIntervalFrames = requireIntegerOption(
+      options.scopeIntervalFrames,
+      this.scopeRing ? this.blockSize : 0,
+      'scopeIntervalFrames',
+      0,
+    );
+    this.scopeBands = resolveScopeBandCount(options.scopeBands);
+    this.scopeEnabled =
+      this.scopeIntervalFrames > 0 &&
+      (this.scopeRing !== undefined || typeof this.transport?.postMessage === 'function');
     this.clipPageRequestRing = options.clipPageRequestSharedBuffer
       ? clipPageRequestRingFromSharedBuffer(
           options.clipPageRequestSharedBuffer,
@@ -183,18 +202,12 @@ export class SonareRealtimeEngineWorkletProcessor {
         this.monitorBuffers[ch] = this.engine.getMonitorChannelBuffer(ch, this.blockSize);
       }
     }
-    // Arm the engine's scope producer only when a scope ring was provided. The
-    // band count follows the ring's record layout so writeScopeRing never
-    // overruns its slot.
-    if (this.scopeRing) {
-      // Zero is the engine's own off switch for the scope tap, so the floor is 0.
-      const interval = requireIntegerOption(
-        options.scopeIntervalFrames,
-        this.blockSize,
-        'scopeIntervalFrames',
-        0,
+    // Arm the native scope producer only when a SAB ring or postMessage sink exists.
+    if (this.scopeEnabled) {
+      this.engine.configureScopeTelemetry(
+        this.scopeIntervalFrames,
+        Math.min(this.scopeRing?.bands ?? this.scopeBands, SONARE_SCOPE_MAX_BANDS),
       );
-      this.engine.configureScopeTelemetry(interval, this.scopeRing.bands);
     }
   }
 
@@ -496,37 +509,32 @@ export class SonareRealtimeEngineWorkletProcessor {
         // Complete earlier immediate edits in message order. Scheduled
         // commands remain queued for their render frame.
         this.engine.applyCommandsDueNowPreservingFuture();
-        this.engine.settleInsertParameters();
         if (message.buses) {
           this.engine.setTrackBuses(message.buses);
         }
         this.engine.setTrackLanes(message.lanes);
-        for (const target of message.forceInsertResets ?? []) {
-          const emptyJson = emptyStripJson(target);
+        for (const strip of message.trackStrips ?? []) {
+          this.engine.setTrackStripJson(strip.trackId, strip.sceneJson);
+        }
+        for (const strip of message.busStrips ?? []) {
+          this.engine.setBusStripJson(strip.busId, strip.sceneJson);
+        }
+        if (message.masterStripJson) {
+          this.engine.setMasterStripJson(message.masterStripJson);
+        }
+        for (const target of message.insertBaseResets ?? []) {
           switch (target.kind) {
             case 'track':
               this.engine.clearTrackInsertParameterBases(target.trackId);
-              this.engine.setTrackStripJson(target.trackId, emptyJson);
               break;
             case 'bus':
               this.engine.clearBusInsertParameterBases(target.busId);
-              this.engine.setBusStripJson(target.busId, emptyJson);
               break;
             case 'master':
               this.engine.clearMasterInsertParameterBases();
-              this.engine.setMasterStripJson(emptyJson);
               break;
           }
         }
-        for (const strip of message.trackStrips ?? []) {
-          this.engine.setTrackStripJson(strip.trackId, strip.sceneJson);
-        }
-        for (const strip of message.busStrips ?? []) {
-          this.engine.setBusStripJson(strip.busId, strip.sceneJson);
-        }
-        if (message.masterStripJson) {
-          this.engine.setMasterStripJson(message.masterStripJson);
-        }
         for (const binding of message.laneSidechains ?? []) {
           this.engine.setLaneSidechain(binding.trackId, binding.insertIndex, binding.sourceTrackId);
         }
@@ -1056,6 +1064,9 @@ export class SonareRealtimeEngineWorkletProcessor {
         this.engine.setTrackMonitorMode(laneIndex, mode as 0 | 1 | 2, sampleTime);
         break;
       }
+      case SonareEngineCommandType.ResetMasterLoudnessMeter:
+        this.engine.resetMasterLoudnessMeter(sampleTime);
+        break;
       default:
         this.publishTelemetryRecord({
           type: SonareEngineTelemetryType.Error,
@@ -1175,6 +1186,8 @@ export class SonareRealtimeEngineWorkletProcessor {
     for (let field = 0; field < 11; field++) {
       ring.records[offset + 3 + field] = this.engine.meterScratchValue(field);
     }
+    ring.records[offset + 14] = this.engine.meterScratchInputPeakDbL();
+    ring.records[offset + 15] = this.engine.meterScratchInputPeakDbR();
     Atomics.store(ring.header, 0, writeIndex + 1);
   }
 
@@ -1192,16 +1205,53 @@ export class SonareRealtimeEngineWorkletProcessor {
   // so header slot 3 is left at its initial 0.
 
   // Drains the engine's scope producer (FFT spectrum + goniometer points) into
-  // the lock-free SAB scope ring. No allocation on the render path: records are
-  // written field-by-field into the ring.
+  // the lock-free SAB scope ring or the bounded postMessage fallback. The SAB
+  // path remains allocation-free; postMessage materialises only records that
+  // are ready to publish.
   private publishScope(): void {
-    const ring = this.scopeRing;
-    if (!ring) {
+    if (!this.scopeEnabled) {
       return;
     }
+    const ring = this.scopeRing;
+    const transport = this.transport;
     for (let count = 0; count < 64 && this.engine.popScopeTelemetryToScratch(); count++) {
-      this.writeScopeScratch(ring);
+      if (ring) {
+        this.writeScopeScratch(ring);
+      } else {
+        this.postScopeScratch(transport);
+      }
+    }
+  }
+
+  private postScopeScratch(transport: WorkletTransport | undefined): void {
+    if (!transport?.postMessage) {
+      return;
+    }
+    const bandCount = Math.min(
+      SONARE_SCOPE_MAX_BANDS,
+      Math.max(0, Math.trunc(Number(this.engine.scopeScratchBandCount()))),
+    );
+    const pointCount = Math.min(
+      SONARE_SCOPE_MAX_POINTS,
+      Math.max(0, Math.trunc(Number(this.engine.scopeScratchPointCount()))),
+    );
+    const bands = new Float32Array(bandCount);
+    for (let i = 0; i < bandCount; i++) {
+      bands[i] = this.engine.scopeScratchBand(i);
+    }
+    const points = new Float32Array(pointCount * 2);
+    for (let i = 0; i < pointCount; i++) {
+      points[2 * i] = this.engine.scopeScratchPointLeft(i);
+      points[2 * i + 1] = this.engine.scopeScratchPointRight(i);
     }
+    const scope: SonareWorkletScopeSnapshot = {
+      type: 'scope',
+      targetId: this.engine.scopeScratchTargetId(),
+      frame: Number(this.engine.scopeScratchRenderFrame()),
+      bands,
+      points,
+    };
+    transport.postMessage(scope, [bands.buffer, points.buffer]);
   }
 
   private writeScopeScratch(ring: SharedScopeRingWriter): void {

package/src/worklet/engine-strips.ts

@@ -2,12 +2,10 @@ import { panLawCode, panModeCode } from '../codes';
 import type { EqBand, PanLawInput, PanMode, RealtimeEngine } from '../index';
 import type { InsertParamOverrideMap } from './engine-mixer-facade';
 import {
-  applyFullStripJson,
-  clearInsertParamOverrides,
   emptyStripJson,
-  hasInsertParamOverrides,
   type InsertParamOverride,
   insertParamOverrideKey,
+  replaceStripScene,
   type StripJsonTarget,
 } from './engine-mixer-facade';
 import type { SonareEngineInstrumentSyncMessage, SonareEngineSyncMessage } from './messages';
@@ -27,6 +25,7 @@ export interface EngineStripContext {
   readStripJson(target: StripJsonTarget): string | undefined;
   writeStripJson(target: StripJsonTarget, sceneJson: string): void;
   readonly insertParamOverrides: InsertParamOverrideMap;
+  clearInsertAutomationLanes(target: StripJsonTarget): void;
 }
 
 function trackIdFor(ctx: EngineStripContext, target: string | number): number {
@@ -92,15 +91,11 @@ export function setTrackStripJson(
   trackId: number,
   sceneJson: string,
   trackStripJson: Map<number, string>,
-): { resetInserts: boolean } {
+): { insertBaseResets: StripJsonTarget[]; constructionOverrides: InsertParamOverride[] } {
   const target: StripJsonTarget = { kind: 'track', trackId };
-  const resetInserts =
-    (trackStripJson.has(trackId) && trackStripJson.get(trackId) !== sceneJson) ||
-    hasInsertParamOverrides(ctx.insertParamOverrides, target);
-  applyFullStripJson(ctx.offlineEngine, target, sceneJson, resetInserts);
-  clearInsertParamOverrides(ctx.insertParamOverrides, target);
+  const result = replaceStripScene(ctx, target, trackStripJson.get(trackId), sceneJson);
   trackStripJson.set(trackId, sceneJson);
-  return { resetInserts };
+  return result;
 }
 
 export function setTrackStripEqBand(

package/src/worklet/engine-sync.ts

@@ -11,25 +11,30 @@ import type { SonareEngineSyncTempoMessage } from './messages';
  * Builds the ordered mixer-lane descriptors for a sync message.
  *
  * Each declared track id is paired with its current send list and output bus
- * (both omitted when absent), defensively copying the send entries.
+ * (both omitted when absent) and source channel layout, defensively copying the
+ * send entries.
  *
  * @param trackLaneIds Lane order (track ids) declared on the engine.
  * @param trackSends Per-track send lists.
  * @param trackOutputBus Per-track output bus routing.
+ * @param trackSourceChannelLayout Per-track source channel layouts.
  * @returns Lane descriptors in lane order.
  */
 export function buildMixerLanes(
   trackLaneIds: readonly number[],
   trackSends: ReadonlyMap<number, EngineTrackSend[]>,
   trackOutputBus: ReadonlyMap<number, number>,
+  trackSourceChannelLayout: ReadonlyMap<number, number>,
 ): EngineTrackLane[] {
   return trackLaneIds.map((trackId) => {
     const sends = trackSends.get(trackId);
     const outputBusId = trackOutputBus.get(trackId);
+    const sourceChannelLayout = trackSourceChannelLayout.get(trackId);
     return {
       trackId,
       ...(sends && sends.length > 0 ? { sends: sends.map((send) => ({ ...send })) } : {}),
       ...(outputBusId !== undefined ? { outputBusId } : {}),
+      ...(sourceChannelLayout !== undefined ? { sourceChannelLayout } : {}),
     };
   });
 }

package/src/worklet/engine.ts

@@ -102,6 +102,7 @@ export class SonareEngine {
   private readonly trackLaneIds: number[] = [];
   private readonly trackSends = new Map<number, EngineTrackSend[]>();
   private readonly trackOutputBus = new Map<number, number>();
+  private readonly trackSourceChannelLayout = new Map<number, number>();
   private readonly laneSidechains = new Map<
     string,
     { trackId: number; insertIndex: number; sourceTrackId: number }
@@ -242,6 +243,11 @@ export class SonareEngine {
     tempo.setTimeSignatureSegments(this.tempoContext, segments);
   }
 
+  /**
+   * A loop wrap, seek or stop sends note-offs plus CC64=0, CC121, CC123 and a
+   * centred pitch bend on every channel played since the last reset, so
+   * controller values set before a loop region are not restored at the wrap.
+   */
   setLoop(startPpq: number, endPpq: number, enabled = true): boolean {
     return tempo.setLoop(this.tempoContext, startPpq, endPpq, enabled);
   }
@@ -321,6 +327,15 @@ export class SonareEngine {
    * mixer lane first (like automationParamId) so the offline engine resolves the
    * same strip selector the realtime engine uses.
    *
+   * The returned id uses the track's current positional lane selector. When
+   * setTrackLanes successfully changes lane order or membership, the engine
+   * remaps already queued and published track automation by track id, but it
+   * cannot update a numeric id retained by the caller. Re-resolve every track
+   * insert id after such a topology change before passing it to
+   * setAutomationLane. Use setTrackStripInsertParamByName when the operation
+   * needs a stable track identity. Master and bus insert ids are separate and
+   * are not invalidated by track-lane changes.
+   *
    * @param target Track id (declares a mixer lane on first use).
    * @param insertIndex Index into the strip's combined insert sequence.
    * @param paramName Processor JSON-key parameter name.
@@ -454,14 +469,24 @@ export class SonareEngine {
     return sent;
   }
 
+  /** Resets the master's integrated loudness accumulator in both engine mirrors. */
+  resetMasterLoudnessMeter(renderFrame = -1): boolean {
+    this.offlineEngine.resetMasterLoudnessMeter(renderFrame);
+    return this.sendMirroredCommand({
+      type: SonareEngineCommandType.ResetMasterLoudnessMeter,
+      sampleTime: renderFrame,
+    });
+  }
+
   /**
    * Declares the mixer track lanes in an explicit order.
    *
-   * Lane indices are append-only: once a track id occupies a lane, its index
-   * stays fixed for the engine's lifetime. The given list must therefore start
-   * with the already-declared lane ids in their current order and may only
-   * append new track ids after them. Entries carrying `sends` replace that
-   * track's send list; entries without `sends` leave existing sends untouched.
+   * A successful call may reorder existing track ids, remove track ids, or add
+   * new ones. Existing queued and published track automation follows the track
+   * id, while numeric track-insert automation ids retained by the caller do
+   * not; re-resolve those ids after every topology change. Entries carrying
+   * `sends` replace that track's send list; entries without `sends` leave
+   * existing sends untouched.
    *
    * @param lanes Track ids or lane descriptors in the desired lane order.
    */
@@ -528,19 +553,18 @@ export class SonareEngine {
   }
 
   setTrackStripJson(target: string | number, sceneJson: string): void {
+    // Parse before declaring a new lane so malformed text cannot declare one.
+    mixer.decodedInsertSignature(sceneJson, { kind: 'track', trackId: 0 });
     const laneIndex = this.ensureTrackLane(target);
     const trackId = this.trackLaneIds[laneIndex];
-    const { resetInserts } = strips.setTrackStripJson(
+    const { insertBaseResets, constructionOverrides } = strips.setTrackStripJson(
       this.stripContext,
       trackId,
       sceneJson,
       this.trackStripJson,
     );
-    if (resetInserts) {
-      this.clearInsertAutomationLanes({ kind: 'track', trackId });
-    }
     mixer.pruneStripSidechains(this.mixerContext, { kind: 'track', trackId }, sceneJson);
-    this.syncMixer(resetInserts ? [{ kind: 'track', trackId }] : []);
+    this.syncMixer(insertBaseResets, constructionOverrides);
   }
 
   setTrackStripEqBand(target: string | number, bandIndex: number, band: EqBand | string): void {
@@ -625,18 +649,7 @@ export class SonareEngine {
   }
 
   setMasterStripJson(sceneJson: string): void {
-    const target = { kind: 'master' } as const;
-    const resetInserts =
-      (this.masterStripJson !== undefined && this.masterStripJson !== sceneJson) ||
-      mixer.hasInsertParamOverrides(this.insertParamOverrides, target);
-    mixer.applyFullStripJson(this.offlineEngine, target, sceneJson, resetInserts);
-    if (resetInserts) {
-      this.clearInsertAutomationLanes(target);
-    }
-    mixer.pruneStripSidechains(this.mixerContext, target, sceneJson);
-    mixer.clearInsertParamOverrides(this.insertParamOverrides, target);
-    this.masterStripJson = sceneJson;
-    this.syncMixer(resetInserts ? [target] : []);
+    mixer.setMasterStripJson(this.mixerContext, sceneJson);
   }
 
   setMasterStripEqBand(bandIndex: number, band: EqBand | string): void {
@@ -904,7 +917,10 @@ export class SonareEngine {
   /**
    * Route a track's MIDI to the external output (drained via {@link onMidiOut})
    * instead of an internal instrument, so the track plays an external device.
-   * Pass `external=false` to restore internal-synth playback.
+   * Pass `external=false` to restore internal-synth playback. The change takes
+   * effect at the next processed block; switching a destination's route first
+   * releases its notes and resets its controllers through the old route, and
+   * drops its pending MIDI-FX events.
    */
   setMidiDestinationExternal(trackId: string | number, external: boolean): void {
     strips.setMidiDestinationExternal(this.stripContext, trackId, external);
@@ -1397,8 +1413,11 @@ export class SonareEngine {
     return mixer.mixerLanes(this.mixerContext);
   }
 
-  private syncMixer(forceInsertResets: mixer.StripJsonTarget[] = []): void {
-    mixer.syncMixer(this.mixerContext, false, forceInsertResets);
+  private syncMixer(
+    insertBaseResets: mixer.StripJsonTarget[] = [],
+    oneShotInsertParamOverrides: mixer.InsertParamOverride[] = [],
+  ): void {
+    mixer.syncMixer(this.mixerContext, false, insertBaseResets, oneShotInsertParamOverrides);
   }
 
   private insertAutomationTargetKey(target: mixer.StripJsonTarget): string {
@@ -1494,6 +1513,7 @@ export class SonareEngine {
       trackLaneIds: this.trackLaneIds,
       trackSends: this.trackSends,
       trackOutputBus: this.trackOutputBus,
+      trackSourceChannelLayout: this.trackSourceChannelLayout,
       laneSidechains: this.laneSidechains,
       busSidechains: this.busSidechains,
       masterSidechains: this.masterSidechains,
@@ -1506,7 +1526,8 @@ export class SonareEngine {
       ensureTrackLane: (target) => this.ensureTrackLane(target),
       ensureBus: (busId) => this.ensureBus(busId),
       mixerLanes: () => this.mixerLanes(),
-      syncMixer: (forceInsertResets) => this.syncMixer(forceInsertResets),
+      syncMixer: (insertBaseResets, oneShotInsertParamOverrides) =>
+        this.syncMixer(insertBaseResets, oneShotInsertParamOverrides),
       clearInsertAutomationLanes: (target, forgetResolvedIds) =>
         this.clearInsertAutomationLanes(target, forgetResolvedIds),
       sendSmoothedParam: (paramId, value) => this.sendSmoothedParam(paramId, value),
@@ -1532,6 +1553,7 @@ export class SonareEngine {
       writeStripJson: (target, sceneJson) =>
         mixer.cacheStripJson(this.mixerContext, target, sceneJson),
       insertParamOverrides: this.insertParamOverrides,
+      clearInsertAutomationLanes: (target) => this.clearInsertAutomationLanes(target),
     };
   }
 
@@ -1683,17 +1705,7 @@ export class SonareEngine {
   }
 
   private ensureTrackLane(target: string | number): number {
-    const trackId = this.resolveTargetId(target);
-    if (!Number.isInteger(trackId) || trackId <= 0) {
-      throw new RangeError(`Invalid track id for mixer lane: ${String(target)}`);
-    }
-    const existing = this.trackLaneIds.indexOf(trackId);
-    if (existing >= 0) {
-      return existing;
-    }
-    this.trackLaneIds.push(trackId);
-    this.syncMixer();
-    return this.trackLaneIds.length - 1;
+    return mixer.ensureTrackLane(this.mixerContext, target);
   }
 
   private ensureBus(busId: number): number {

package/src/worklet/guards.ts

@@ -13,9 +13,11 @@ import type {
 } from './messages';
 import {
   isRecord,
+  SONARE_SCOPE_DEFAULT_BANDS,
   type SonareEngineCommandRecord,
   type SonareEngineTelemetryRecord,
   type SonareWorkletMeterSnapshot,
+  type SonareWorkletScopeSnapshot,
 } from './protocol';
 
 export function isWorkletMessage(value: unknown): value is SonareWorkletMessage {
@@ -331,10 +333,55 @@ export function isMeterSnapshot(value: unknown): value is SonareWorkletMeterSnap
     typeof value.rmsDbL === 'number' &&
     typeof value.rmsDbR === 'number' &&
     typeof value.correlation === 'number' &&
+    Number.isFinite(value.inputPeakDbL) &&
+    Number.isFinite(value.inputPeakDbR) &&
     (typeof value.targetId === 'number' || value.targetId === undefined)
   );
 }
 
+export const SONARE_SCOPE_MAX_BANDS = 64;
+export const SONARE_SCOPE_MAX_POINTS = 32;
+
+function isPlainFloat32Array(
+  value: unknown,
+  maxLength: number,
+  evenLength = false,
+): value is Float32Array {
+  if (
+    !(value instanceof Float32Array) ||
+    typeof ArrayBuffer === 'undefined' ||
+    !(value.buffer instanceof ArrayBuffer) ||
+    value.length > maxLength ||
+    (evenLength && value.length % 2 !== 0)
+  ) {
+    return false;
+  }
+  for (const sample of value) {
+    if (!Number.isFinite(sample)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Validates the bounded postMessage representation of a scope snapshot. */
+export function isScopeSnapshot(value: unknown): value is SonareWorkletScopeSnapshot {
+  return (
+    isRecord(value) &&
+    value.type === 'scope' &&
+    typeof value.targetId === 'number' &&
+    Number.isSafeInteger(value.targetId) &&
+    value.targetId >= 0 &&
+    value.targetId <= 0xffff_ffff &&
+    typeof value.frame === 'number' &&
+    Number.isSafeInteger(value.frame) &&
+    value.frame >= 0 &&
+    isPlainFloat32Array(value.bands, SONARE_SCOPE_MAX_BANDS) &&
+    value.bands.length > 0 &&
+    isPlainFloat32Array(value.points, SONARE_SCOPE_MAX_POINTS * 2, true)
+  );
+}
+
 /**
  * Resolves an integer option, refusing anything the field's own domain cannot
  * hold instead of rounding it into range.
@@ -356,6 +403,14 @@ export function requireIntegerOption(
   return resolved;
 }
 
+/** Resolves scope bands and applies the native tap's fixed 64-band ceiling. */
+export function resolveScopeBandCount(
+  value: number | undefined,
+  fallback = SONARE_SCOPE_DEFAULT_BANDS,
+): number {
+  return Math.min(requireIntegerOption(value, fallback, 'scopeBands', 1), SONARE_SCOPE_MAX_BANDS);
+}
+
 /** As {@link requireIntegerOption}, for a field whose domain admits either sign. */
 export function requireInteger(value: number | undefined, fallback: number, name: string): number {
   const resolved = value ?? fallback;

package/src/worklet/messages.ts

@@ -21,6 +21,7 @@ import type {
   SonareEngineCommandRecord,
   SonareEngineTelemetryRecord,
   SonareWorkletMeterSnapshot,
+  SonareWorkletScopeSnapshot,
   SonareWorkletSpectrumSnapshot,
 } from './protocol';
 
@@ -288,6 +289,7 @@ export interface SonareEngineSyncErrorMessage {
 
 export type SonareWorkletTransportMessage =
   | SonareWorkletMeterSnapshot
+  | SonareWorkletScopeSnapshot
   | SonareWorkletSpectrumSnapshot
   | SonareWorkletExternalMidiMessage
   | SonareEngineClipPageRequestMessage
@@ -511,8 +513,8 @@ export interface SonareEngineSyncMixerMessage {
   masterStripJson?: string;
   /** Retained by-name insert values, applied after strip and sidechain replay. */
   insertParamOverrides?: SonareEngineSyncMixerInsertParamOverride[];
-  /** Explicit full strip replacements that must reset retained insert state. */
-  forceInsertResets?: Array<
+  /** Strips whose manual insert bases are cleared after the strip replay, before insertParamOverrides. */
+  insertBaseResets?: Array<
     { kind: 'track'; trackId: number } | { kind: 'bus'; busId: number } | { kind: 'master' }
   >;
   /** Lane insert sidechain bindings (replayed after lanes/strips). */