diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index 318847752..f88c4159a 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -508,6 +508,16 @@ export class Pattern {
    * @param {Function} func
    * @returns Pattern
    * @noAutocomplete
+   * @example
+   * note("[a b, c d] a b c d").s("gm_piano").withHaps(x=>{
+   *   if (x.length > 1) {
+   *     x.map(hap=>{
+   *       // select gm_piano:1 sample
+   *       hap.value.n = 1
+   *     })
+   *   }
+   *   return x
+   * })
    */
   withHaps(func) {
     const result = new Pattern((state) => func(this.query(state), state));
@@ -521,6 +531,17 @@ export class Pattern {
    * @param {Function} func
    * @returns Pattern
    * @noAutocomplete
+   * @example
+   * note("c a f e").withHap(x=>{
+   *   if (x.value.note == 'c') {
+   *     x.value.s = 'gm_piano'
+   *   }
+   *   else {
+   *     x.value.s = 'gm_piano'
+   *     x.value.n = 2
+   *   }
+   *   return x
+   * })
    */
   withHap(func) {
     return this.withHaps((haps) => haps.map(func));
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index 163d5e8b3..551f80cd0 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -5361,6 +5361,43 @@ exports[`runs examples > example "getDuration" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "getFrequency" example index 0 1`] = `
+[
+  "[ 0/1 → 1/12 | freq:{i:4} clip:0.5 room:1 ]",
+  "[ 1/12 → 1/6 | freq:{i:8} clip:0.5 room:1 ]",
+  "[ 1/6 → 1/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 1/4 → 1/3 | freq:{i:10} clip:0.5 room:1 ]",
+  "[ 1/2 → 7/12 | freq:{i:5} clip:0.5 room:1 ]",
+  "[ 7/12 → 2/3 | freq:{i:7} clip:0.5 room:1 ]",
+  "[ 2/3 → 3/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 3/4 → 5/6 | freq:{i:11} clip:0.5 room:1 ]",
+  "[ 1/1 → 13/12 | freq:{i:4} clip:0.5 room:1 ]",
+  "[ 13/12 → 7/6 | freq:{i:8} clip:0.5 room:1 ]",
+  "[ 7/6 → 5/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 5/4 → 4/3 | freq:{i:10} clip:0.5 room:1 ]",
+  "[ 3/2 → 19/12 | freq:{i:5} clip:0.5 room:1 ]",
+  "[ 19/12 → 5/3 | freq:{i:7} clip:0.5 room:1 ]",
+  "[ 5/3 → 7/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 7/4 → 11/6 | freq:{i:11} clip:0.5 room:1 ]",
+  "[ 2/1 → 25/12 | freq:{i:4} clip:0.5 room:1 ]",
+  "[ 25/12 → 13/6 | freq:{i:8} clip:0.5 room:1 ]",
+  "[ 13/6 → 9/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 9/4 → 7/3 | freq:{i:10} clip:0.5 room:1 ]",
+  "[ 5/2 → 31/12 | freq:{i:5} clip:0.5 room:1 ]",
+  "[ 31/12 → 8/3 | freq:{i:7} clip:0.5 room:1 ]",
+  "[ 8/3 → 11/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 11/4 → 17/6 | freq:{i:11} clip:0.5 room:1 ]",
+  "[ 3/1 → 37/12 | freq:{i:4} clip:0.5 room:1 ]",
+  "[ 37/12 → 19/6 | freq:{i:8} clip:0.5 room:1 ]",
+  "[ 19/6 → 13/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 13/4 → 10/3 | freq:{i:10} clip:0.5 room:1 ]",
+  "[ 7/2 → 43/12 | freq:{i:5} clip:0.5 room:1 ]",
+  "[ 43/12 → 11/3 | freq:{i:7} clip:0.5 room:1 ]",
+  "[ 11/3 → 15/4 | freq:{i:9} clip:0.5 room:1 ]",
+  "[ 15/4 → 23/6 | freq:{i:11} clip:0.5 room:1 ]",
+]
+`;
+
 exports[`runs examples > example "grow" example index 0 1`] = `
 [
   "[ 0/1 → 1/10 | s:tha bank:mridangam ]",
@@ -9150,6 +9187,24 @@ exports[`runs examples > example "pickF" example index 2 1`] = `
 ]
 `;
 
+exports[`runs examples > example "pickOut" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:g ]",
+  "[ 1/4 → 1/2 | note:g ]",
+  "[ 1/2 → 3/4 | note:a ]",
+  "[ 3/4 → 1/1 | note:a ]",
+  "[ (1/1 → 3/2) ⇝ 2/1 | note:e ]",
+  "[ 1/1 ⇜ (3/2 → 2/1) | note:f ]",
+  "[ (2/1 → 9/4) ⇝ 5/2 | note:f ]",
+  "[ 2/1 ⇜ (9/4 → 5/2) | note:g ]",
+  "[ (5/2 → 11/4) ⇝ 3/1 | note:f ]",
+  "[ 5/2 ⇜ (11/4 → 3/1) | note:g ]",
+  "[ 3/1 → 10/3 | note:g ]",
+  "[ 10/3 → 11/3 | note:c ]",
+  "[ 11/3 → 4/1 | note:d ]",
+]
+`;
+
 exports[`runs examples > example "pickmodRestart" example index 0 1`] = `
 [
   "[ 0/1 → 1/4 | note:C3 s:piano ]",
@@ -15288,6 +15343,64 @@ exports[`runs examples > example "withBase" example index 1 1`] = `
 ]
 `;
 
+exports[`runs examples > example "withHap" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:c s:gm_piano ]",
+  "[ 1/4 → 1/2 | note:a s:gm_piano n:2 ]",
+  "[ 1/2 → 3/4 | note:f s:gm_piano n:2 ]",
+  "[ 3/4 → 1/1 | note:e s:gm_piano n:2 ]",
+  "[ 1/1 → 5/4 | note:c s:gm_piano ]",
+  "[ 5/4 → 3/2 | note:a s:gm_piano n:2 ]",
+  "[ 3/2 → 7/4 | note:f s:gm_piano n:2 ]",
+  "[ 7/4 → 2/1 | note:e s:gm_piano n:2 ]",
+  "[ 2/1 → 9/4 | note:c s:gm_piano ]",
+  "[ 9/4 → 5/2 | note:a s:gm_piano n:2 ]",
+  "[ 5/2 → 11/4 | note:f s:gm_piano n:2 ]",
+  "[ 11/4 → 3/1 | note:e s:gm_piano n:2 ]",
+  "[ 3/1 → 13/4 | note:c s:gm_piano ]",
+  "[ 13/4 → 7/2 | note:a s:gm_piano n:2 ]",
+  "[ 7/2 → 15/4 | note:f s:gm_piano n:2 ]",
+  "[ 15/4 → 4/1 | note:e s:gm_piano n:2 ]",
+]
+`;
+
+exports[`runs examples > example "withHaps" example index 0 1`] = `
+[
+  "[ 0/1 → 1/10 | note:a s:gm_piano n:1 ]",
+  "[ 0/1 → 1/10 | note:c s:gm_piano n:1 ]",
+  "[ 1/10 → 1/5 | note:b s:gm_piano n:1 ]",
+  "[ 1/10 → 1/5 | note:d s:gm_piano n:1 ]",
+  "[ 1/5 → 2/5 | note:a s:gm_piano n:1 ]",
+  "[ 2/5 → 3/5 | note:b s:gm_piano n:1 ]",
+  "[ 3/5 → 4/5 | note:c s:gm_piano n:1 ]",
+  "[ 4/5 → 1/1 | note:d s:gm_piano n:1 ]",
+  "[ 1/1 → 11/10 | note:a s:gm_piano n:1 ]",
+  "[ 1/1 → 11/10 | note:c s:gm_piano n:1 ]",
+  "[ 11/10 → 6/5 | note:b s:gm_piano n:1 ]",
+  "[ 11/10 → 6/5 | note:d s:gm_piano n:1 ]",
+  "[ 6/5 → 7/5 | note:a s:gm_piano n:1 ]",
+  "[ 7/5 → 8/5 | note:b s:gm_piano n:1 ]",
+  "[ 8/5 → 9/5 | note:c s:gm_piano n:1 ]",
+  "[ 9/5 → 2/1 | note:d s:gm_piano n:1 ]",
+  "[ 2/1 → 21/10 | note:a s:gm_piano n:1 ]",
+  "[ 2/1 → 21/10 | note:c s:gm_piano n:1 ]",
+  "[ 21/10 → 11/5 | note:b s:gm_piano n:1 ]",
+  "[ 21/10 → 11/5 | note:d s:gm_piano n:1 ]",
+  "[ 11/5 → 12/5 | note:a s:gm_piano n:1 ]",
+  "[ 12/5 → 13/5 | note:b s:gm_piano n:1 ]",
+  "[ 13/5 → 14/5 | note:c s:gm_piano n:1 ]",
+  "[ 14/5 → 3/1 | note:d s:gm_piano n:1 ]",
+  "[ 3/1 → 31/10 | note:a s:gm_piano n:1 ]",
+  "[ 3/1 → 31/10 | note:c s:gm_piano n:1 ]",
+  "[ 31/10 → 16/5 | note:b s:gm_piano n:1 ]",
+  "[ 31/10 → 16/5 | note:d s:gm_piano n:1 ]",
+  "[ 16/5 → 17/5 | note:a s:gm_piano n:1 ]",
+  "[ 17/5 → 18/5 | note:b s:gm_piano n:1 ]",
+  "[ 18/5 → 19/5 | note:c s:gm_piano n:1 ]",
+  "[ 19/5 → 4/1 | note:d s:gm_piano n:1 ]",
+]
+`;
+
 exports[`runs examples > example "withValue" example index 0 1`] = `
 [
   "[ 0/1 → 1/3 | 10 ]",