@collabhut/plugin-sdk 0.1.0

package/README.md

@@ -0,0 +1,1046 @@
+# @collabhut/plugin-sdk
+
+> Official TypeScript SDK for building CollabDAW plugins.
+
+The `@collabhut/plugin-sdk` package gives you everything you need to create,
+type-check, and publish plugins for [CollabDAW](https://collabhut.com) — the
+collaborative music production environment.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Plugin types](#plugin-types)
+3. [Installation](#installation)
+4. [Project setup](#project-setup)
+5. [Getting started — Hello World audio effect](#getting-started--hello-world-audio-effect)
+6. [Audio effect plugins](#audio-effect-plugins)
+7. [MIDI effect plugins](#midi-effect-plugins)
+8. [Instrument plugins](#instrument-plugins)
+9. [Vocal preset plugins](#vocal-preset-plugins)
+10. [Shader plugins & ShaderToy compatibility](#shader-plugins--shadertoy-compatibility)
+11. [Parameter system](#parameter-system)
+12. [Note utilities](#note-utilities)
+13. [Security & sandbox model](#security--sandbox-model)
+14. [Licensing & verification](#licensing--verification)
+15. [Collaboration access rules](#collaboration-access-rules)
+16. [Publishing to the CollabHut Marketplace](#publishing-to-the-collabhut-marketplace)
+17. [Plugin IDE & .dawplugin files](#plugin-ide--dawplugin-files)
+18. [API reference](#api-reference)
+19. [Frequently asked questions](#frequently-asked-questions)
+
+---
+
+## Overview
+
+Plugins for CollabDAW are **TypeScript ES modules** that export a `manifest`
+object and a factory function (or, for vocal presets and shaders, a data
+object).  They are compiled to a signed bundle by the CollabHut build service
+and hosted on the CollabHut CDN.
+
+```
+your-plugin/
+  src/
+    index.ts      ← exports manifest + factory (or preset / shader)
+  package.json
+  tsconfig.json
+```
+
+Key design decisions:
+
+| Property | Detail |
+|---|---|
+| **Language** | TypeScript 5+ (strict mode required) |
+| **Runtime** | Sandboxed Web Worker inside CollabDAW |
+| **Audio API** | Web Audio API (`AudioContext`) — injected via `PluginContext` |
+| **Network** | Only `cdn.collabhut.com` — via `context.fetchAsset()` |
+| **No DOM access** | `document`, `window`, `localStorage` are unmounted |
+| **Licensing** | Server-side only — no user key-entry friction |
+
+---
+
+## Plugin types
+
+| Type | `manifest.type` | What it does |
+|---|---|---|
+| Audio Effect | `"audio-effect"` | Processes a live audio stream (EQ, reverb, compressor…) |
+| MIDI Effect | `"midi-effect"` | Transforms or generates MIDI events (arpeggiator, chord generator…) |
+| Instrument | `"instrument"` | Synthesises audio from MIDI notes (synth, sampler…) |
+| Vocal Preset | `"vocal-preset"` | Configures CollabDAW's built-in vocal chain (static data, no DSP code) |
+| Shader | `"shader"` | GLSL fragment shader displayed in the ShaderToy panel |
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev @collabhut/plugin-sdk
+# or
+pnpm add -D @collabhut/plugin-sdk
+```
+
+The package is **type-only at runtime** — all exports are TypeScript
+interfaces.  Helper functions (`noteToHz`, `gainToDb`, etc.) are the only
+compiled JavaScript.
+
+---
+
+## Project setup
+
+### `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationDir": "dist",
+    "sourceMap": true
+  },
+  "include": ["src"]
+}
+```
+
+> `"DOM"` is required so TypeScript knows about `AudioContext`, `AudioNode`,
+> `Worker`, and `SharedArrayBuffer`.
+
+### `package.json`
+
+```json
+{
+  "name": "@your-org/my-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "@collabhut/plugin-sdk": "^0.1.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+---
+
+## Getting started — Hello World audio effect
+
+This is the minimal complete plugin.  It creates a `GainNode` that lets the
+user control the volume from within CollabDAW.
+
+```ts
+// src/index.ts
+import type {
+    AudioEffectModule,
+    AudioEffectFactory,
+    PluginManifest,
+} from "@collabhut/plugin-sdk"
+
+export const manifest = {
+    id: "com.myorg.hello-gain",
+    name: "Hello Gain",
+    version: "1.0.0",
+    type: "audio-effect",
+    description: "A simple gain control — the Hello World of CollabDAW plugins.",
+    author: {
+        name: "My Org",
+        url: "https://myorg.com",
+    },
+    params: [
+        {
+            type: "range",
+            id: "gain",
+            label: "Gain",
+            min: 0,
+            max: 2,
+            default: 1,
+            decimals: 2,
+        },
+    ],
+    pricing: "free",
+    minApiVersion: "0.1.0",
+} satisfies PluginManifest
+
+const factory: AudioEffectFactory<typeof manifest.params> = (context, params) => {
+    const gain = context.audioContext.createGain()
+    gain.gain.value = params.gain as number
+    return {
+        input: gain,
+        output: gain,
+        automationTargets: { gain: gain.gain },
+    }
+}
+
+const mod: AudioEffectModule = { manifest, factory }
+export default mod
+```
+
+Build it:
+
+```bash
+pnpm build
+```
+
+---
+
+## Audio effect plugins
+
+An audio effect plugin creates a **Web Audio subgraph** and exposes input/output
+nodes.  The DAW connects your plugin into the track's processing chain.
+
+```
+Track source → [your input node] → [your DSP graph] → [your output node] → track bus
+```
+
+### Stereo compressor example
+
+```ts
+// src/index.ts
+import type { AudioEffectModule, AudioEffectFactory, PluginManifest } from "@collabhut/plugin-sdk"
+
+export const manifest = {
+    id: "com.myorg.stereo-compressor",
+    name: "Stereo Compressor",
+    version: "1.0.0",
+    type: "audio-effect",
+    description: "Classic stereo dynamics compressor with optional side-chain.",
+    author: { name: "My Org" },
+    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 },
+        { type: "range", id: "attack",    label: "Attack",    min: 0,   max: 1,  default: 0.003, unit: "s", decimals: 3, curve: "log" },
+        { type: "range", id: "release",   label: "Release",   min: 0,   max: 2,  default: 0.15,  unit: "s", decimals: 2, curve: "log" },
+        { type: "range", id: "makeUpGain",label: "Make-up",   min: 0,   max: 24, default: 6,  unit: "dB" },
+        { type: "bool",  id: "softClip",  label: "Soft Clip",              default: false },
+    ],
+    pricing: "paid",
+    minApiVersion: "0.1.0",
+} satisfies PluginManifest
+
+const factory: AudioEffectFactory<typeof manifest.params> = (context, params) => {
+    const comp = context.audioContext.createDynamicsCompressor()
+    comp.threshold.value = params.threshold as number
+    comp.ratio.value     = params.ratio as number
+    comp.attack.value    = params.attack as number
+    comp.release.value   = params.release as number
+
+    const makeUp = context.audioContext.createGain()
+    makeUp.gain.value = 10 ** ((params.makeUpGain as number) / 20)
+
+    comp.connect(makeUp)
+
+    return {
+        input: comp,
+        output: makeUp,
+        automationTargets: {
+            threshold: comp.threshold,
+            ratio:     comp.ratio,
+            attack:    comp.attack,
+            release:   comp.release,
+        },
+    }
+}
+
+const mod: AudioEffectModule = { manifest, factory }
+export default mod
+```
+
+### Fetching an impulse response for a convolution reverb
+
+```ts
+const factory: AudioEffectFactory = async (context, _params) => {
+    // Only cdn.collabhut.com URLs are permitted
+    const irBuffer = await context.fetchAsset(
+        "https://cdn.collabhut.com/ir/hall-large.wav"
+    )
+    const decoded  = await context.audioContext.decodeAudioData(irBuffer)
+
+    const convolver = context.audioContext.createConvolver()
+    convolver.buffer = decoded
+
+    return { input: convolver, output: convolver }
+}
+```
+
+> `context.fetchAsset()` throws `TypeError` for any URL not on
+> `cdn.collabhut.com`.  The restriction is enforced in the sandbox.
+
+---
+
+## MIDI effect plugins
+
+MIDI effects transform or generate MIDI events on a per-block basis.
+Your plugin receives the incoming events and returns the processed list.
+
+### Arpeggiator example
+
+```ts
+// src/index.ts
+import type {
+    MidiEffectModule,
+    MidiEffectFactory,
+    MidiEvent,
+    MidiNoteOnEvent,
+    PluginManifest,
+} from "@collabhut/plugin-sdk"
+import { transpose } from "@collabhut/plugin-sdk"
+
+export const manifest = {
+    id: "com.myorg.simple-arp",
+    name: "Simple Arpeggiator",
+    version: "1.0.0",
+    type: "midi-effect",
+    description: "Fans held notes into an up-down arpeggio pattern.",
+    author: { name: "My Org" },
+    params: [
+        {
+            type: "choice",
+            id: "pattern",
+            label: "Pattern",
+            choices: ["up", "down", "up-down"],
+            default: "up",
+        },
+    ],
+    pricing: "free",
+    minApiVersion: "0.1.0",
+} satisfies PluginManifest
+
+const factory: MidiEffectFactory = (_context, params) => {
+    const heldNotes: MidiNoteOnEvent[] = []
+
+    return {
+        process(events) {
+            const out: MidiEvent[] = []
+
+            for (const ev of events) {
+                if (ev.type === "note-on") {
+                    heldNotes.push(ev)
+                } else if (ev.type === "note-off") {
+                    const idx = heldNotes.findIndex(n => n.note === ev.note)
+                    if (idx !== -1) heldNotes.splice(idx, 1)
+                }
+                // Emit original event
+                out.push(ev)
+            }
+
+            // Emit transposed copies for each held note based on pattern
+            const pattern = params.pattern as string
+            for (const held of heldNotes) {
+                if (pattern === "up" || pattern === "up-down") {
+                    out.push({ ...held, note: transpose(held.note, 12) })
+                }
+                if (pattern === "up-down") {
+                    out.push({ ...held, note: transpose(held.note, -12) })
+                }
+            }
+
+            return out
+        },
+        dispose() {
+            heldNotes.length = 0
+        },
+    }
+}
+
+const mod: MidiEffectModule = { manifest, factory }
+export default mod
+```
+
+---
+
+## Instrument plugins
+
+Instrument plugins are **polyphonic synthesisers**.  The DAW calls `noteOn()`
+for each MIDI note and stores the returned voice.  When the note ends it calls
+`voice.stop()`.
+
+### Simple sine synth
+
+```ts
+// src/index.ts
+import type { InstrumentModule, InstrumentFactory, InstrumentVoice, PluginManifest } from "@collabhut/plugin-sdk"
+import { noteToHz, dbToGain } from "@collabhut/plugin-sdk"
+
+export const manifest = {
+    id: "com.myorg.sine-synth",
+    name: "Sine Synth",
+    version: "1.0.0",
+    type: "instrument",
+    description: "A pure sine-wave synthesiser with ADSR envelope.",
+    author: { name: "My Org" },
+    params: [
+        { type: "range", id: "attack",  label: "Attack",  min: 0.001, max: 2, default: 0.01,  unit: "s", curve: "log", decimals: 3 },
+        { type: "range", id: "decay",   label: "Decay",   min: 0.001, max: 2, default: 0.1,   unit: "s", curve: "log", decimals: 3 },
+        { type: "range", id: "sustain", label: "Sustain", min: 0,     max: 1, default: 0.7,   decimals: 2 },
+        { type: "range", id: "release", label: "Release", min: 0.001, max: 4, default: 0.3,   unit: "s", curve: "log", decimals: 3 },
+        { type: "range", id: "volume",  label: "Volume",  min: -60,   max: 0, default: -12,   unit: "dB" },
+    ],
+    pricing: "free",
+    minApiVersion: "0.1.0",
+} satisfies PluginManifest
+
+const factory: InstrumentFactory = (context, params) => ({
+    noteOn(note, velocity, time): InstrumentVoice {
+        const { audioContext } = context
+
+        const osc  = audioContext.createOscillator()
+        const gain = audioContext.createGain()
+
+        osc.type                 = "sine"
+        osc.frequency.value      = noteToHz(note)
+        gain.gain.value          = 0
+
+        osc.connect(gain)
+        osc.start(time)
+
+        const velGain  = velocity / 127
+        const maxGain  = dbToGain(params.volume as number) * velGain
+        const attack   = params.attack as number
+        const decay    = params.decay as number
+        const sustain  = params.sustain as number
+        const release  = params.release as number
+
+        // ADSR
+        gain.gain.linearRampToValueAtTime(maxGain, time + attack)
+        gain.gain.linearRampToValueAtTime(maxGain * sustain, time + attack + decay)
+
+        return {
+            output: gain,
+            stop(_vel, releaseTime) {
+                gain.gain.cancelScheduledValues(releaseTime)
+                gain.gain.setValueAtTime(gain.gain.value, releaseTime)
+                gain.gain.linearRampToValueAtTime(0, releaseTime + release)
+                osc.stop(releaseTime + release + 0.01)
+            },
+            kill() {
+                osc.stop()
+                gain.disconnect()
+            },
+        }
+    },
+    onMidi(_ev) {},
+    dispose() {},
+})
+
+const mod: InstrumentModule = { manifest, factory }
+export default mod
+```
+
+---
+
+## Vocal preset plugins
+
+A vocal preset is **only data** — no JavaScript runs at playback time.
+CollabDAW reads the `VocalPreset` object and applies it to the built-in vocal
+engine.  This means vocal presets have:
+
+- **Zero sandbox risk** (no code execution)
+- **No latency penalty**
+- **Instant parameter recall**
+
+```ts
+// src/index.ts
+import type { VocalPresetModule } from "@collabhut/plugin-sdk"
+
+const mod: VocalPresetModule = {
+    manifest: {
+        id: "com.myorg.vintage-tape-vocals",
+        name: "Vintage Tape Vocals",
+        version: "1.0.0",
+        type: "vocal-preset",
+        description: "Warm, slightly compressed vocals with subtle tape saturation.",
+        author: { name: "My Org" },
+        pricing: "paid",
+        minApiVersion: "0.1.0",
+    },
+    preset: {
+        inputGain: 0,
+        outputGain: -2,
+        eq: {
+            enabled: true,
+            bands: [
+                { frequency: 100,   gain: -4,  q: 0.7, type: "highpass" },
+                { frequency: 250,   gain: -2,  q: 1.2, type: "peaking"  },
+                { frequency: 1500,  gain: 2,   q: 1.5, type: "peaking"  },
+                { frequency: 6000,  gain: 3,   q: 0.9, type: "peaking"  },
+                { frequency: 12000, gain: 1.5, q: 0.7, type: "highshelf"},
+            ],
+        },
+        compressor: {
+            enabled: true,
+            threshold: -20,
+            knee: 8,
+            ratio: 4,
+            attack: 0.005,
+            release: 0.12,
+            makeUpGain: 5,
+        },
+        deEsser: { enabled: true, frequency: 7200, threshold: -28, range: 10 },
+        saturation: { enabled: true, drive: 0.15, mix: 0.35 },
+        pitchCorrection: { enabled: false, scale: "chromatic", strength: 0, speed: 0.1 },
+        chorus: { enabled: false, rate: 0.5,  depth: 0.3, delay: 0.02, mix: 0.3 },
+        reverb: { enabled: true,  roomSize: 0.25, damping: 0.75, preDelay: 0.015, mix: 0.18 },
+        delay:  { enabled: false, time: 0.25, feedback: 0.3, filter: 4000, mix: 0.2 },
+    },
+}
+
+export default mod
+```
+
+---
+
+## Shader plugins & ShaderToy compatibility
+
+Shader plugins render a GLSL fragment shader in the **ShaderToy panel** of
+CollabDAW.  They can be static visuals, or they can react to audio in real time.
+
+### Audio-reactive circle shader
+
+```ts
+// src/index.ts
+import type { ShaderModule } from "@collabhut/plugin-sdk"
+
+const mod: ShaderModule = {
+    manifest: {
+        id: "com.myorg.audio-circle",
+        name: "Audio Circle",
+        version: "1.0.0",
+        type: "shader",
+        description: "A circle that pulses with the music.",
+        author: { name: "My Org" },
+        pricing: "free",
+        minApiVersion: "0.1.0",
+        shadertoyCompatible: false,
+    },
+    shader: {
+        glsl: `
+            precision mediump float;
+
+            uniform vec2  uResolution;
+            uniform float uRms;
+            uniform float uBeat;
+
+            void main() {
+                vec2 uv = (gl_FragCoord.xy / uResolution) * 2.0 - 1.0;
+                uv.x *= uResolution.x / uResolution.y;
+
+                float radius = 0.3 + uRms * 0.4;
+                float ring   = smoothstep(radius + 0.01, radius, length(uv));
+                float pulse  = 0.5 + 0.5 * sin(uBeat * 6.2831);
+
+                vec3 col = mix(vec3(0.0, 0.4, 0.8), vec3(0.8, 0.2, 0.5), pulse);
+                gl_FragColor = vec4(col * ring, 1.0);
+            }
+        `,
+        uniforms: [
+            { name: "uResolution", type: "vec2",  source: "resolution" },
+            { name: "uRms",        type: "float", source: "audio-rms"  },
+            { name: "uBeat",       type: "float", source: "beat"       },
+        ],
+    },
+}
+
+export default mod
+```
+
+### ShaderToy port
+
+When `shadertoyCompatible: true`, CollabDAW pre-injects the standard ShaderToy
+uniforms so you can paste ShaderToy code almost as-is.
+
+Pre-injected uniforms (do **not** declare these in `uniforms`):
+
+| ShaderToy name | Type | Source |
+|---|---|---|
+| `iTime` | float | Playback time in seconds |
+| `iResolution` | vec3 | Canvas size (z = pixel ratio) |
+| `iMouse` | vec4 | Mouse position |
+| `iChannel0` | sampler2D | Audio spectrum texture |
+
+```ts
+import type { ShaderModule } from "@collabhut/plugin-sdk"
+
+const mod: ShaderModule = {
+    manifest: {
+        id: "com.myorg.shadertoy-port",
+        name: "Classic Plasma",
+        version: "1.0.0",
+        type: "shader",
+        shadertoyCompatible: true,  // ← enables automatic uniform injection
+        description: "ShaderToy plasma effect ported to CollabDAW.",
+        author: { name: "My Org" },
+        pricing: "free",
+        minApiVersion: "0.1.0",
+    },
+    shader: {
+        // iTime, iResolution, iMouse are injected automatically
+        glsl: `
+            void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+                vec2 uv = fragCoord / iResolution.xy;
+                float t = iTime;
+                vec3 col = 0.5 + 0.5 * cos(t + uv.xyx + vec3(0, 2, 4));
+                fragColor = vec4(col, 1.0);
+            }
+        `,
+    },
+}
+
+export default mod
+```
+
+---
+
+## Parameter system
+
+Parameters appear as knobs, toggles, and dropdowns in the CollabDAW plugin GUI.
+
+### Range parameter (knob / slider)
+
+```ts
+{
+    type: "range",
+    id: "cutoff",        // unique within the plugin, used as key in params object
+    label: "Cutoff",
+    min: 20,
+    max: 20000,
+    default: 1000,
+    unit: "Hz",          // displayed in the tooltip
+    curve: "log",        // "linear" | "log" | "exp"
+    decimals: 0,
+    group: "Filter",     // optional — groups params in the UI
+}
+```
+
+### Bool parameter (toggle)
+
+```ts
+{
+    type: "bool",
+    id: "bypass",
+    label: "Bypass",
+    default: false,
+}
+```
+
+### Choice parameter (dropdown)
+
+```ts
+{
+    type: "choice",
+    id: "filterType",
+    label: "Filter",
+    choices: ["lowpass", "highpass", "bandpass", "notch"],
+    default: "lowpass",
+}
+```
+
+### Type-safe param access
+
+The `params` argument in your factory is typed as
+`Readonly<Record<string, number | boolean | string>>`.  Cast to the concrete
+type within your factory:
+
+```ts
+const cutoff  = params.cutoff  as number   // from a "range" param
+const bypass  = params.bypass  as boolean  // from a "bool" param
+const filter  = params.filterType as string // from a "choice" param
+```
+
+---
+
+## Note utilities
+
+All helpers are pure functions, zero-dependency, and safe to use in Workers.
+
+```ts
+import {
+    noteToHz, hzToNote, hzToNoteFractional,
+    midiToName, nameToMidi,
+    semitonesBetween, transpose,
+    beatsToSeconds, secondsToBeats,
+    gainToDb, dbToGain,
+    clamp, lerp,
+} from "@collabhut/plugin-sdk"
+
+noteToHz(69)            // 440   (A4)
+noteToHz(60)            // 261.63 (C4, middle C)
+hzToNote(440)           // 69
+hzToNoteFractional(450) // 69.39 (fractional for pitch detection)
+midiToName(60)          // "C4"
+midiToName(57)          // "A3"
+nameToMidi("A", 4)      // 69
+transpose(60, 7)        // 67  (C4 → G4, perfect fifth)
+transpose(60, -12)      // 48  (C4 → C3, one octave down)
+semitonesBetween(60, 67)// 7
+
+beatsToSeconds(1, 120)  // 0.5
+secondsToBeats(0.5, 120)// 1
+
+gainToDb(1)             // 0
+gainToDb(0.5)           // -6.02
+dbToGain(0)             // 1
+dbToGain(-6)            // 0.501
+
+clamp(1.5, 0, 1)        // 1
+lerp(0, 100, 0.5)       // 50
+```
+
+---
+
+## Security & sandbox model
+
+### What plugins can do
+
+- Use the Web Audio API through `context.audioContext`
+- Fetch binary assets from `cdn.collabhut.com` via `context.fetchAsset()`
+- Use `SharedArrayBuffer` for lock-free transport reads (provided by the host)
+- Use standard Web APIs available in Workers: `crypto`, `TextEncoder`,
+  `URL`, `Math`, `JSON`, `console`
+
+### What plugins cannot do
+
+| Blocked | Reason |
+|---|---|
+| `fetch()` to arbitrary URLs | Prevented at the sandbox level; only `context.fetchAsset()` is available and it checks `cdn.collabhut.com` |
+| `XMLHttpRequest` | Not available in Workers by default |
+| DOM access (`document`, `window`) | Workers have no DOM |
+| `localStorage`, `sessionStorage`, `IndexedDB` | Storage isolation |
+| `WebSocket`, `WebRTC` | Network isolation |
+| `navigator.mediaDevices` | Mic/camera are host-only |
+| `eval()`, `new Function()` | Dynamic code execution is prohibited in the build validator |
+
+### How the sandbox is enforced
+
+1. **Build-time**: The CollabHut build service analyses your compiled bundle
+   with static analysis.  Prohibited APIs (`eval`, `Function`, `XMLHttpRequest`,
+   direct `fetch`) cause the build to be rejected.
+2. **Runtime**: The plugin Worker is created with a strict
+   `Content-Security-Policy` that blocks all network access except
+   `cdn.collabhut.com`.
+3. **CDN fetch proxy**: All asset fetches go through `context.fetchAsset()`
+   which validates the URL before making the request on the main thread.
+
+### Malicious code detection
+
+The build service scans for:
+
+- Obfuscated strings that expand to prohibited API names
+- Attempts to access `globalThis` to bypass restrictions
+- Prototype pollution patterns
+- Infinite loops without exit conditions
+
+Submissions that fail these checks are rejected and the developer account is
+flagged for manual review.
+
+---
+
+## Licensing & verification
+
+### How it works (no user friction)
+
+CollabDAW verifies plugin licenses **server-side** when a project containing a
+plugin is opened.  The flow is:
+
+```
+DAW opens project
+    → DAW sends session token + plugin manifest IDs to CollabHut API
+    → API returns signed LicenseToken per plugin (or denial)
+    → DAW validates token signature against embedded public key
+    → Plugin is loaded (granted) or an in-app notice is shown (denied)
+```
+
+There is **no key-entry dialog** — users never type a license key.
+
+### Token lifetime
+
+Tokens are short-lived (typically 1 hour) so revocations take effect quickly.
+The DAW re-verifies automatically in the background.
+
+### Denial reasons
+
+| Code | Shown when |
+|---|---|
+| `"not-purchased"` | User has not bought the plugin |
+| `"revoked"` | License was revoked (charge-back, TOS violation) |
+| `"collab-completed"` | The collaboration granting access is finished |
+| `"collab-not-member"` | User was removed from the collaboration |
+| `"expired"` | Token is past expiry — re-verification needed |
+| `"plugin-delisted"` | Plugin was removed from the marketplace |
+
+---
+
+## Collaboration access rules
+
+> **This section describes mandatory policy — deviation is not permitted.**
+
+A user who does **not** directly own a paid plugin may still use it **if all of
+the following conditions are met simultaneously**:
+
+1. They are a participant in an **active** (non-completed) collaboration on
+   CollabHut.
+2. At least one **other** participant in that same collaboration owns a valid
+   license for the plugin.
+3. The plugin's `manifest.pricing` is `"paid"` (free plugins require no
+   license at all).
+
+### What "active" means
+
+A collaboration is active while its `status` field in the database is
+`"active"` or `"pending"`.  Once it is marked `"completed"`, collab-access
+tokens are revoked at the next re-verification cycle.
+
+### What non-owners can and cannot do
+
+| Action | Non-owner with collab access | Without collab access |
+|---|---|---|
+| Use plugin during project session | ✅ | ❌ |
+| Export / bounce with plugin active | ✅ (while collab active) | ❌ |
+| Export after collab completes | ❌ | ❌ |
+| Upload plugin to marketplace | ❌ (only the license owner can) | ❌ |
+
+### Developer responsibility
+
+You **do not** need to implement these rules in your plugin code — they are
+enforced by CollabDAW and the CollabHut API.  The `LicenseCheckResult` your
+plugin receives is already resolved.
+
+This policy is also documented in:
+- CollabDAW's in-app scripting manual (Docs panel, `/docs`)
+- The CollabHut Marketplace terms of service
+- The developer agreement you accept when publishing
+
+---
+
+## Publishing to the CollabHut Marketplace
+
+### Build your plugin
+
+```bash
+pnpm build
+# or
+npx tsc
+```
+
+Verify the output:
+
+```bash
+ls dist/
+# index.js  index.d.ts  index.js.map
+```
+
+### Validate locally
+
+```bash
+npx collabhut-plugin-validate dist/index.js
+```
+
+This runs the same static analysis as the build service.
+
+### Create a Marketplace listing
+
+1. Go to [collabhut.com/marketplace/developer](https://collabhut.com/marketplace/developer)
+2. Click **New Plugin Listing**
+3. Fill in:
+   - Plugin name and description (pulled from `manifest` on upload)
+   - Pricing: free or paid (must match `manifest.pricing`)
+   - Category, tags, cover image
+4. Upload `dist/index.js` — the build service signs the bundle
+5. After approval (automated for free, manual review for paid), the plugin
+   goes live
+
+### Bundle upload rules
+
+| Rule | Detail |
+|---|---|
+| Single file only | `index.js` — no external dependencies at runtime |
+| Max bundle size | 2 MB (request an increase for sample-based instruments) |
+| No `.dawplugin` uploads | Plugin IDE working files are not marketplace bundles |
+| No source maps required | Strip them for smaller uploads |
+| No TypeScript source | Compiled JS only |
+
+### Versioning
+
+Follow semantic versioning.  To publish an update:
+1. Increment `version` in your `manifest` object
+2. Rebuild and upload the new bundle
+3. Old installs auto-update when users next open a project containing the plugin
+
+### Pricing
+
+- **Free plugins**: Unlimited downloads, no review delay
+- **Paid plugins**: Set a price in USD (minimum $0.99). 80% revenue share.
+  Manual review takes 1–3 business days.
+
+---
+
+## Plugin IDE & .dawplugin files
+
+CollabDAW includes a built-in **Plugin IDE** accessible from the sidebar
+(Plugins screen).  It lets you:
+
+- Write and edit plugin TypeScript in a code editor
+- Preview shader output in real time
+- Test audio/MIDI effect output on a test signal
+- Save your work as a **`.dawplugin` file** — a local project format
+
+### .dawplugin format
+
+A `.dawplugin` file is a ZIP archive containing:
+
+```
+my-plugin.dawplugin/
+  plugin.json      ← manifest + IDE metadata
+  src/
+    index.ts       ← your TypeScript source
+  assets/          ← local test assets (not included in marketplace bundle)
+```
+
+**`.dawplugin` files are for development only.**  They cannot be uploaded to
+the marketplace directly — you must build the compiled bundle first.
+
+### Workflow
+
+```
+IDE → .dawplugin → tsc → dist/index.js → collabhut-plugin-validate → marketplace upload
+```
+
+---
+
+## API reference
+
+### `PluginManifest`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | ✅ | Globally unique reverse-domain ID, e.g. `"com.myorg.plugin-name"` |
+| `name` | `string` | ✅ | Display name |
+| `version` | `SemVer` | ✅ | Semantic version string, e.g. `"1.2.3"` |
+| `type` | `PluginType` | ✅ | One of the five plugin types |
+| `description` | `string` | ✅ | Short description (max 200 chars) |
+| `author` | `PluginAuthor` | ✅ | Author name, optional URL and email |
+| `homepage` | `string` | — | Plugin or developer homepage URL |
+| `tags` | `string[]` | — | Discoverability tags |
+| `params` | `PluginParam[]` | — | Parameter definitions |
+| `pricing` | `"free" \| "paid"` | ✅ | Must match marketplace listing |
+| `minApiVersion` | `SemVer` | ✅ | Minimum CollabDAW API version required |
+| `shadertoyCompatible` | `boolean` | — | Only for `type: "shader"` |
+
+### `PluginContext`
+
+Injected into every factory function.
+
+| Property | Type | Description |
+|---|---|---|
+| `audioContext` | `AudioContext` | The track's Web Audio context |
+| `sampleRate` | `number` | Current sample rate in Hz |
+| `bpm` | `number` | Current session BPM |
+| `positionBeats` | `number` | Current playback position in beats |
+| `isPlaying` | `boolean` | Whether the transport is playing |
+| `fetchAsset(url)` | `Promise<ArrayBuffer>` | Fetch a CDN asset (CDN-only) |
+
+`InstrumentContext` extends `PluginContext` with:
+
+| Property | Type | Description |
+|---|---|---|
+| `maxPolyphony` | `number` | Maximum simultaneous voices the host will trigger |
+
+### `AudioEffectIO`
+
+Returned by an audio-effect factory.
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `input` | `AudioNode` | ✅ | Host connects track signal here |
+| `output` | `AudioNode` | ✅ | Plugin outputs processed audio here |
+| `sidechain` | `AudioNode` | — | Optional side-chain input |
+| `automationTargets` | `Record<string, AudioParam>` | — | Automation-capable params |
+
+### `MidiEffectPlugin`
+
+| Method | Signature | Description |
+|---|---|---|
+| `process` | `(events: ReadonlyArray<MidiEvent>) => MidiEvent[]` | Process one audio block |
+| `dispose` | `() => void` | Clean up resources |
+
+### `InstrumentVoice`
+
+| Member | Description |
+|---|---|
+| `output: AudioNode` | Audio output for this voice |
+| `stop(velocity, time)` | Begin release phase |
+| `kill()` | Immediate hard stop (no release) |
+
+### `InstrumentPlugin`
+
+| Method | Description |
+|---|---|
+| `noteOn(note, velocity, time)` | Start a new voice |
+| `onMidi(event)` | Handle non-note MIDI events |
+| `dispose()` | Clean up resources |
+
+---
+
+## Frequently asked questions
+
+**Can I use npm packages in my plugin?**
+
+Only packages that compile to pure ES2022+ JavaScript with no DOM or Node.js
+dependencies.  All dependencies must be bundled into your single `index.js`.
+Use a bundler like `esbuild` or `rollup` before upload.
+
+**Can I use WebAssembly?**
+
+Yes — load your `.wasm` module via `context.fetchAsset()` and instantiate with
+`WebAssembly.instantiate()`.  The `.wasm` file must be hosted on
+`cdn.collabhut.com`; contact support to have assets uploaded there.
+
+**Can I access the microphone?**
+
+No — audio input is managed exclusively by the host.  For instrument plugins
+the host provides a MIDI stream; for audio effects the host provides the
+rendered audio block.
+
+**How do I test my plugin locally before publishing?**
+
+Use the Plugin IDE built into CollabDAW (sidebar → Plugins).  It gives you a
+live preview environment with a test signal.
+
+**My plugin uses external SDKs (Tone.js, etc.) — is that allowed?**
+
+You can bundle them, but they must not attempt network access or DOM manipulation.
+Tone.js is partially safe; avoid its transport and timeline features
+(which inject into `window`) and use only its DSP utilities.
+
+**Can I use `async` / `await` in my factory functions?**
+
+Yes — the DAW awaits the factory if it returns a `Promise`.  Use it freely
+for one-shot setup like loading impulse responses or WASM modules.  The plugin
+will not be connected to the audio graph until the promise resolves, so there
+is no risk of glitches.
+
+**What happens to collab-access plugins when a project is opened outside of a collab?**
+
+The plugin will show a "License not available outside collaboration" notice.
+The track will be muted until either the user purchases the plugin or they open
+the project from within an active collaboration where a participant owns a
+license.
+
+---
+
+*For support and community discussion, visit the
+[CollabHut Developer Discord](https://discord.gg/collabhut).*