diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index b63a702f8..2063e3695 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -1056,6 +1056,36 @@ function _composeOp(a, b, func) {
 
 // pattern composers
 const COMPOSERS = {
+  /**
+   * When called on a pattern `a`, with a input pattern `b` (`a.set(b)`),
+   * combines `a` and `b` such that anything defined in `b`
+   * overwrites the corresponding value in `a`
+   *
+   * See examples below
+   * @name set
+   * @param {Pattern} pat
+   * @returns Pattern
+   * @memberof Pattern
+   * @tags internal, combiners
+   * @example
+   * // because input pattern has `s` set,
+   * // it overrides the "sine" declared earlier
+   * note("c a f e").s("sine").set(s("triangle"))
+   * @example
+   * // Structure from original pattern is
+   * // maintained, even when explicitly set
+   * note("c a f e").s("sine").set(note("c a")
+   * .struct("x!8"))
+   * @example
+   * // Using something like `apply`, we can
+   * // invert which pattern overrides the other
+   * // Here, the struct will be "x!8", and the
+   * // notes will be c c a a f f e e
+   * note("c a f e").apply(x=>{
+   * // pure(0) here is used as a dummy pattern
+   *     return pure(0).struct("x!8").set(x)
+   * })
+   */
   set: [(a, b) => b],
   keep: [(a) => a],
   keepif: [(a, b) => (b ? a : undefined)],
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 831e48767..a66c939a3 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -11110,6 +11110,101 @@ exports[`runs examples > example "seqPLoop" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "set" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:c s:triangle ]",
+  "[ 1/4 → 1/2 | note:a s:triangle ]",
+  "[ 1/2 → 3/4 | note:f s:triangle ]",
+  "[ 3/4 → 1/1 | note:e s:triangle ]",
+  "[ 1/1 → 5/4 | note:c s:triangle ]",
+  "[ 5/4 → 3/2 | note:a s:triangle ]",
+  "[ 3/2 → 7/4 | note:f s:triangle ]",
+  "[ 7/4 → 2/1 | note:e s:triangle ]",
+  "[ 2/1 → 9/4 | note:c s:triangle ]",
+  "[ 9/4 → 5/2 | note:a s:triangle ]",
+  "[ 5/2 → 11/4 | note:f s:triangle ]",
+  "[ 11/4 → 3/1 | note:e s:triangle ]",
+  "[ 3/1 → 13/4 | note:c s:triangle ]",
+  "[ 13/4 → 7/2 | note:a s:triangle ]",
+  "[ 7/2 → 15/4 | note:f s:triangle ]",
+  "[ 15/4 → 4/1 | note:e s:triangle ]",
+]
+`;
+
+exports[`runs examples > example "set" example index 1 1`] = `
+[
+  "[ (0/1 → 1/8) ⇝ 1/4 | note:c s:sine ]",
+  "[ 0/1 ⇜ (1/8 → 1/4) | note:c s:sine ]",
+  "[ (1/4 → 3/8) ⇝ 1/2 | note:c s:sine ]",
+  "[ 1/4 ⇜ (3/8 → 1/2) | note:c s:sine ]",
+  "[ (1/2 → 5/8) ⇝ 3/4 | note:a s:sine ]",
+  "[ 1/2 ⇜ (5/8 → 3/4) | note:a s:sine ]",
+  "[ (3/4 → 7/8) ⇝ 1/1 | note:a s:sine ]",
+  "[ 3/4 ⇜ (7/8 → 1/1) | note:a s:sine ]",
+  "[ (1/1 → 9/8) ⇝ 5/4 | note:c s:sine ]",
+  "[ 1/1 ⇜ (9/8 → 5/4) | note:c s:sine ]",
+  "[ (5/4 → 11/8) ⇝ 3/2 | note:c s:sine ]",
+  "[ 5/4 ⇜ (11/8 → 3/2) | note:c s:sine ]",
+  "[ (3/2 → 13/8) ⇝ 7/4 | note:a s:sine ]",
+  "[ 3/2 ⇜ (13/8 → 7/4) | note:a s:sine ]",
+  "[ (7/4 → 15/8) ⇝ 2/1 | note:a s:sine ]",
+  "[ 7/4 ⇜ (15/8 → 2/1) | note:a s:sine ]",
+  "[ (2/1 → 17/8) ⇝ 9/4 | note:c s:sine ]",
+  "[ 2/1 ⇜ (17/8 → 9/4) | note:c s:sine ]",
+  "[ (9/4 → 19/8) ⇝ 5/2 | note:c s:sine ]",
+  "[ 9/4 ⇜ (19/8 → 5/2) | note:c s:sine ]",
+  "[ (5/2 → 21/8) ⇝ 11/4 | note:a s:sine ]",
+  "[ 5/2 ⇜ (21/8 → 11/4) | note:a s:sine ]",
+  "[ (11/4 → 23/8) ⇝ 3/1 | note:a s:sine ]",
+  "[ 11/4 ⇜ (23/8 → 3/1) | note:a s:sine ]",
+  "[ (3/1 → 25/8) ⇝ 13/4 | note:c s:sine ]",
+  "[ 3/1 ⇜ (25/8 → 13/4) | note:c s:sine ]",
+  "[ (13/4 → 27/8) ⇝ 7/2 | note:c s:sine ]",
+  "[ 13/4 ⇜ (27/8 → 7/2) | note:c s:sine ]",
+  "[ (7/2 → 29/8) ⇝ 15/4 | note:a s:sine ]",
+  "[ 7/2 ⇜ (29/8 → 15/4) | note:a s:sine ]",
+  "[ (15/4 → 31/8) ⇝ 4/1 | note:a s:sine ]",
+  "[ 15/4 ⇜ (31/8 → 4/1) | note:a s:sine ]",
+]
+`;
+
+exports[`runs examples > example "set" example index 2 1`] = `
+[
+  "[ 0/1 → 1/8 | value:0 note:c ]",
+  "[ 1/8 → 1/4 | value:0 note:c ]",
+  "[ 1/4 → 3/8 | value:0 note:a ]",
+  "[ 3/8 → 1/2 | value:0 note:a ]",
+  "[ 1/2 → 5/8 | value:0 note:f ]",
+  "[ 5/8 → 3/4 | value:0 note:f ]",
+  "[ 3/4 → 7/8 | value:0 note:e ]",
+  "[ 7/8 → 1/1 | value:0 note:e ]",
+  "[ 1/1 → 9/8 | value:0 note:c ]",
+  "[ 9/8 → 5/4 | value:0 note:c ]",
+  "[ 5/4 → 11/8 | value:0 note:a ]",
+  "[ 11/8 → 3/2 | value:0 note:a ]",
+  "[ 3/2 → 13/8 | value:0 note:f ]",
+  "[ 13/8 → 7/4 | value:0 note:f ]",
+  "[ 7/4 → 15/8 | value:0 note:e ]",
+  "[ 15/8 → 2/1 | value:0 note:e ]",
+  "[ 2/1 → 17/8 | value:0 note:c ]",
+  "[ 17/8 → 9/4 | value:0 note:c ]",
+  "[ 9/4 → 19/8 | value:0 note:a ]",
+  "[ 19/8 → 5/2 | value:0 note:a ]",
+  "[ 5/2 → 21/8 | value:0 note:f ]",
+  "[ 21/8 → 11/4 | value:0 note:f ]",
+  "[ 11/4 → 23/8 | value:0 note:e ]",
+  "[ 23/8 → 3/1 | value:0 note:e ]",
+  "[ 3/1 → 25/8 | value:0 note:c ]",
+  "[ 25/8 → 13/4 | value:0 note:c ]",
+  "[ 13/4 → 27/8 | value:0 note:a ]",
+  "[ 27/8 → 7/2 | value:0 note:a ]",
+  "[ 7/2 → 29/8 | value:0 note:f ]",
+  "[ 29/8 → 15/4 | value:0 note:f ]",
+  "[ 15/4 → 31/8 | value:0 note:e ]",
+  "[ 31/8 → 4/1 | value:0 note:e ]",
+]
+`;
+
 exports[`runs examples > example "setDefaultJoin" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | s:saw velocity:1 note:F delay:0 ]",