Auto call functions in kabel; clean up end behavior of worklet; move kabel first in chain; write docstring

packages/core/pattern.mjs

@@ -3761,6 +3761,42 @@ const _asArrayPattern = (pats) => {
   return acc;
 };
 
+/**
+ * Produces a [Kabelsalat](https://kabel.salat.dev/) modular sound engine.
+ * This can be used as either an effect (by including `audioin()` at the beginning
+ * of your kabel expression) or as a sound source (via any expression which doesn't
+ * start with `audioin()`).
+ *
+ * Some helpers you have available to you:
+ *   * Strudel mini notation works fine in K(..) via "" or ``
+ *   * More complex Strudel expressions (like "0 1 2".fast(4) or irand(24)) can be
+ *     written by wrapping them in `S(..)` inside your Kabel code
+ *   * We expose Strudel's note frequency under `sFreq` and Strudel's gate
+ *     information under `sGate`
+ *   * You can use more complex multi-line expressions (like `let x = a; let y = b; x.lpf(y);`)
+ *     by wrapping them inside a function in K (see example).
+ *
+ * @name K
+ * @param {KabelsalatExpression | Function} expr Kabelsalat graph definition
+ * @memberof Pattern
+ * @returns Pattern
+ *
+ * @example
+ * note("A c e".fast(4)).transpose("<0 2 4 6 8>")
+ *   .scale("F:minor").transpose("12")
+ *   .s("saw")
+ *   .K(
+ *     // audioin().mul(sGate.adsr(0.001, 0.3, 0, 0.2)) // as effect
+ *     saw(saw(sFreq / "2!3 16").mul(8).add(sFreq).lag("0!3 0.1")).mul(0.3) // as source
+ *     .mul(sGate.adsr(0, 0.15, 0.5, "0.1!3 1"))
+ *     .lpf(sGate.adsr(0, 0.2, 0.3, 0.2).mul(1).add(0))
+ *     .add(x => x.delay(S("0.3 0.2".fast(2))).mul(0.7))
+ *     .add(x => x.delay("0.03 [0.08 0.01] 0.01 0.013").mul(0.77)).mul(0.7)
+ *     .add(x => x.delay(.13).mul(0.7))
+ *     .out()
+ *   )
+ *   ._pianoroll()
+ */
 /**
  * Creates a worklet effect. Typically derived by writing K(...) in the REPL which will parse
  * Kabelsalat code.