@collabhut/plugin-sdk 0.1.0

package/dist/helpers/note-utils.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Note utility helpers for @collabhut/plugin-sdk.
+ *
+ * All functions are pure and zero-dependency.  Safe to call from a Worker.
+ *
+ * ## MIDI note numbers
+ * Middle C (C4) = MIDI 60.  A4 (concert pitch) = MIDI 69 = 440 Hz.
+ */
+/**
+ * Convert a MIDI note number to its frequency in Hz.
+ *
+ * Uses equal temperament at A4 = 440 Hz.
+ *
+ * @example
+ * noteToHz(69)  // 440
+ * noteToHz(60)  // 261.63 (middle C)
+ * noteToHz(57)  // 220 (A3)
+ */
+export declare function noteToHz(midi: number): number;
+/**
+ * Convert a frequency in Hz to the nearest MIDI note number.
+ *
+ * The result is rounded to the nearest integer.
+ *
+ * @example
+ * hzToNote(440)   // 69
+ * hzToNote(261.63)// 60
+ */
+export declare function hzToNote(hz: number): number;
+/**
+ * Convert a frequency in Hz to a precise (fractional) MIDI note number.
+ *
+ * Useful for pitch detection where you want the exact pitch, not just the
+ * nearest semitone.
+ *
+ * @example
+ * hzToNoteFractional(450) // ~69.39
+ */
+export declare function hzToNoteFractional(hz: number): number;
+/** Note names in order (chromatic, starting from C) */
+declare const NOTE_NAMES: readonly ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+export type NoteName = (typeof NOTE_NAMES)[number];
+/**
+ * Convert a MIDI note number to a human-readable note name with octave.
+ *
+ * @example
+ * midiToName(60)  // "C4"
+ * midiToName(69)  // "A4"
+ * midiToName(57)  // "A3"
+ */
+export declare function midiToName(midi: number): string;
+/**
+ * Convert a note name + octave to a MIDI note number.
+ *
+ * @example
+ * nameToMidi("C", 4)   // 60
+ * nameToMidi("A", 4)   // 69
+ * nameToMidi("A#", 3)  // 58
+ */
+export declare function nameToMidi(note: NoteName, octave: number): number;
+/**
+ * Return the number of semitones between two MIDI note numbers.
+ * Result is signed — positive if `b > a`.
+ *
+ * @example
+ * semitonesBetween(60, 67)  //  7 (perfect fifth up)
+ * semitonesBetween(69, 60)  // -9
+ */
+export declare function semitonesBetween(a: number, b: number): number;
+/**
+ * Transpose a MIDI note by a number of semitones, clamped to 0–127.
+ *
+ * @example
+ * transpose(60, 7)   // 67 (C4 → G4)
+ * transpose(60, -12) // 48 (C4 → C3)
+ */
+export declare function transpose(midi: number, semitones: number): number;
+/**
+ * Convert beats to seconds given a BPM.
+ *
+ * @example
+ * beatsToSeconds(1, 120)  // 0.5
+ * beatsToSeconds(4, 90)   // 2.666...
+ */
+export declare function beatsToSeconds(beats: number, bpm: number): number;
+/**
+ * Convert seconds to beats given a BPM.
+ *
+ * @example
+ * secondsToBeats(0.5, 120) // 1
+ * secondsToBeats(2, 90)    // 3
+ */
+export declare function secondsToBeats(seconds: number, bpm: number): number;
+/**
+ * Convert a linear gain value (0–∞) to decibels.
+ * Returns `-Infinity` for gain = 0.
+ *
+ * @example
+ * gainToDb(1)   // 0
+ * gainToDb(0.5) // -6.02
+ */
+export declare function gainToDb(gain: number): number;
+/**
+ * Convert decibels to a linear gain value.
+ *
+ * @example
+ * dbToGain(0)  // 1
+ * dbToGain(-6) // ~0.5012
+ */
+export declare function dbToGain(db: number): number;
+/**
+ * Clamp a value between a minimum and maximum.
+ *
+ * @example
+ * clamp(1.5, 0, 1)  // 1
+ * clamp(-0.5, 0, 1) // 0
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Linear interpolation between two values.
+ *
+ * @param t  Blend factor, 0–1
+ * @example
+ * lerp(0, 100, 0.5) // 50
+ */
+export declare function lerp(a: number, b: number, t: number): number;
+export {};
+//# sourceMappingURL=note-utils.d.ts.map

package/dist/helpers/note-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"note-utils.d.ts","sourceRoot":"","sources":["../../src/helpers/note-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,uDAAuD;AACvD,QAAA,MAAM,UAAU,4EAA6E,CAAA;AAE7F,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAElD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5D"}

package/dist/helpers/note-utils.js

@@ -0,0 +1,155 @@
+/**
+ * Note utility helpers for @collabhut/plugin-sdk.
+ *
+ * All functions are pure and zero-dependency.  Safe to call from a Worker.
+ *
+ * ## MIDI note numbers
+ * Middle C (C4) = MIDI 60.  A4 (concert pitch) = MIDI 69 = 440 Hz.
+ */
+/**
+ * Convert a MIDI note number to its frequency in Hz.
+ *
+ * Uses equal temperament at A4 = 440 Hz.
+ *
+ * @example
+ * noteToHz(69)  // 440
+ * noteToHz(60)  // 261.63 (middle C)
+ * noteToHz(57)  // 220 (A3)
+ */
+export function noteToHz(midi) {
+    return 440 * 2 ** ((midi - 69) / 12);
+}
+/**
+ * Convert a frequency in Hz to the nearest MIDI note number.
+ *
+ * The result is rounded to the nearest integer.
+ *
+ * @example
+ * hzToNote(440)   // 69
+ * hzToNote(261.63)// 60
+ */
+export function hzToNote(hz) {
+    return Math.round(69 + 12 * Math.log2(hz / 440));
+}
+/**
+ * Convert a frequency in Hz to a precise (fractional) MIDI note number.
+ *
+ * Useful for pitch detection where you want the exact pitch, not just the
+ * nearest semitone.
+ *
+ * @example
+ * hzToNoteFractional(450) // ~69.39
+ */
+export function hzToNoteFractional(hz) {
+    return 69 + 12 * Math.log2(hz / 440);
+}
+/** Note names in order (chromatic, starting from C) */
+const NOTE_NAMES = ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+/**
+ * Convert a MIDI note number to a human-readable note name with octave.
+ *
+ * @example
+ * midiToName(60)  // "C4"
+ * midiToName(69)  // "A4"
+ * midiToName(57)  // "A3"
+ */
+export function midiToName(midi) {
+    const octave = Math.floor(midi / 12) - 1;
+    const name = NOTE_NAMES[midi % 12];
+    return `${name}${octave}`;
+}
+/**
+ * Convert a note name + octave to a MIDI note number.
+ *
+ * @example
+ * nameToMidi("C", 4)   // 60
+ * nameToMidi("A", 4)   // 69
+ * nameToMidi("A#", 3)  // 58
+ */
+export function nameToMidi(note, octave) {
+    return NOTE_NAMES.indexOf(note) + (octave + 1) * 12;
+}
+/**
+ * Return the number of semitones between two MIDI note numbers.
+ * Result is signed — positive if `b > a`.
+ *
+ * @example
+ * semitonesBetween(60, 67)  //  7 (perfect fifth up)
+ * semitonesBetween(69, 60)  // -9
+ */
+export function semitonesBetween(a, b) {
+    return b - a;
+}
+/**
+ * Transpose a MIDI note by a number of semitones, clamped to 0–127.
+ *
+ * @example
+ * transpose(60, 7)   // 67 (C4 → G4)
+ * transpose(60, -12) // 48 (C4 → C3)
+ */
+export function transpose(midi, semitones) {
+    return Math.max(0, Math.min(127, midi + semitones));
+}
+/**
+ * Convert beats to seconds given a BPM.
+ *
+ * @example
+ * beatsToSeconds(1, 120)  // 0.5
+ * beatsToSeconds(4, 90)   // 2.666...
+ */
+export function beatsToSeconds(beats, bpm) {
+    return (beats / bpm) * 60;
+}
+/**
+ * Convert seconds to beats given a BPM.
+ *
+ * @example
+ * secondsToBeats(0.5, 120) // 1
+ * secondsToBeats(2, 90)    // 3
+ */
+export function secondsToBeats(seconds, bpm) {
+    return (seconds * bpm) / 60;
+}
+/**
+ * Convert a linear gain value (0–∞) to decibels.
+ * Returns `-Infinity` for gain = 0.
+ *
+ * @example
+ * gainToDb(1)   // 0
+ * gainToDb(0.5) // -6.02
+ */
+export function gainToDb(gain) {
+    if (gain <= 0)
+        return -Infinity;
+    return 20 * Math.log10(gain);
+}
+/**
+ * Convert decibels to a linear gain value.
+ *
+ * @example
+ * dbToGain(0)  // 1
+ * dbToGain(-6) // ~0.5012
+ */
+export function dbToGain(db) {
+    return 10 ** (db / 20);
+}
+/**
+ * Clamp a value between a minimum and maximum.
+ *
+ * @example
+ * clamp(1.5, 0, 1)  // 1
+ * clamp(-0.5, 0, 1) // 0
+ */
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/**
+ * Linear interpolation between two values.
+ *
+ * @param t  Blend factor, 0–1
+ * @example
+ * lerp(0, 100, 0.5) // 50
+ */
+export function lerp(a, b, t) {
+    return a + (b - a) * t;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { PluginManifest, PluginType, PluginPricing, SemVer, PluginAuthor } from "./types/manifest";
+export type { PluginParam, RangeParam, BoolParam, ChoiceParam, ParamCurve, ParamValues } from "./types/parameters";
+export type { PluginContext, InstrumentContext } from "./types/context";
+export type { AudioEffectIO, AudioEffectFactory, AudioEffectModule, } from "./types/audio-effect";
+export type { MidiEvent, MidiEventType, MidiNoteOnEvent, MidiNoteOffEvent, MidiControlChangeEvent, MidiPitchBendEvent, MidiAftertouchEvent, MidiPolyAftertouchEvent, MidiProgramChangeEvent, MidiEffectPlugin, MidiEffectFactory, MidiEffectModule, } from "./types/midi-effect";
+export type { InstrumentVoice, InstrumentPlugin, InstrumentFactory, InstrumentModule, } from "./types/instrument";
+export type { EqBand, EqBandType, VocalEqSettings, VocalCompressorSettings, VocalDeEsserSettings, VocalSaturationSettings, VocalPitchCorrectionSettings, VocalChorusSettings, VocalReverbSettings, VocalDelaySettings, VocalPreset, VocalPresetModule, } from "./types/vocal-preset";
+export type { UniformType, ShaderUniform, ShaderDefinition, ShaderModule, } from "./types/shader";
+export type { CollaborationAccess, LicenseToken, LicenseGranted, LicenseDenied, LicenseCheckResult, LicenseChecker, } from "./types/licensing";
+export type { HostToPluginMessage, HostToPluginExtended, PluginToHostEvent, PluginInitMessage, PluginParamsUpdateMessage, PluginProcessMessage, PluginMidiMessage, PluginNoteOnMessage, PluginNoteOffMessage, PluginDisposeMessage, PluginReadyEvent, PluginAudioOutputEvent, PluginMidiOutputEvent, PluginErrorEvent, PluginFetchRequestEvent, PluginFetchResponseMessage, } from "./types/events";
+export { noteToHz, hzToNote, hzToNoteFractional, midiToName, nameToMidi, semitonesBetween, transpose, beatsToSeconds, secondsToBeats, gainToDb, dbToGain, clamp, lerp, } from "./helpers/note-utils";
+export type { NoteName } from "./helpers/note-utils";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACvG,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAClH,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAGvE,YAAY,EACR,aAAa,EACb,kBAAkB,EAClB,iBAAiB,GACpB,MAAM,sBAAsB,CAAA;AAG7B,YAAY,EACR,SAAS,EACT,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACnB,MAAM,qBAAqB,CAAA;AAG5B,YAAY,EACR,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,GACnB,MAAM,oBAAoB,CAAA;AAG3B,YAAY,EACR,MAAM,EACN,UAAU,EACV,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,4BAA4B,EAC5B,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,GACpB,MAAM,sBAAsB,CAAA;AAG7B,YAAY,EACR,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,YAAY,GACf,MAAM,gBAAgB,CAAA;AAGvB,YAAY,EACR,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,cAAc,GACjB,MAAM,mBAAmB,CAAA;AAG1B,YAAY,EACR,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,yBAAyB,EACzB,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,0BAA0B,GAC7B,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EACH,QAAQ,EACR,QAAQ,EACR,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,IAAI,GACP,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+// Helpers (runtime values, not just types)
+export { noteToHz, hzToNote, hzToNoteFractional, midiToName, nameToMidi, semitonesBetween, transpose, beatsToSeconds, secondsToBeats, gainToDb, dbToGain, clamp, lerp, } from "./helpers/note-utils";

package/dist/types/audio-effect.d.ts

@@ -0,0 +1,70 @@
+import type { PluginContext } from "./context";
+import type { PluginParam } from "./parameters";
+import type { PluginManifest } from "./manifest";
+/** The stereo or mono AudioNode pair exposed by an audio-effect plugin */
+export interface AudioEffectIO {
+    /** Plugin receives audio here — connect the host's source to this node */
+    readonly input: AudioNode;
+    /** Plugin outputs processed audio from here — host connects this to the chain */
+    readonly output: AudioNode;
+    /**
+     * Optional side-chain input for compressors, gates, etc.
+     * Declare `sidechain: true` in the manifest to activate this input.
+     */
+    readonly sidechain?: AudioNode;
+    /**
+     * Named AudioParams made available for automation.
+     * Keys must match the `id` fields of `manifest.params` entries.
+     * If omitted, the DAW uses param-polling via `getParamValue()` instead.
+     */
+    readonly automationTargets?: Readonly<Record<string, AudioParam>>;
+}
+/**
+ * Audio effect plugin interface.
+ *
+ * Return an `AudioEffectIO` from your factory function.  The host wires
+ * `input` and `output` into the track processing chain automatically.
+ *
+ * @example
+ * ```ts
+ * import type { AudioEffectFactory, PluginContext } from "@collabhut/plugin-sdk"
+ *
+ * export const manifest = {
+ *     id: "com.myorg.warm-compressor",
+ *     // ...
+ *     params: [
+ *         { type: "range", id: "threshold", label: "Threshold",
+ *           min: -60, max: 0, default: -18, unit: "dB" },
+ *         { type: "range", id: "ratio", label: "Ratio",
+ *           min: 1, max: 20, default: 4, decimals: 1 },
+ *     ],
+ * } satisfies PluginManifest
+ *
+ * export const factory: AudioEffectFactory<typeof manifest.params> =
+ *     (context, params) => {
+ *         const compressor = context.audioContext.createDynamicsCompressor()
+ *         compressor.threshold.value = params.threshold
+ *         compressor.ratio.value     = params.ratio
+ *         return {
+ *             input:  compressor,
+ *             output: compressor,
+ *             automationTargets: {
+ *                 threshold: compressor.threshold,
+ *                 ratio:     compressor.ratio,
+ *             },
+ *         }
+ *     }
+ * ```
+ */
+export type AudioEffectFactory<TParams extends ReadonlyArray<PluginParam> = ReadonlyArray<PluginParam>> = (context: PluginContext, params: Readonly<Record<string, number | boolean | string>>, manifest: PluginManifest) => AudioEffectIO;
+/**
+ * Full audio-effect module shape.
+ * Your plugin file must export both `manifest` and `factory`.
+ */
+export interface AudioEffectModule {
+    readonly manifest: PluginManifest & {
+        readonly type: "audio-effect";
+    };
+    readonly factory: AudioEffectFactory;
+}
+//# sourceMappingURL=audio-effect.d.ts.map

package/dist/types/audio-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-effect.d.ts","sourceRoot":"","sources":["../../src/types/audio-effect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,kBAAkB,CAC1B,OAAO,SAAS,aAAa,CAAC,WAAW,CAAC,GAAG,aAAa,CAAC,WAAW,CAAC,IACvE,CACA,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC,EAC3D,QAAQ,EAAE,cAAc,KACvB,aAAa,CAAA;AAElB;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;KAAE,CAAA;IACrE,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CACvC"}

package/dist/types/audio-effect.js

@@ -0,0 +1 @@
+export {};

package/dist/types/context.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime context provided to every plugin factory.
+ *
+ * The context object is the plugin's only gateway to the host environment.
+ * All properties are read-only — plugins cannot modify host state directly.
+ */
+export interface PluginContext {
+    /** Web Audio API context.  Use this to create nodes and schedule events. */
+    readonly audioContext: AudioContext;
+    /**
+     * Current sample rate in Hz.
+     * Always equal to `audioContext.sampleRate`.
+     */
+    readonly sampleRate: number;
+    /**
+     * Current tempo in beats per minute.
+     * Reactive: you should re-read this in every `process()` call for DAW sync.
+     */
+    readonly bpm: number;
+    /** Current transport position in beats (fractions of a beat allowed) */
+    readonly positionBeats: number;
+    /** `true` when the DAW transport is rolling */
+    readonly isPlaying: boolean;
+    /**
+     * Fetch a resource from CollabHut CDN.
+     * Only HTTPS URLs on `cdn.collabhut.com` are allowed.
+     * Arbitrary network access is blocked inside the plugin sandbox.
+     */
+    fetchAsset(url: string): Promise<ArrayBuffer>;
+}
+/**
+ * Runtime context provided exclusively to instrument plugins.
+ * Extends PluginContext with polyphonic voice management.
+ */
+export interface InstrumentContext extends PluginContext {
+    /** Maximum number of simultaneous voices the host will attempt */
+    readonly maxPolyphony: number;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/types/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/types/context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CAChD;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACpD,kEAAkE;IAClE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAChC"}

package/dist/types/context.js

@@ -0,0 +1 @@
+export {};

package/dist/types/events.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Typed message protocol for plugin ↔ host communication.
+ *
+ * Plugins execute inside a sandboxed Web Worker.  All communication with the
+ * host DAW happens via `postMessage` with these discriminated-union types.
+ *
+ * ## Architecture
+ * ```
+ * Host (main thread)                Plugin (Worker)
+ *       │                                  │
+ *       │──── HostToPluginMessage ────────►│  host → plugin commands
+ *       │◄─── PluginToHostMessage ─────────│  plugin → host events
+ * ```
+ *
+ * Plugin authors **do not** import or use these types directly — they are
+ * consumed by the DAW runtime.  They are documented here for those building
+ * plugin host environments or tooling.
+ */
+/** Initialize the plugin.  Sent once immediately after the Worker starts. */
+export interface PluginInitMessage {
+    readonly type: "init";
+    /** Transferable SharedArrayBuffer for lock-free transport state reads */
+    readonly transportBuffer: SharedArrayBuffer;
+    /** Plugin parameter initial values */
+    readonly params: Readonly<Record<string, number | boolean | string>>;
+    readonly sampleRate: number;
+    readonly blockSize: number;
+}
+/** Update one or more parameter values */
+export interface PluginParamsUpdateMessage {
+    readonly type: "params-update";
+    readonly params: Readonly<Record<string, number | boolean | string>>;
+}
+/** Process one audio block (audio-effect plugins only) */
+export interface PluginProcessMessage {
+    readonly type: "process";
+    /** Interleaved float32 samples, transferred (zero-copy) */
+    readonly inputBuffer: Float32Array;
+    readonly numChannels: number;
+    readonly numFrames: number;
+}
+/** Send MIDI events for this block (midi-effect / instrument plugins) */
+export interface PluginMidiMessage {
+    readonly type: "midi";
+    readonly events: ReadonlyArray<{
+        readonly channel: number;
+        readonly beatTime: number;
+        readonly data: readonly number[];
+    }>;
+}
+/** Trigger note on (instrument plugins only) */
+export interface PluginNoteOnMessage {
+    readonly type: "note-on";
+    readonly note: number;
+    readonly velocity: number;
+    readonly time: number;
+}
+/** Trigger note off (instrument plugins only) */
+export interface PluginNoteOffMessage {
+    readonly type: "note-off";
+    readonly note: number;
+    readonly velocity: number;
+    readonly time: number;
+}
+/** Dispose and terminate the plugin */
+export interface PluginDisposeMessage {
+    readonly type: "dispose";
+}
+export type HostToPluginMessage = PluginInitMessage | PluginParamsUpdateMessage | PluginProcessMessage | PluginMidiMessage | PluginNoteOnMessage | PluginNoteOffMessage | PluginDisposeMessage;
+/** Plugin is ready after init */
+export interface PluginReadyEvent {
+    readonly type: "ready";
+    readonly manifestId: string;
+    readonly apiVersion: string;
+}
+/** Processed audio output (audio-effect plugins) */
+export interface PluginAudioOutputEvent {
+    readonly type: "audio-output";
+    /** Interleaved float32 samples, transferred (zero-copy) */
+    readonly outputBuffer: Float32Array;
+    readonly numChannels: number;
+    readonly numFrames: number;
+}
+/** MIDI output events (midi-effect plugins) */
+export interface PluginMidiOutputEvent {
+    readonly type: "midi-output";
+    readonly events: ReadonlyArray<{
+        readonly channel: number;
+        readonly beatTime: number;
+        readonly data: readonly number[];
+    }>;
+}
+/** Plugin encountered an error */
+export interface PluginErrorEvent {
+    readonly type: "error";
+    /** Human-readable description of the error */
+    readonly message: string;
+    /** Optional stack trace (stripped in production builds) */
+    readonly stack?: string;
+}
+/** Plugin requests to fetch a CDN asset (host performs the fetch and replies) */
+export interface PluginFetchRequestEvent {
+    readonly type: "fetch-request";
+    readonly requestId: string;
+    /** Must be a URL on cdn.collabhut.com — rejected otherwise */
+    readonly url: string;
+}
+/** Host response to a `fetch-request` */
+export interface PluginFetchResponseMessage {
+    readonly type: "fetch-response";
+    readonly requestId: string;
+    readonly ok: boolean;
+    /** Transferred ArrayBuffer on success */
+    readonly data?: ArrayBuffer;
+    readonly error?: string;
+}
+export type PluginToHostEvent = PluginReadyEvent | PluginAudioOutputEvent | PluginMidiOutputEvent | PluginErrorEvent | PluginFetchRequestEvent;
+export type HostToPluginExtended = HostToPluginMessage | PluginFetchResponseMessage;
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"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"}

package/dist/types/events.js

@@ -0,0 +1,19 @@
+/**
+ * Typed message protocol for plugin ↔ host communication.
+ *
+ * Plugins execute inside a sandboxed Web Worker.  All communication with the
+ * host DAW happens via `postMessage` with these discriminated-union types.
+ *
+ * ## Architecture
+ * ```
+ * Host (main thread)                Plugin (Worker)
+ *       │                                  │
+ *       │──── HostToPluginMessage ────────►│  host → plugin commands
+ *       │◄─── PluginToHostMessage ─────────│  plugin → host events
+ * ```
+ *
+ * Plugin authors **do not** import or use these types directly — they are
+ * consumed by the DAW runtime.  They are documented here for those building
+ * plugin host environments or tooling.
+ */
+export {};

package/dist/types/instrument.d.ts

@@ -0,0 +1,83 @@
+import type { InstrumentContext } from "./context";
+import type { MidiEvent } from "./midi-effect";
+import type { PluginManifest } from "./manifest";
+/**
+ * An individual voice instance returned by `noteOn`.
+ *
+ * The DAW keeps a reference per active voice and calls `stop` when the
+ * corresponding note-off arrives (or when voices are stolen for polyphony).
+ */
+export interface InstrumentVoice {
+    /** AudioNode carrying this voice's audio signal — host connects it to the track bus */
+    readonly output: AudioNode;
+    /**
+     * Stop (release) the voice.
+     * @param velocity  Release velocity, 0–127
+     * @param time      AudioContext time at which the release should begin
+     */
+    stop(velocity: number, time: number): void;
+    /**
+     * Kill the voice immediately with no release tail.
+     * Used for voice stealing or when the project stops.
+     */
+    kill(): void;
+}
+/**
+ * Polyphonic instrument plugin.
+ *
+ * The DAW calls `noteOn` for every note and stores the returned voice.
+ * When the note ends it calls `voice.stop()`.  If polyphony is exceeded it
+ * calls `voice.kill()` on the oldest voice before starting a new one.
+ *
+ * @example
+ * ```ts
+ * import type { InstrumentFactory, InstrumentVoice } from "@collabhut/plugin-sdk"
+ *
+ * export const factory: InstrumentFactory = (context) => ({
+ *     noteOn(note, velocity, time) {
+ *         const osc = context.audioContext.createOscillator()
+ *         const gain = context.audioContext.createGain()
+ *         osc.frequency.value = 440 * 2 ** ((note - 69) / 12)
+ *         gain.gain.setValueAtTime(velocity / 127, time)
+ *         osc.connect(gain)
+ *         osc.start(time)
+ *         return {
+ *             output: gain,
+ *             stop(_vel, releaseTime) {
+ *                 gain.gain.setTargetAtTime(0, releaseTime, 0.1)
+ *                 osc.stop(releaseTime + 0.5)
+ *             },
+ *             kill() { osc.stop(); gain.disconnect() },
+ *         }
+ *     },
+ *     onMidi(_event) {},
+ *     dispose() {},
+ * })
+ * ```
+ */
+export interface InstrumentPlugin {
+    /**
+     * Start a new voice for the given MIDI note.
+     * @param note      MIDI note number (0–127)
+     * @param velocity  Attack velocity (0–127)
+     * @param time      AudioContext time for the note start
+     * @returns A voice object the DAW will manage
+     */
+    noteOn(note: number, velocity: number, time: number): InstrumentVoice;
+    /**
+     * Handle non-note MIDI events (CC, pitch bend, aftertouch, etc.).
+     * Called alongside the voice lifecycle — useful for mod-wheel, portamento, etc.
+     */
+    onMidi(event: MidiEvent): void;
+    /** Called when the plugin is removed or the project closes */
+    dispose(): void;
+}
+export type InstrumentFactory = (context: InstrumentContext, params: Readonly<Record<string, number | boolean | string>>, manifest: PluginManifest) => InstrumentPlugin;
+/** Full instrument module shape */
+export interface InstrumentModule {
+    readonly manifest: PluginManifest & {
+        readonly type: "instrument";
+    };
+    readonly factory: InstrumentFactory;
+}
+//# sourceMappingURL=instrument.d.ts.map

package/dist/types/instrument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrument.d.ts","sourceRoot":"","sources":["../../src/types/instrument.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;IAC1B;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1C;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;IACrE;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAAA;IAC9B,8DAA8D;IAC9D,OAAO,IAAI,IAAI,CAAA;CAClB;AAED,MAAM,MAAM,iBAAiB,GAAG,CAC5B,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC,EAC3D,QAAQ,EAAE,cAAc,KACvB,gBAAgB,CAAA;AAErB,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;KAAE,CAAA;IACnE,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAA;CACtC"}