Feat: documentation, UI/UX

docs/forth/cycling.md

@@ -0,0 +1,92 @@
+# Cycling & Selection
+
+These words all share a pattern: push values onto the stack, then select one. If the selected item is a quotation, it gets executed. If it is a plain value, it gets pushed. All of them support `[ ]` brackets for auto-counting.
+
+## cycle / pcycle
+
+Sequential rotation through values.
+
+`cycle` advances based on `runs` — how many times this particular step has played:
+
+```forth
+60 64 67 3 cycle note sine s .    ;; 60, 64, 67, 60, 64, 67, ...
+```
+
+`pcycle` advances based on `iter` — the pattern iteration count:
+
+```forth
+kick snare 2 pcycle s .    ;; kick on even iterations, snare on odd
+```
+
+The distinction matters when patterns have different lengths or when multiple steps share the same script. `cycle` gives each step its own independent counter. `pcycle` ties all steps to the same global pattern position.
+
+## bounce / pbounce
+
+Ping-pong instead of wrapping. With 4 values the sequence is 0, 1, 2, 3, 2, 1, 0, 1, 2, ...
+
+```forth
+60 64 67 72 4 bounce note sine s .    ;; ping-pong by step runs
+60 64 67 72 4 pbounce note sine s .   ;; ping-pong by pattern iteration
+```
+
+Same `runs` vs `iter` split as `cycle` / `pcycle`.
+
+## choose
+
+Uniform random selection:
+
+```forth
+kick snare hat 3 choose s .    ;; random drum hit each time
+```
+
+Unlike the cycling words, `choose` is nondeterministic — every evaluation picks independently.
+
+## wchoose
+
+Weighted random. Push value/weight pairs, then the count:
+
+```forth
+kick 0.5  snare 0.3  hat 0.2  3 wchoose s .
+```
+
+Kick plays 50% of the time, snare 30%, hat 20%. Weights are normalized automatically — they don't need to sum to 1.
+
+## index
+
+Direct lookup by an explicit index. The index wraps with modulo, so it never goes out of bounds. Negative indices count from the end:
+
+```forth
+[ c4 e4 g4 ] step index note sine s .    ;; step number picks the note
+[ c4 e4 g4 ] iter index note sine s .    ;; pattern iteration picks the note
+```
+
+This is useful when you want full control over which value is selected, driven by any expression you like.
+
+## Using with brackets
+
+All these words take a count argument `n`. Square brackets compute that count for you:
+
+```forth
+[ 60 64 67 ] cycle note sine s .      ;; no need to write "3"
+[ kick snare hat ] choose s .
+[ c4 e4 g4 b4 ] bounce note sine s .
+```
+
+Without brackets: `60 64 67 3 cycle`. With brackets: `[ 60 64 67 ] cycle`. Same result, less counting.
+
+## Quotations
+
+When any of these words selects a quotation, it executes it instead of pushing it:
+
+```forth
+[ ( c4 note ) ( e4 note ) ( g4 note ) ] cycle
+sine s .
+```
+
+On the first run the quotation `( c4 note )` executes, setting the note to C4. Next run, E4. Then G4. Then back to C4.
+
+This works with all selection words. Mix plain values and quotations freely:
+
+```forth
+[ ( hat s 0.3 gain . ) ( snare s . ) ( kick s . ) ] choose
+```