@libraz/libsonare 1.5.5 → 1.7.0

package/src/project_class.ts

@@ -1,5 +1,6 @@
 import {
   assertProjectMidiEvents,
+  projectAutomationTargetKindValue,
   projectLoopModeValue,
   projectMidi1Event,
   projectModule,
@@ -9,12 +10,17 @@ import {
 } from './project_internal';
 import type {
   BuiltinSynthBinding,
+  ExternalSeparatedStemImportRequest,
+  ExternalSeparatedStemImportResult,
   MidiCcLearnOptions,
   ProjectAssistSidecar,
+  ProjectAssistSidecarInput,
   ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
+  ProjectAutomationTargetKind,
   ProjectBounceOptions,
   ProjectChordSymbol,
+  ProjectClip,
   ProjectClipCompSegment,
   ProjectClipDesc,
   ProjectClipFade,
@@ -32,9 +38,11 @@ import type {
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
+  ProjectSource,
   ProjectTempoCandidate,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
+  ProjectTrack,
   ProjectTrackDesc,
   ProjectTrackKind,
   ProjectWarpMapDesc,
@@ -44,6 +52,41 @@ import type {
   SynthPatch,
 } from './project_types';
 
+function validateAssistSidecarUint32(value: unknown, field: string): number {
+  if (
+    typeof value !== 'number' ||
+    !Number.isSafeInteger(value) ||
+    value < 0 ||
+    value > 0xffff_ffff
+  ) {
+    throw new RangeError(`Project.setAssistSidecar: ${field} must be a uint32`);
+  }
+  return value;
+}
+
+function validateAssistSidecarPpq(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `Project.setAssistSidecar: ${field} must be a finite, non-negative number`,
+    );
+  }
+  return value;
+}
+
+function validateAssistSidecarPayload(value: unknown): Uint8Array {
+  if (!(value instanceof Uint8Array)) {
+    throw new TypeError('Project.setAssistSidecar: payload must be a Uint8Array');
+  }
+  return value;
+}
+
+function validateAssistSidecarModuleId(value: unknown): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError('Project.setAssistSidecar: moduleId must be a non-empty string');
+  }
+  return value;
+}
+
 /**
  * Headless DAW project (control-thread-only arrangement model).
  *
@@ -77,6 +120,11 @@ export class Project {
     this.native = new (projectModule().Project)();
   }
 
+  /** Create a new empty project. */
+  static create(): Project {
+    return new Project();
+  }
+
   /** Pack a MIDI 1.0 note-on event accepted by {@link setMidiEvents}. */
   static midiNoteOn(
     ppq: number,
@@ -337,6 +385,19 @@ export class Project {
     return this.native.addClip(desc);
   }
 
+  /** Import host-separated PCM through the normal audio-track/clip path. */
+  importExternalStems(
+    request: ExternalSeparatedStemImportRequest,
+  ): ExternalSeparatedStemImportResult {
+    return this.native.importExternalStems({
+      ...request,
+      stems: request.stems.map((stem) => ({
+        ...stem,
+        layout: stem.layout === 'mono' ? 1 : stem.layout === 'stereo' ? 2 : stem.layout,
+      })),
+    });
+  }
+
   /** Split captured loop-recording audio into takes and add one clip. */
   addLoopRecordingTakes(desc: ProjectLoopRecordingDesc): ProjectLoopRecordingResult {
     return this.native.addLoopRecordingTakes(desc);
@@ -391,7 +452,11 @@ export class Project {
    * Route a track's MIDI to host-instrument `destinationId` (0 = default). The
    * compiler stamps every MIDI clip on the track with this id so the engine
    * dispatches its events to the instrument registered for that destination.
-   * Routes through an undoable edit command.
+   * Routes through an undoable edit command. Builtin, NativeSynth, and SF2
+   * instruments retain source-track provenance inside a shared destination
+   * voice pool. With only zero-latency instruments bound, live lanes and
+   * channel-strip bounces remain aligned. Configure one live lane per source
+   * track that needs strip processing.
    */
   setTrackMidiDestination(trackId: number, destinationId: number): void {
     this.native.setTrackMidiDestination(trackId, destinationId);
@@ -440,6 +505,19 @@ export class Project {
     this.native.setMaxUndoDepth(depth);
   }
 
+  /** Set the combined undo/redo history byte cap. Zero disables retention. */
+  setMaxHistoryBytes(bytes: number): void {
+    if (typeof bytes !== 'number') {
+      throw new TypeError('Project.setMaxHistoryBytes: bytes must be a number');
+    }
+    if (!Number.isFinite(bytes) || !Number.isInteger(bytes) || bytes < 0 || bytes > 0xffff_ffff) {
+      throw new RangeError(
+        'Project.setMaxHistoryBytes: bytes must be a finite integer in the uint32 range',
+      );
+    }
+    this.native.setMaxHistoryBytes(bytes);
+  }
+
   /** Replace a MIDI clip's entire event list. */
   setMidiEvents(
     clipId: number,
@@ -603,8 +681,11 @@ export class Project {
    * Karplus-Strong / modal / additive / percussion / extended-waveguide-piano
    * engines plus the realism layer). Pass a {@link SynthPatch}, a preset-name
    * string (`'saw-lead'` / `'va:saw-lead'`; see {@link synthPresetNames}), or
-   * an array of either; each object entry may carry a `destinationId` binding
-   * convenience (default 0), which is not part of the NativeSynth patch itself.
+   * an array of either; each object entry may carry `destinationId` (default
+   * 0) and `useGmPrograms` (default `false`) binding conveniences, neither of
+   * which is part of the NativeSynth patch itself. When enabled, MIDI program
+   * changes select the corresponding General MIDI voice while the patch remains
+   * the fallback.
    * Because the parameter defaults to `{}`, omission and explicit `undefined`
    * both create one default binding. Use an explicitly empty array `[]` (or
    * runtime `null`) for zero bindings. Unknown preset names throw.
@@ -685,6 +766,26 @@ export class Project {
     this.native.setClipFade(clipId, fadeIn, fadeOut);
   }
 
+  /** Audio source ids that need decoded PCM after deserialization. */
+  unresolvedAudioSourceIds(): number[] {
+    return this.native.unresolvedAudioSourceIds();
+  }
+
+  /** Register decoded interleaved PCM for an existing audio source (undoable). */
+  setSourceAudio(
+    sourceId: number,
+    audio: Float32Array,
+    channels: number,
+    sampleRate: number,
+  ): void {
+    this.native.setSourceAudio(sourceId, audio, channels, sampleRate);
+  }
+
+  /** Replace an audio source's metadata strings as one undoable edit. */
+  setAudioSourceMetadata(sourceId: number, contentHash: string, externalStemRole: string): void {
+    this.native.setAudioSourceMetadata(sourceId, contentHash, externalStemRole);
+  }
+
   /** Replace a clip's take list and active take id (undoable). */
   setClipTakes(clipId: number, takes: ReadonlyArray<ProjectClipTake>, activeTakeId = 0): void {
     this.native.setClipTakes(clipId, takes, activeTakeId);
@@ -739,25 +840,41 @@ export class Project {
     this.native.setTrackRoute(trackId, channelStripRef ?? '', outputTarget ?? '');
   }
 
-  /** Append an automation lane to a track; returns the lane index (undoable). */
+  /** Append an automation lane; returns its stable target parameter id (undoable). */
   addAutomationLane(trackId: number, desc: ProjectAutomationLaneDesc): number {
-    return this.native.addAutomationLane(trackId, {
-      targetParamId: desc.targetParamId,
-      points: desc.points,
-    });
+    if (desc.targetParamId === 0) {
+      throw new RangeError('project automation lane targetParamId must be non-zero');
+    }
+    const nativeDesc: ProjectAutomationLaneDesc = { ...desc };
+    if (Object.keys(desc).includes('targetKind')) {
+      nativeDesc.targetKind = projectAutomationTargetKindValue(
+        desc.targetKind as ProjectAutomationTargetKind,
+      ) as ProjectAutomationTargetKind;
+    }
+    return this.native.addAutomationLane(trackId, nativeDesc);
   }
 
-  /** Replace an existing automation lane in place (undoable). */
-  editAutomationLane(trackId: number, laneIndex: number, desc: ProjectAutomationLaneDesc): void {
-    this.native.editAutomationLane(trackId, laneIndex, {
-      targetParamId: desc.targetParamId,
-      points: desc.points,
-    });
+  /** Replace the lane identified by its stable target parameter id (undoable). */
+  editAutomationLane(
+    trackId: number,
+    targetParamId: number,
+    desc: ProjectAutomationLaneDesc,
+  ): void {
+    if (desc.targetParamId === 0) {
+      throw new RangeError('project automation lane targetParamId must be non-zero');
+    }
+    const nativeDesc: ProjectAutomationLaneDesc = { ...desc };
+    if (Object.keys(desc).includes('targetKind')) {
+      nativeDesc.targetKind = projectAutomationTargetKindValue(
+        desc.targetKind as ProjectAutomationTargetKind,
+      ) as ProjectAutomationTargetKind;
+    }
+    this.native.editAutomationLane(trackId, targetParamId, nativeDesc);
   }
 
-  /** Remove an automation lane from a track (undoable). */
-  removeAutomationLane(trackId: number, laneIndex: number): void {
-    this.native.removeAutomationLane(trackId, laneIndex);
+  /** Remove the lane identified by its stable target parameter id (undoable). */
+  removeAutomationLane(trackId: number, targetParamId: number): void {
+    this.native.removeAutomationLane(trackId, targetParamId);
   }
 
   /** Replace the project's key annotation stream (undoable). */
@@ -770,7 +887,14 @@ export class Project {
     this.native.annotateChords(chords);
   }
 
-  /** Add or update an opaque assist sidecar by module id + target scope (undoable). */
+  /**
+   * Add or update an opaque assist sidecar via an undoable edit.
+   *
+   * The descriptor form is the canonical API and matches the Node binding;
+   * the positional form remains available for compatibility with the original
+   * WASM facade.
+   */
+  setAssistSidecar(sidecar: ProjectAssistSidecarInput): void;
   setAssistSidecar(
     moduleId: string,
     schemaVersion: number,
@@ -778,14 +902,52 @@ export class Project {
     regionStartPpq: number,
     regionEndPpq: number,
     payload: Uint8Array,
+  ): void;
+  setAssistSidecar(
+    sidecarOrModuleId: ProjectAssistSidecarInput | string,
+    schemaVersion?: number,
+    targetTrackId?: number,
+    regionStartPpq?: number,
+    regionEndPpq?: number,
+    payload?: Uint8Array,
   ): void {
+    if (typeof sidecarOrModuleId === 'string') {
+      if (
+        schemaVersion === undefined ||
+        targetTrackId === undefined ||
+        regionStartPpq === undefined ||
+        regionEndPpq === undefined ||
+        payload === undefined
+      ) {
+        throw new TypeError('Project.setAssistSidecar: positional form requires six arguments');
+      }
+      this.native.setAssistSidecar(
+        validateAssistSidecarModuleId(sidecarOrModuleId),
+        validateAssistSidecarUint32(schemaVersion, 'schemaVersion'),
+        validateAssistSidecarUint32(targetTrackId, 'targetTrackId'),
+        validateAssistSidecarPpq(regionStartPpq, 'regionStartPpq'),
+        validateAssistSidecarPpq(regionEndPpq, 'regionEndPpq'),
+        validateAssistSidecarPayload(payload),
+      );
+      return;
+    }
+
+    if (
+      sidecarOrModuleId === null ||
+      typeof sidecarOrModuleId !== 'object' ||
+      Array.isArray(sidecarOrModuleId)
+    ) {
+      throw new TypeError('Project.setAssistSidecar: expected a sidecar descriptor object');
+    }
+    const sidecar = sidecarOrModuleId;
+    const moduleId = validateAssistSidecarModuleId(sidecar.moduleId);
     this.native.setAssistSidecar(
       moduleId,
-      schemaVersion,
-      targetTrackId,
-      regionStartPpq,
-      regionEndPpq,
-      payload,
+      validateAssistSidecarUint32(sidecar.schemaVersion ?? 0, 'schemaVersion'),
+      validateAssistSidecarUint32(sidecar.targetTrackId ?? 0, 'targetTrackId'),
+      validateAssistSidecarPpq(sidecar.regionStartPpq ?? 0, 'regionStartPpq'),
+      validateAssistSidecarPpq(sidecar.regionEndPpq ?? 0, 'regionEndPpq'),
+      validateAssistSidecarPayload(sidecar.payload ?? new Uint8Array()),
     );
   }
 
@@ -799,6 +961,12 @@ export class Project {
     return this.native.getAssistSidecar(index);
   }
 
+  /** Read every stored assist sidecar in the same order as the index getter. */
+  assistSidecars(): ProjectAssistSidecar[] {
+    const count = this.assistSidecarCount();
+    return Array.from({ length: count }, (_, index) => this.getAssistSidecar(index));
+  }
+
   /** Set the project's clip-overlap policy (SonareProjectOverlapPolicy ordinal). */
   setOverlapPolicy(policy: number): void {
     this.native.setOverlapPolicy(policy);
@@ -841,6 +1009,19 @@ export class Project {
     return this.native.markerByIndex(index);
   }
 
+  /** Read a stored project track by 0-based index. */
+  trackByIndex(index: number): ProjectTrack {
+    return this.native.trackByIndex(index);
+  }
+  /** Read a stored project clip by 0-based index. */
+  clipByIndex(index: number): ProjectClip {
+    return this.native.clipByIndex(index);
+  }
+  /** Read a stored project source by 0-based index. */
+  sourceByIndex(index: number): ProjectSource {
+    return this.native.sourceByIndex(index);
+  }
+
   /** Number of markers in the project. */
   markerCount(): number {
     return this.native.markerCount();

package/src/project_internal.ts

@@ -1,10 +1,14 @@
+import { resolveEnumOrdinal } from './codes';
 import { getSonareModule } from './module_state';
 import type {
   BuiltinSynthBinding,
   ProjectAssistSidecar,
+  ProjectAutomationLaneDesc,
   ProjectAutomationPoint,
+  ProjectAutomationTargetKind,
   ProjectBounceOptions,
   ProjectChordSymbol,
+  ProjectClip,
   ProjectClipCompSegment,
   ProjectClipDesc,
   ProjectClipFade,
@@ -21,9 +25,11 @@ import type {
   ProjectMidiRouteConfig,
   ProjectMidiRouteResult,
   ProjectNotePairValidation,
+  ProjectSource,
   ProjectTempoCandidate,
   ProjectTempoSegment,
   ProjectTimeSignatureSegment,
+  ProjectTrack,
   ProjectTrackKind,
   ProjectWarpMapDesc,
   ProjectWarpMode,
@@ -41,6 +47,7 @@ export interface WasmProject {
   setSampleRate: (sampleRate: number) => void;
   addTrack: (desc: { kind?: number | string; name?: string }) => number;
   addClip: (desc: ProjectClipDesc) => number;
+  importExternalStems: (request: unknown) => { trackIds: number[]; clipIds: number[] };
   addLoopRecordingTakes: (desc: ProjectLoopRecordingDesc) => ProjectLoopRecordingResult;
   addMidiClip: (startPpq: number, lengthPpq: number) => ProjectMidiClipResult;
   splitClip: (clipId: number, splitPpq: number) => number;
@@ -60,6 +67,7 @@ export interface WasmProject {
   redo: () => void;
   clearHistory: () => void;
   setMaxUndoDepth: (depth: number) => void;
+  setMaxHistoryBytes: (bytes: number) => void;
   setMidiEvents: (
     clipId: number,
     events: ReadonlyArray<ProjectMidiEvent | readonly [number, number, number]>,
@@ -108,6 +116,14 @@ export interface WasmProject {
   removeClip: (clipId: number) => void;
   setClipGain: (clipId: number, gain: number) => void;
   setClipFade: (clipId: number, fadeIn: ProjectClipFade, fadeOut: ProjectClipFade) => void;
+  unresolvedAudioSourceIds: () => number[];
+  setSourceAudio: (
+    sourceId: number,
+    audio: Float32Array,
+    channels: number,
+    sampleRate: number,
+  ) => void;
+  setAudioSourceMetadata: (sourceId: number, contentHash: string, externalStemRole: string) => void;
   setClipTakes: (
     clipId: number,
     takes: ReadonlyArray<ProjectClipTake>,
@@ -125,16 +141,13 @@ export interface WasmProject {
   removeTrack: (trackId: number) => void;
   renameTrack: (trackId: number, name: string) => void;
   setTrackRoute: (trackId: number, channelStripRef: string, outputTarget: string) => void;
-  addAutomationLane: (
-    trackId: number,
-    desc: { targetParamId: number; points: ReadonlyArray<ProjectAutomationPoint> },
-  ) => number;
+  addAutomationLane: (trackId: number, desc: ProjectAutomationLaneDesc) => number;
   editAutomationLane: (
     trackId: number,
-    laneIndex: number,
-    desc: { targetParamId: number; points: ReadonlyArray<ProjectAutomationPoint> },
+    targetParamId: number,
+    desc: ProjectAutomationLaneDesc,
   ) => void;
-  removeAutomationLane: (trackId: number, laneIndex: number) => void;
+  removeAutomationLane: (trackId: number, targetParamId: number) => void;
   annotateKeys: (keys: ReadonlyArray<ProjectKeySegment>) => void;
   annotateChords: (chords: ReadonlyArray<ProjectChordSymbol>) => void;
   setAssistSidecar: (
@@ -154,6 +167,9 @@ export interface WasmProject {
   setMarker: (markerId: number, ppq: number, name: string) => number;
   setMarkerEx: (marker: ProjectMarker) => number;
   markerByIndex: (index: number) => ProjectMarker;
+  trackByIndex: (index: number) => ProjectTrack;
+  clipByIndex: (index: number) => ProjectClip;
+  sourceByIndex: (index: number) => ProjectSource;
   markerCount: () => number;
   trackCount: () => number;
   clipCount: () => number;
@@ -307,37 +323,25 @@ export function assertProjectMidiEvents(
 }
 
 export function projectTrackKindValue(kind: ProjectTrackKind | undefined): number {
-  if (kind === undefined || kind === 'audio') {
-    return 0;
-  }
-  if (kind === 'midi') {
-    return 1;
-  }
-  if (kind === 'aux') {
-    return 2;
-  }
-  return kind;
+  return resolveEnumOrdinal(kind ?? 'audio', { audio: 0, midi: 1, aux: 2 }, 'project track kind');
+}
+
+export function projectAutomationTargetKindValue(kind: ProjectAutomationTargetKind): number {
+  return resolveEnumOrdinal(
+    kind,
+    { opaque: 0, 'track-fader-db': 1, 'track-pan': 2 },
+    'project automation target kind',
+  );
 }
 
 export function projectWarpModeValue(mode: ProjectWarpMode | undefined): number {
-  if (mode === undefined || mode === 'off') {
-    return 0;
-  }
-  if (mode === 'repitch') {
-    return 1;
-  }
-  if (mode === 'tempo-sync') {
-    return 2;
-  }
-  return mode;
+  return resolveEnumOrdinal(
+    mode ?? 'off',
+    { off: 0, repitch: 1, 'tempo-sync': 2 },
+    'project warp mode',
+  );
 }
 
 export function projectLoopModeValue(mode: ProjectLoopMode | undefined): number {
-  if (mode === undefined || mode === 'off') {
-    return 0;
-  }
-  if (mode === 'loop') {
-    return 1;
-  }
-  return mode;
+  return resolveEnumOrdinal(mode ?? 'off', { off: 0, loop: 1 }, 'project loop mode');
 }

package/src/project_types.ts

@@ -25,6 +25,29 @@ export interface ProjectBounceOptions {
   instrumentLatencySamples?: number;
 }
 
+/** One decoded output from a host-owned source-separation model. */
+export interface ExternalSeparatedStem {
+  name: string;
+  /** Optional host metadata; it does not change DSP. */
+  role?: string;
+  layout: 'mono' | 'stereo' | 1 | 2;
+  planarSamples: Float32Array[];
+  /** Absolute project-rate frame at which this stem begins. */
+  startFrame?: number;
+}
+
+/** Request for {@link Project.importExternalStems}. */
+export interface ExternalSeparatedStemImportRequest {
+  sampleRate: number;
+  stems: ExternalSeparatedStem[];
+}
+
+/** Ids of the normal tracks and clips created by the import. */
+export interface ExternalSeparatedStemImportResult {
+  trackIds: number[];
+  clipIds: number[];
+}
+
 /**
  * Marker kind ordinals. Mirrors `SonareMarkerKind` in `src/sonare_c_types.h`;
  * the values are part of the ABI and must not be renumbered.
@@ -53,17 +76,51 @@ export interface ProjectMarker {
   keyMinor?: boolean;
 }
 
+/** Read-only stored project track returned by {@link Project.trackByIndex}. */
+export interface ProjectTrack {
+  id: number;
+  kind: number;
+  midiDestinationId: number;
+  gain: number;
+  pan: number;
+  mute: boolean;
+  solo: boolean;
+  name: string;
+}
+
+/** Read-only stored project clip returned by {@link Project.clipByIndex}. */
+export interface ProjectClip {
+  id: number;
+  trackId: number;
+  sourceId: number;
+  sourceKind: number;
+  startPpq: number;
+  lengthPpq: number;
+  sourceOffsetPpq: number;
+  gain: number;
+  loopMode: number;
+  loopLengthPpq: number;
+}
+
+/** Read-only stored project source returned by {@link Project.sourceByIndex}. */
+export interface ProjectSource {
+  id: number;
+  kind: number;
+  channelCount: number;
+  storageHandleId: number;
+  sampleRateHint: number;
+  nameOrUri: string;
+  /** Owning content hash for audio sources; empty for MIDI sources. */
+  contentHash: string;
+  /** External source-separation role for audio sources; empty for MIDI sources. */
+  externalStemRole: string;
+}
+
+/** Names accepted by the minimal built-in oscillator synth. */
+export const BUILTIN_SYNTH_WAVEFORMS = ['sine', 'saw', 'sawtooth', 'square', 'triangle'] as const;
+
 /** Oscillator waveform for the built-in synth. */
-export type BuiltinSynthWaveform =
-  | 'sine'
-  | 'saw'
-  | 'sawtooth'
-  | 'square'
-  | 'triangle'
-  | 0
-  | 1
-  | 2
-  | 3;
+export type BuiltinSynthWaveform = (typeof BUILTIN_SYNTH_WAVEFORMS)[number] | 0 | 1 | 2 | 3;
 
 /**
  * Built-in synth patch + MIDI routing for
@@ -111,6 +168,8 @@ export interface Sf2InstrumentConfig {
   gain?: number;
   /** Max simultaneous voices (0 => 48, clamped to [1, 64]). */
   polyphony?: number;
+  /** Prefer dedicated physical models for covered melodic GM programs. Defaults to false; drums stay SF2-first. */
+  preferModelForModeledFamilies?: boolean;
 }
 
 /** Source backend a resolved MIDI program renders through. */
@@ -198,6 +257,7 @@ export const SYNTH_MOD_DESTINATIONS = [
 export interface SynthEnumTables {
   engineModes: string[];
   waveforms: string[];
+  builtinWaveforms: string[];
   filterModels: string[];
   filterOutputs: string[];
   bodyTypes: string[];
@@ -258,6 +318,8 @@ export interface SynthPatch {
    * `(destination_id, patch)` bindings instead. Defaults to `0`.
    */
   destinationId?: number;
+  /** Resolve MIDI channels from incoming GM bank/program changes; defaults to false. */
+  useGmPrograms?: boolean;
   /** Base preset name (see {@link synthPresetNames}); omit for the init patch. */
   preset?: string;
   engineMode?: SynthEngineMode | number;
@@ -312,8 +374,11 @@ export type ProjectFadeCurve =
   | 'equal-power'
   | 'equal_power'
   | 'equalPower'
+  | 'equalpower'
   | 'exponential'
+  | 'exp'
   | 'logarithmic'
+  | 'log'
   | 0
   | 1
   | 2
@@ -389,12 +454,34 @@ export interface ProjectAutomationPoint {
   curve?: ProjectAutomationCurve;
 }
 
+/**
+ * Persistent target classification for an automation lane.
+ *
+ * The numeric ordinals mirror `SonareAutomationTargetKind`; the string names
+ * are the public WASM spellings accepted by the project facade.
+ */
+export const AutomationTargetKind = {
+  opaque: 0,
+  trackFaderDb: 1,
+  trackPan: 2,
+} as const;
+
+/** Accepted automation target kind name or ABI ordinal. */
+export type ProjectAutomationTargetKind = 'opaque' | 'track-fader-db' | 'track-pan' | 0 | 1 | 2;
+
+/** Numeric aliases matching the C-ABI enum names. */
+export const PROJECT_AUTOMATION_TARGET_OPAQUE = AutomationTargetKind.opaque;
+export const PROJECT_AUTOMATION_TARGET_TRACK_FADER_DB = AutomationTargetKind.trackFaderDb;
+export const PROJECT_AUTOMATION_TARGET_TRACK_PAN = AutomationTargetKind.trackPan;
+
 /** Automation-lane descriptor for {@link Project.addAutomationLane}. */
 export interface ProjectAutomationLaneDesc {
-  /** Host-defined id of the parameter the lane drives. */
+  /** Host-defined, non-zero id of the parameter the lane drives (zero is reserved). */
   targetParamId: number;
   /** Breakpoints (stored verbatim). */
   points: ReadonlyArray<ProjectAutomationPoint>;
+  /** Optional persistent target classification; omission retains the legacy opaque route. */
+  targetKind?: ProjectAutomationTargetKind;
 }
 
 /** One tempo segment for {@link Project.setTempoSegments}. */
@@ -456,6 +543,22 @@ export interface ProjectChordSymbol {
   modulationBoundary?: boolean;
 }
 
+/** Descriptor accepted by {@link Project.setAssistSidecar}. */
+export interface ProjectAssistSidecarInput {
+  /** Non-empty module id key. */
+  moduleId: string;
+  /** Module-defined schema version. Defaults to `0`. */
+  schemaVersion?: number;
+  /** Target track id (`0` = project scope). Defaults to `0`. */
+  targetTrackId?: number;
+  /** Region start in PPQ. Defaults to `0`. */
+  regionStartPpq?: number;
+  /** Region end in PPQ. Defaults to `0`. */
+  regionEndPpq?: number;
+  /** Opaque module-owned payload bytes. Defaults to an empty payload. */
+  payload?: Uint8Array;
+}
+
 /** Assist sidecar snapshot returned by {@link Project.getAssistSidecar}. */
 export interface ProjectAssistSidecar {
   moduleId: string;