diff --git a/docs/.claude/settings.local.json b/docs/.claude/settings.local.json
new file mode 100644
index 0000000..e45680a
--- /dev/null
+++ b/docs/.claude/settings.local.json
@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm build:*)",
+      "Bash(npm info:*)",
+      "Bash(cat:*)",
+      "Bash(ls:*)",
+      "Bash(grep:*)",
+      "Bash(pnpm run buildbase:*)",
+      "Bash(xargs basename:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}
diff --git a/docs/content/api/integration-guide/index.html b/docs/content/api/integration-guide/index.html
index a73ecbb..519552e 100644
--- a/docs/content/api/integration-guide/index.html
+++ b/docs/content/api/integration-guide/index.html
@@ -83,7 +83,7 @@ <h2 id="cdn">CDN / Vanilla HTML</h2>
 \cycle("|4|2|2|")
 Sw: S R G M P D N S.
 Sh: sa ri ga ma pa dha ni sa
-    </notation>
+</notation>
   </div>
 </div>
 
diff --git a/docs/content/api/integration-guide/nodejs/index.html b/docs/content/api/integration-guide/nodejs/index.html
index c6a2525..900bc4b 100644
--- a/docs/content/api/integration-guide/nodejs/index.html
+++ b/docs/content/api/integration-guide/nodejs/index.html
@@ -86,11 +86,11 @@ <h2>Accessing Notation Structure</h2>
 <notation showSource="true" caption="Multi-line Composition">
 \cycle("|4|2|2|")
 \line("Pallavi")
-Sw: S , R , | G , M , | P , D , | N , S. , ||
-Sh: ni , nnu , | ko , ri , | va , ra , | nam , ma , ||
+Sw: S , R , G , M , P , D , N , S. ,
+Sh: ni , nnu , ko , ri , va , ra , nam , ma ,
 \line("Anupallavi")
-Sw: S. , N , | D , P , | M , G , | R , S , ||
-Sh: en , na , | gu , ru , | sva , mi , | ra , ya , ||
+Sw: S. , N , D , P , M , G , R , S ,
+Sh: en , na , gu , ru , sva , mi , ra , ya ,
 </notation>
 
 <h2>Validation</h2>
diff --git a/docs/content/api/integration-guide/react/index.html b/docs/content/api/integration-guide/react/index.html
index ffcbc66..882582a 100644
--- a/docs/content/api/integration-guide/react/index.html
+++ b/docs/content/api/integration-guide/react/index.html
@@ -73,7 +73,7 @@ <h2>Basic NotationViewer Component</h2>
 \cycle("|4|2|2|")
 Sw: S R G M P D N S.
 Sh: sa ri ga ma pa dha ni sa
-    </notation>
+</notation>
   </div>
 </div>
 
@@ -156,7 +156,7 @@ <h2>Component with Source Display and Editing</h2>
 \line("Pallavi")
 Sw: S , R , G , M , P , D , N , S. ,
 Sh: ni , nnu , ko , ri , va , ra , nam , ma ,
-    </notation>
+</notation>
   </div>
 </div>
 
diff --git a/docs/content/api/integration-guide/vue/index.html b/docs/content/api/integration-guide/vue/index.html
index a74a3b3..48f5e4f 100644
--- a/docs/content/api/integration-guide/vue/index.html
+++ b/docs/content/api/integration-guide/vue/index.html
@@ -79,7 +79,7 @@ <h2>Basic NotationViewer Component</h2>
 \cycle("|4|2|2|")
 Sw: S R G M P D N S.
 Sh: sa ri ga ma pa dha ni sa
-    </notation>
+</notation>
   </div>
 </div>
 
@@ -191,7 +191,7 @@ <h2>Component with Source Display and Editing</h2>
 \line("Pallavi")
 Sw: S , R , G , M , P , D , N , S. ,
 Sh: ni , nnu , ko , ri , va , ra , nam , ma ,
-    </notation>
+</notation>
   </div>
 </div>
 
diff --git a/docs/content/api/integration-guide/web-components/index.html b/docs/content/api/integration-guide/web-components/index.html
index 8ba297d..8070d4d 100644
--- a/docs/content/api/integration-guide/web-components/index.html
+++ b/docs/content/api/integration-guide/web-components/index.html
@@ -189,7 +189,7 @@ <h2>Advanced: External Source</h2>
 \beatDuration(4)
 \line("Pallavi")
 Sw: S , R , G , M , P , D , N , S. ,
-Sh: ni , nnu , ko , ri , va , ra , nam , ma , 
+Sh: ni , nnu , ko , ri , va , ra , nam , ma ,
 </notation>
 
 <h2>Interactive Features</h2>
diff --git a/docs/content/api/styling/index.html b/docs/content/api/styling/index.html
index fb116b0..74449ee 100644
--- a/docs/content/api/styling/index.html
+++ b/docs/content/api/styling/index.html
@@ -156,7 +156,7 @@ <h4 style="margin-top: 0; color: #023e8a;">Ocean Theme</h4>
 \cycle("|4|2|2|")
 \beatDuration(4)
 Sw: S R G M , P D , N S.
-  </notation>
+</notation>
 </div>
 
 <div class="theme-forest">
@@ -165,7 +165,7 @@ <h4 style="margin-top: 0; color: #1b4332;">Forest Theme</h4>
 \cycle("|4|2|2|")
 \beatDuration(4)
 Sw: S R G M , P D , N S.
-  </notation>
+</notation>
 </div>
 
 <div class="theme-sunset">
@@ -174,7 +174,7 @@ <h4 style="margin-top: 0; color: #7b2cbf;">Sunset Theme</h4>
 \cycle("|4|2|2|")
 \beatDuration(4)
 Sw: S R G M , P D , N S.
-  </notation>
+</notation>
 </div>
 
 <h3>CSS for Scoped Themes</h3>
diff --git a/docs/content/demos/playgrounds/model-events/index.html b/docs/content/demos/playgrounds/model-events/index.html
index 1e8c7c0..b72fde5 100644
--- a/docs/content/demos/playgrounds/model-events/index.html
+++ b/docs/content/demos/playgrounds/model-events/index.html
@@ -94,7 +94,7 @@ <h2>Notation Syntax</h2>
   <tr><td><code>S R G M</code></td><td>Individual notes</td></tr>
   <tr><td><code>S.</code> or <code>S'</code></td><td>Higher octave</td></tr>
   <tr><td><code>.S</code> or <code>S,</code></td><td>Lower octave</td></tr>
-  <tr><td><code>,</code> or <code>_</code></td><td>Space/silence</td></tr>
+  <tr><td><code>,</code></td><td>Space/silence</td></tr>
   <tr><td><code>[ G M P ]</code></td><td>Group (atoms share duration)</td></tr>
   <tr><td><code>2 S</code></td><td>Duration prefix (S has duration 2)</td></tr>
 </table>
diff --git a/docs/content/examples/basic-varnam/index.html b/docs/content/examples/basic-varnam/index.html
index 37e6bf6..65cbca9 100644
--- a/docs/content/examples/basic-varnam/index.html
+++ b/docs/content/examples/basic-varnam/index.html
@@ -163,7 +163,7 @@ <h2>Tips for Varnam Notation</h2>
 
 <ul>
   <li>Always align swaras and sahitya on the same beat</li>
-  <li>Use underscores (<code>_</code>) for sustained notes or pauses</li>
+  <li>Use commas (<code>,</code>) for sustained notes or pauses</li>
   <li>Use <code>\line()</code> to separate sections clearly</li>
   <li>Mark speed changes in muktayi swarams</li>
 </ul>
diff --git a/docs/content/examples/complex-gamakas/index.html b/docs/content/examples/complex-gamakas/index.html
index 099cc09..550ee89 100644
--- a/docs/content/examples/complex-gamakas/index.html
+++ b/docs/content/examples/complex-gamakas/index.html
@@ -94,8 +94,8 @@ <h2>Combining with Speed Changes</h2>
 <h2>Practical Tips</h2>
 
 <ul>
-  <li>Use <code>kampitam</code> for sustained oscillating notes</li>
-  <li>Use <code>jaru</code> for smooth glides between notes</li>
+  <li>Use <code>~</code> before a note for kampitam, the sustained oscillation</li>
+  <li>Use <code>~/</code> and <code>~\</code> for jaaru, the glide up into or down into a note</li>
   <li>Use <code>~</code> for quick ornamental touches</li>
   <li>Study raga-specific gamaka patterns</li>
   <li>Listen to masters to understand proper gamaka application</li>
diff --git a/docs/content/examples/organizing-compositions/index.html b/docs/content/examples/organizing-compositions/index.html
index 38ec352..c32233f 100644
--- a/docs/content/examples/organizing-compositions/index.html
+++ b/docs/content/examples/organizing-compositions/index.html
@@ -14,16 +14,16 @@ <h2>Using Lines to Separate Sections</h2>
 \beatDuration(4)
 
 \line("Pallavi")
-Sw: S R G M , P D N S. , ___ ___ , ___ ___ |
-Sh: sa ri ga ma , pa dha ni sa , ___ ___ , ___ ___ ||
+Sw: S R G M , P D N S. , , , , , , , , , , , , , ,
+Sh: sa ri ga ma , pa dha ni sa , , , , , , , , , , , , , ,
 
 \line("Anupallavi")
-Sw: S. R. G. M. , P. D. N. S.. , ___ ___ , ___ ___ |
-Sh: sa ri ga ma , pa dha ni sa , ___ ___ , ___ ___ ||
+Sw: S. R. G. M. , P. D. N. S.. , , , , , , , , , , , , , ,
+Sh: sa ri ga ma , pa dha ni sa , , , , , , , , , , , , , ,
 
 \line("Charanam")
-Sw: P D S. R. , S. D P M , G M P D , S. ___ |
-Sh: pa dha sa ri , sa dha pa ma , ga ma pa dha , sa ___ ||
+Sw: P D S. R. , S. D P M , G M P D , S. , , ,
+Sh: pa dha sa ri , sa dha pa ma , ga ma pa dha , sa , , ,
 </notation>
 
 <h2>Separating Swaras and Sahitya</h2>
@@ -35,10 +35,10 @@ <h2>Separating Swaras and Sahitya</h2>
 \beatDuration(4)
 
 \line("Pallavi - Swaras")
-Sw: S R G M , P M G R , S R G M , P ___ ___ ___ |
+Sw: S R G M , P M G R , S R G M , P , , , , , , , , ,
 
 \line("Pallavi - Sahitya")
-Sh: nin nu ko ri , va ra da nun , nu ko ri , va ___ ___ ___ ||
+Sh: nin nu ko ri , va ra da nun , nu ko ri , va , , , , , , , , ,
 </notation>
 
 <h2>Multi-Speed Sections</h2>
@@ -50,13 +50,13 @@ <h2>Multi-Speed Sections</h2>
 \beatDuration(4)
 
 \line("Muktayi Swaram - 1st Speed")
-S R G M , P D N S. , ___ ___ , ___ ___ |
+S R G M , P D N S. , , , , , , , , , , , , , ,
 
 \line("Muktayi Swaram - 2nd Speed")
-SR GM PD NS. , R.S. DP MG RS , ___ ___ ___ ___ , ___ ___ ___ ___ |
+SR GM PD NS. , R.S. DP MG RS , , , , , , , , , , , , , , , , , , , , , , , , , ,
 
 \line("Muktayi Swaram - 3rd Speed")
-SRG GMP PDN NS.R. , R.S.D DPN PMG GRS , ___ ___ ___ ___ , ___ ___ ___ ___ |
+SRG GMP PDN NS.R. , R.S.D DPN PMG GRS , , , , , , , , , , , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Long Kriti Structure</h2>
@@ -68,35 +68,37 @@ <h2>Long Kriti Structure</h2>
 \beatDuration(4)
 
 \line("==== PALLAVI ====")
-Sw: S R G M , P D N S. , ___ ___ , ___ ___ |
-Sh: bro va bha ra ma , moo la ra ma chan , dra ___ , ___ ___ ||
+Sw: S R G M , P D N S. , , , , , , , , , , , , , ,
+Sh: bro va bha ra ma , moo la ra ma chan , dra , , , , , , , , , ,
 
 \line("==== ANUPALLAVI ====")
-Sw: S. R. G. M. , P. D. N. S.. , ___ ___ , ___ ___ |
-Sh: de va de va , ja ya ja ya , ___ ___ , ___ ___ ||
+Sw: S. R. G. M. , P. D. N. S.. , , , , , , , , , , , , , ,
+Sh: de va de va , ja ya ja ya , , , , , , , , , , , , , ,
 
 \line("==== CHARANAM 1 ====")
-Sw: P D S. R. , S. D P M , G R S ___ , ___ ___ ___ ___ |
-Sh: ka ru na ni dhi , ra ma bha dra , nin ne ___ , ___ ___ ___ ___ ||
+Sw: P D S. R. , S. D P M , G R S , , , , , , , , , , , , , , , ,
+Sh: ka ru na ni dhi , ra ma bha dra , nin ne , , , , , , , , , , , , , , , ,
 
 \line("==== CHARANAM 2 ====")
-Sw: S R G M , P M G R , S R G M , P ___ ___ ___ |
-Sh: sa da sa dhi ya , tya ga ra ja , vi nu ta , ra ___ ___ ___ ||
+Sw: S R G M , P M G R , S R G M , P , , , , , , , , ,
+Sh: sa da sa dhi ya , tya ga ra ja , vi nu ta , ra , , , , , , , , ,
 </notation>
 
 <h2>Using Comments for Annotations</h2>
 
-<p>Add performance notes or reminders:</p>
+<p>Anything after <code>//</code> on a line is ignored by the parser, so performance notes and
+reminders can sit next to the notation they describe rather than in a line title:</p>
 
 <notation id="comments" showSource="true" caption="Using Comments">
 \cycle("|4|2|2|")
 \beatDuration(4)
 
-\line("Pallavi - Slow tempo, emphasize gamakas")
-Sw: S (R~G) M P , (P~D) N S. , ___ ___ , ___ ___ |
-Sh: nin nu ko ri , va ra da , ___ ___ , ___ ___ ||
+// Slow tempo here, let the gamakas breathe
+\line("Pallavi")
+Sw: S [~ R G] M P , [~ P D] N S. , , , , , , , , , , , , , ,
+Sh: nin nu ko ri , va ra da , , , , , , , , , , , , , ,
 
-\line("Repeat pallavi 2x before anupallavi")
+// Repeat the pallavi twice before moving to the anupallavi
 </notation>
 
 <h2>Organizing Repetitions</h2>
@@ -108,10 +110,10 @@ <h2>Organizing Repetitions</h2>
 \beatDuration(4)
 
 \line("Pallavi [Repeat 2x]")
-Sw: S R G M , P D N S. , ___ ___ , ___ ___ ||
+Sw: S R G M , P D N S. , , , , , , , , , , , , , ,
 
 \line("Anupallavi")
-Sw: S. R. G. M. , P. D. N. S.. , ___ ___ , ___ ___ ||
+Sw: S. R. G. M. , P. D. N. S.. , , , , , , , , , , , , , ,
 
 \line("[Return to Pallavi]")
 </notation>
@@ -125,10 +127,10 @@ <h2>Breaking Long Phrases</h2>
 \beatDuration(4)
 
 \line("Extended Swaram - Part 1")
-SR GM PD NS. , R.S. DP MG RS , SR GM PD NS. , R.S. DP MG RS |
+SR GM PD NS. , R.S. DP MG RS , SR GM PD NS. , R.S. DP MG RS
 
 \line("Extended Swaram - Part 2")
-S.R. G.M. P.D. N.S.. , R..S.. D..N.. P..D.. M..P.. , G..M.. R..G.. S..R.. ___ , ___ ___ ___ ___ |
+S.R. G.M. P.D. N.S.. , R..S.. D..N.. P..D.. M..P.. , G..M.. R..G.. S..R.. , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Organizing by Tala Avartanams</h2>
@@ -140,13 +142,13 @@ <h2>Organizing by Tala Avartanams</h2>
 \beatDuration(4)
 
 \line("Avartanam 1")
-S R G M , P D N S. , ___ ___ , ___ ___ |
+S R G M , P D N S. , , , , , , , , , , , , , ,
 
 \line("Avartanam 2")
-S. R. G. M. , P. D. N. S.. , ___ ___ , ___ ___ |
+S. R. G. M. , P. D. N. S.. , , , , , , , , , , , , , ,
 
 \line("Avartanam 3")
-S.. D.. N.. S.. , P. M. G. R. , S. ___ ___ , ___ ___ ___ ||
+S.. D.. N.. S.. , P. M. G. R. , S. , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Best Practices</h2>
@@ -156,7 +158,7 @@ <h2>Best Practices</h2>
   <li><strong>Visual separation</strong> - Use <code>\line()</code> liberally to separate sections</li>
   <li><strong>Alignment</strong> - Keep swaras and sahitya aligned on the same beats</li>
   <li><strong>Speed markers</strong> - Always label speed changes (1st, 2nd, 3rd speed)</li>
-  <li><strong>Tala markers</strong> - Use <code>|</code> and <code>||</code> to mark avartanam boundaries</li>
+  <li><strong>Tala markers</strong> - Drawn for you from the cycle, one line at the end of each bar and a double line at the end of the avartanam</li>
   <li><strong>Whitespace</strong> - Don't be afraid of empty space for readability</li>
   <li><strong>Comments</strong> - Add performance notes where helpful</li>
   <li><strong>Logical grouping</strong> - Group related phrases together</li>
@@ -167,7 +169,6 @@ <h2>Template for a Complete Composition</h2>
 <notation id="template" showSource="true" caption="Composition Template">
 \cycle("|4|2|2|")
 \beatDuration(4)
-\accidentals()  // Add accidentals if needed
 
 \line("==== PALLAVI ====")
 Sw: // Add swaras
diff --git a/docs/content/examples/percussion/index.html b/docs/content/examples/percussion/index.html
index 96da43a..dc6dd61 100644
--- a/docs/content/examples/percussion/index.html
+++ b/docs/content/examples/percussion/index.html
@@ -7,15 +7,17 @@
 
 <h2>Basic Approach: Using Comments</h2>
 
-<p>The simplest way is to add percussion as comments or labels:</p>
+<p>The simplest way is to write the solkattu as a comment above the line it belongs to. Anything
+after <code>//</code> is ignored by the parser, so it stays in the source without becoming part of
+the notation:</p>
 
 <notation id="percussion-comments" showSource="true" caption="Percussion as Comments">
 \cycle("|4|2|2|")
 \beatDuration(4)
 
 \line("Pallavi with Mridangam")
-Sw: S R G M , P D N S. , ___ ___ , ___ ___ |
-\line("Mridangam: ta ka dhi mi , ta ka jha nu , ___ ___ , ___ ___")
+// mridangam: ta ka dhi mi , ta ka jha nu
+Sw: S R G M , P D N S. , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Separate Percussion Line</h2>
@@ -27,10 +29,10 @@ <h2>Separate Percussion Line</h2>
 \beatDuration(4)
 
 \line("Melody")
-Sw: S R G M , P D N S. , R. S. N D , P M G R |
+Sw: S R G M , P D N S. , R. S. N D , P M G R
 
 \line("Mridangam")
-Pe: ta ka dhi mi , ta ka jha nu , ta ki ta ta , ka dhi mi ta |
+Pe: ta ka dhi mi , ta ka jha nu , ta ki ta ta , ka dhi mi ta
 </notation>
 
 <h2>Common Mridangam Patterns</h2>
@@ -42,10 +44,10 @@ <h3>Basic Adi Tala Pattern</h3>
 \beatDuration(4)
 
 \line("Swaras")
-Sw: S R G M , P D N S. , ___ ___ , ___ ___ |
+Sw: S R G M , P D N S. , , , , , , , , , , , , , ,
 
 \line("Mridangam Pattern")
-Pe: ta ka ta ki , ta ta ka dhi , mi ta ka , jha nu ta |
+Pe: ta ka ta ki , ta ta ka dhi , mi ta ka , jha nu ta
 </notation>
 
 <h3>Chatusram in Adi Tala</h3>
@@ -54,8 +56,8 @@ <h3>Chatusram in Adi Tala</h3>
 \cycle("|4|2|2|")
 \beatDuration(4)
 
-Sw: SRGM PDNS. R.G.M.P. D.N.S..R.. , ___ ___ ___ ___ , ___ ___ ___ ___ |
-Pe: taka dimi taka jhanu , taki tata kadhi mita , ___ ___ ___ ___ , ___ ___ ___ ___ |
+Sw: SRGM PDNS. R.G.M.P. D.N.S..R.. , , , , , , , , , , , , , , , , , , , , , , , , , ,
+Pe: taka dimi taka jhanu , taki tata kadhi mita , , , , , , , , , , , , , , , , , , , , , , , , , ,
 </notation>
 
 <h3>Tisram in Adi Tala</h3>
@@ -64,8 +66,8 @@ <h3>Tisram in Adi Tala</h3>
 \cycle("|4|2|2|")
 \beatDuration(4)
 
-Sw: SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... ___ ___ , ___ ___ ___ ___ |
-Pe: tak adh imi tak adh , ita kit ata kat adh , imi tak adh ___ , ___ ___ ___ ___ |
+Sw: SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... , , , , , , , , , , , , , , , , , , ,
+Pe: tak adh imi tak adh , ita kit ata kat adh , imi tak adh , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Mridangam in Different Talas</h2>
@@ -76,8 +78,8 @@ <h3>Rupaka Tala (6 beats)</h3>
 \cycle("|2|4|")
 \beatDuration(4)
 
-Sw: S R , G M P D N S. |
-Pe: ta ka , dhi mi ta ka jha nu |
+Sw: S R , G M P D N S.
+Pe: ta ka , dhi mi ta ka jha nu
 </notation>
 
 <h3>Misra Chapu (7 beats)</h3>
@@ -86,8 +88,8 @@ <h3>Misra Chapu (7 beats)</h3>
 \cycle("|3|2|2|")
 \beatDuration(4)
 
-Sw: S R G , M P , D N |
-Pe: ta ka dhi , mi ta , ka jha ||
+Sw: S R G , M P , D N
+Pe: ta ka dhi , mi ta , ka jha
 </notation>
 
 <h2>Mridangam Korvai Patterns</h2>
@@ -99,16 +101,16 @@ <h2>Mridangam Korvai Patterns</h2>
 \beatDuration(4)
 
 \line("Korvai - First Iteration")
-Pe: ta ka dhi mi ta ka jha nu , ta ri ki ta ta ka dhi mi , ta ka jha nu ___ , ___ ___ ___ ___ |
+Pe: ta ka dhi mi ta ka jha nu , ta ri ki ta ta ka dhi mi , ta ka jha nu , , , , , , , , , , , , , , , ,
 
 \line("Korvai - Second Iteration")
-Pe: ta ka dhi mi ta ka jha nu , ta ri ki ta ta ka dhi mi , ta ka jha nu ___ , ___ ___ ___ ___ |
+Pe: ta ka dhi mi ta ka jha nu , ta ri ki ta ta ka dhi mi , ta ka jha nu , , , , , , , , , , , , , , , ,
 
 \line("Korvai - Third Iteration")
-Pe: ta ka dhi mi ta ka jha nu , ta ri ki ta ta ka dhi mi , ta ka jha nu ___ , ___ ___ ___ ___ |
+Pe: ta ka dhi mi ta ka jha nu , ta ri ki ta ta ka dhi mi , ta ka jha nu , , , , , , , , , , , , , , , ,
 
 \line("Mohra (Ending)")
-Pe: ta ___ dhi mi ___ , ___ ta ___ , ___ ___ ___ ||
+Pe: ta , , , dhi mi , , , , , , , ta , , , , , , , , , , , , ,
 </notation>
 
 <h2>Thani Avartanam Structure</h2>
@@ -120,13 +122,13 @@ <h2>Thani Avartanam Structure</h2>
 \beatDuration(4)
 
 \line("Section 1 - Simple Patterns")
-Pe: ta ka dhi mi , ta ka jha nu , ta ki ta ta , ka dhi mi ta |
+Pe: ta ka dhi mi , ta ka jha nu , ta ki ta ta , ka dhi mi ta
 
 \line("Section 2 - Increase Complexity")
-Pe: taka dimi taka jhanu , taki tata kadhi mita , takajhanu tari kita , dimi taka jhanu ta |
+Pe: taka dimi taka jhanu , taki tata kadhi mita , takajhanu tari kita , dimi taka jhanu ta
 
 \line("Section 3 - Korvai")
-Pe: takadimi takajhanu tarikita , takadimi takajhanu tarikita , takadimi takajhanu tarikita , ta ___ dhi mi ___ ||
+Pe: takadimi takajhanu tarikita , takadimi takajhanu tarikita , takadimi takajhanu tarikita , ta , , , dhi mi , , ,
 </notation>
 
 <h2>Combining with Swaras</h2>
@@ -138,12 +140,12 @@ <h2>Combining with Swaras</h2>
 \beatDuration(4)
 
 \line("Pallavi")
-Sw: S R G M , P M G R , S R G M , P ___ ___ ___ |
-Pe: ta ka dhi mi , ta ka jha nu , ta ri ki ta , ta ___ ___ ___ ||
+Sw: S R G M , P M G R , S R G M , P , , , , , , , , ,
+Pe: ta ka dhi mi , ta ka jha nu , ta ri ki ta , ta , , , , , , , , ,
 
 \line("Swaram Passage")
-Sw: SR GM PD NS. , R.S. DP MG RS , ___ ___ ___ ___ , ___ ___ ___ ___ |
-Pe: taka dimi taka jhanu , taki tata kadh imi ta , ___ ___ ___ ___ , ___ ___ ___ ___ ||
+Sw: SR GM PD NS. , R.S. DP MG RS , , , , , , , , , , , , , , , , , , , , , , , , , ,
+Pe: taka dimi taka jhanu , taki tata kadh imi ta , , , , , , , , , , , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Tabla Patterns</h2>
@@ -155,10 +157,10 @@ <h2>Tabla Patterns</h2>
 \beatDuration(4)
 
 \line("Melody")
-Sw: S R G M , P D N S. , R. G. M. P. , D. N. S.. R.. |
+Sw: S R G M , P D N S. , R. G. M. P. , D. N. S.. R..
 
 \line("Tabla (Teental)")
-Pe: dha dhin dhin dha , dha dhin dhin dha , dha tin tin ta , ta dhin dhin dha |
+Pe: dha dhin dhin dha , dha dhin dhin dha , dha tin tin ta , ta dhin dhin dha
 </notation>
 
 <h2>Notation Symbols</h2>
@@ -178,7 +180,7 @@ <h2>Practical Tips</h2>
   <li>Use a separate line prefixed with <code>Pe:</code> for percussion</li>
   <li>Align percussion syllables with corresponding melody beats</li>
   <li>Mark korvai iterations clearly (1st, 2nd, 3rd)</li>
-  <li>Use <code>___</code> for rests or sustained tones</li>
+  <li>Use <code>,</code> for a held beat and <code>-</code> for an explicit rest</li>
   <li>Study traditional korvai patterns and their variations</li>
   <li>Practice reciting solkattu (vocal percussion syllables)</li>
   <li>Consider the interaction between melody and percussion</li>
diff --git a/docs/content/examples/ragam-tanam-pallavi/index.html b/docs/content/examples/ragam-tanam-pallavi/index.html
index eeacd9f..15558a2 100644
--- a/docs/content/examples/ragam-tanam-pallavi/index.html
+++ b/docs/content/examples/ragam-tanam-pallavi/index.html
@@ -16,19 +16,17 @@ <h2>Structure Overview</h2>
 
 <h2>Ragam Section</h2>
 
-<p>The ragam is a free exploration. Use <code>\noTala</code> to indicate no fixed rhythm:</p>
+<p>The ragam is a free exploration with no fixed rhythm. There is no command for that yet, so the example below leaves out <code>\cycle</code> and lets the default apply:</p>
 
 <notation id="ragam" showSource="true" caption="Ragam - Raga Kalyani Opening">
-\noTala
-\accidentals(M#)
 \line("Alapana - Lower Octave")
-S _ _ R , G _ M# _ , P _ _ _
+S , , R , G , "M#" , , P , , ,
 
 \line("Alapana - Middle Octave")
-M# P D N , S. _ _ R. , G. M#. P. D.
+"M#" P D N , S. , , R. , G. "M#." P. D.
 
 \line("Alapana - Descent")
-S. _ D N , P M# G R , S _ _ _
+S. , D N , P "M#" G R , S , , ,
 </notation>
 
 <h2>Tanam Section</h2>
@@ -36,14 +34,12 @@ <h2>Tanam Section</h2>
 <p>Tanam introduces rhythm but maintains freedom. Mark it with <code>\line("Tanam")</code>:</p>
 
 <notation id="tanam" showSource="true" caption="Tanam - Raga Kalyani">
-\noTala
-\accidentals(M#)
 \line("Tanam")
-S R G M# , P D N S. , ta na na tom , ta na na tom
+S R G "M#" , P D N S. , ta na na tom , ta na na tom
 
-S. R. G. M#. , P. D. N. S.. , ta na na tom , ta na na tom
+S. R. G. "M#." , P. D. N. S.. , ta na na tom , ta na na tom
 
-S.. D. N. S. , P M# G R , S _ _ _ , ta nom _ _
+S.. D. N. S. , P "M#" G R , S , , , , ta nom , ,
 </notation>
 
 <h2>Pallavi - Setting the Tala</h2>
@@ -53,10 +49,9 @@ <h2>Pallavi - Setting the Tala</h2>
 <notation id="pallavi-setup" showSource="true" caption="Pallavi - Tala Introduction">
 \cycle("|3|2|2|")
 \beatDuration(4)
-\accidentals(M#)
 \line("Pallavi - Misra Chapu")
-Sw: S R G M# , P D N , S. R. G. |
-Sh: ga na na tha , bho vi , ka ra na ||
+Sw: S R G "M#" , P D N , S. R. G.
+Sh: ga na na tha , bho vi , ka ra na
 </notation>
 
 <h2>Pallavi - First Speed</h2>
@@ -66,10 +61,9 @@ <h2>Pallavi - First Speed</h2>
 <notation id="pallavi-first" showSource="true" caption="Pallavi Elaboration - First Speed">
 \cycle("|3|2|2|")
 \beatDuration(4)
-\accidentals(M#)
 \line("1st Speed Variation")
-S R G M# , P M# G R , S R G M# |
-P D N S. , R. S. N D , P M# G R ||
+S R G "M#" , P "M#" G R , S R G "M#"
+P D N S. , R. S. N D , P "M#" G R
 </notation>
 
 <h2>Pallavi - Second Speed</h2>
@@ -77,10 +71,9 @@ <h2>Pallavi - Second Speed</h2>
 <notation id="pallavi-second" showSource="true" caption="Pallavi Elaboration - Second Speed">
 \cycle("|3|2|2|")
 \beatDuration(4)
-\accidentals(M#)
 \line("2nd Speed Variation")
-SR GM# PD , NS. R.S. ND , PM# GR SR |
-GM# PD NS. , R.G. M#.P. D.N. , S.R. G.M#. P.D. ||
+SR "GM#" PD , NS. R.S. ND , "PM#" GR SR
+"GM#" PD NS. , R.G. "M#.P." D.N. , S.R. "G.M#." P.D.
 </notation>
 
 <h2>Pallavi - Third Speed (Tisram)</h2>
@@ -88,10 +81,9 @@ <h2>Pallavi - Third Speed (Tisram)</h2>
 <notation id="pallavi-third" showSource="true" caption="Pallavi Elaboration - Third Speed">
 \cycle("|3|2|2|")
 \beatDuration(4)
-\accidentals(M#)
 \line("3rd Speed Variation (Tisram)")
-SRG GM#P PDN , NS.R. R.S.N NDP , PM#G GRS SRG |
-GM#P PDN NS.R. , R.G.M#. M#.P.D. D.N.S.. , S..D.N. N.S.P PM#G ||
+SRG "GM#P" PDN , NS.R. R.S.N NDP , "PM#G" GRS SRG
+"GM#P" PDN NS.R. , "R.G.M#." "M#.P.D." D.N.S.. , S..D.N. N.S.P "PM#G"
 </notation>
 
 <h2>Kalpana Swarams</h2>
@@ -101,16 +93,15 @@ <h2>Kalpana Swarams</h2>
 <notation id="kalpana" showSource="true" caption="Kalpana Swarams">
 \cycle("|3|2|2|")
 \beatDuration(4)
-\accidentals(M#)
 \line("Kalpana Swaram 1")
-SR GM# PD , NS. R.S. ND , PM# GR SR |
+SR "GM#" PD , NS. R.S. ND , "PM#" GR SR
 \line("Return to Pallavi")
-S R G M# , P D N , S. R. G. ||
+S R G "M#" , P D N , S. R. G.
 
 \line("Kalpana Swaram 2")
-S.D. N.S. S.P , PM# M#G GR , RS SR RG |
+S.D. N.S. S.P , "PM#" "M#G" GR , RS SR RG
 \line("Return to Pallavi")
-S R G M# , P D N , S. R. G. ||
+S R G "M#" , P D N , S. R. G.
 </notation>
 
 <h2>Complete RTP Structure</h2>
@@ -131,7 +122,7 @@ <h2>Complete RTP Structure</h2>
 <h2>Tips for RTP Notation</h2>
 
 <ul>
-  <li>Use <code>\noTala</code> for ragam and tanam sections</li>
+  <li>Leave out <code>\cycle</code> in ragam and tanam sections, which have no fixed rhythm</li>
   <li>Choose interesting talas for pallavi (not just Adi tala)</li>
   <li>Mark each speed variation clearly with <code>\line()</code></li>
   <li>Always return to the pallavi line after kalpana swarams</li>
@@ -144,5 +135,5 @@ <h2>See Also</h2>
 <ul>
   <li><a href="{{.Site.PathPrefix}}/examples/different-speeds/">Different Speeds</a> - Master speed variations</li>
   <li><a href="{{.Site.PathPrefix}}/examples/complex-gamakas/">Complex Gamakas</a> - Apply embellishments</li>
-  <li><a href="{{.Site.PathPrefix}}/reference/commands/">Commands Reference</a> - Learn <code>\noTala</code> and other commands</li>
+  <li><a href="{{.Site.PathPrefix}}/reference/commands/">Commands Reference</a> - Learn <code>\cycle</code>, <code>\beatDuration</code> and the rest</li>
 </ul>
diff --git a/docs/content/examples/tisram/index.html b/docs/content/examples/tisram/index.html
index b866028..7b03801 100644
--- a/docs/content/examples/tisram/index.html
+++ b/docs/content/examples/tisram/index.html
@@ -13,7 +13,7 @@ <h2>Understanding Tisram</h2>
 \cycle("|4|2|2|")
 \beatDuration(4)
 \line("Tisram - 3 notes per beat")
-SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... ___ ___ , ___ ___ ___ ___
+SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... , , , , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Tisram vs Chatusram (4 notes per beat)</h2>
@@ -24,10 +24,10 @@ <h2>Tisram vs Chatusram (4 notes per beat)</h2>
 \cycle("|4|2|2|")
 \beatDuration(4)
 \line("Chatusram (4 per beat)")
-SRGM PDNS. R.G.M. P.D.N. , S..R..G..M.. P..D..N..S... , ___ ___ , ___ ___
+SRGM PDNS. R.G.M. P.D.N. , S..R..G..M.. P..D..N..S... , , , , , , , , , , , , , ,
 
 \line("Tisram (3 per beat)")
-SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... ___ , ___ ___ ___
+SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... , , , , , , , , , , , , ,
 </notation>
 
 <h2>Tisram in Different Talas</h2>
@@ -45,8 +45,8 @@ <h3>Rupaka Tala (6 beats)</h3>
 <notation id="tisram-rupaka" showSource="true" caption="Tisram in Rupaka Tala">
 \cycle("|2|4|")
 \beatDuration(4)
-SRG MPD , NS. R.G. M.P. D.N. |
-S..R.. G..M.. , P..D.. N..S... ___
+SRG MPD , NS. R.G. M.P. D.N.
+S..R.. G..M.. , P..D.. N..S... , , ,
 </notation>
 
 <h3>Misra Chapu (7 beats)</h3>
@@ -54,8 +54,8 @@ <h3>Misra Chapu (7 beats)</h3>
 <notation id="tisram-chapu" showSource="true" caption="Tisram in Misra Chapu">
 \cycle("|3|2|2|")
 \beatDuration(4)
-SRG MPD NS. , R.G. M.P. , D.N. S..R.. |
-G..M.. P..D.. N..S... , ___ ___ , ___ ___
+SRG MPD NS. , R.G. M.P. , D.N. S..R..
+G..M.. P..D.. N..S... , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Kanda Chapu (5 beats) - Natural Tisram Feel</h2>
@@ -65,7 +65,7 @@ <h2>Kanda Chapu (5 beats) - Natural Tisram Feel</h2>
 <notation id="kanda-chapu" showSource="true" caption="Tisram in Kanda Chapu">
 \cycle("|2|3|")
 \beatDuration(4)
-SRG MPD , NS. R.G. M.P. |
+SRG MPD , NS. R.G. M.P.
 D.N. S..R.. , G..M.. P..D.. N..S...
 </notation>
 
@@ -76,7 +76,7 @@ <h3>Ascending Patterns</h3>
 <notation id="tisram-ascending" showSource="true" caption="Tisram Ascending Patterns">
 \cycle("|4|2|2|")
 \beatDuration(4)
-SRG RGM GMP MPD , PDN DNS. NS.R. S.R.G. , R.G.M. G.M.P. M.P.D. P.D.N. , D.N.S.. ___  ___ ___
+SRG RGM GMP MPD , PDN DNS. NS.R. S.R.G. , R.G.M. G.M.P. M.P.D. P.D.N. , D.N.S.. , , ,  , , , , , ,
 </notation>
 
 <h3>Descending Patterns</h3>
@@ -92,7 +92,7 @@ <h3>Mixed Patterns</h3>
 <notation id="tisram-mixed" showSource="true" caption="Tisram Mixed Patterns">
 \cycle("|4|2|2|")
 \beatDuration(4)
-SRG SRG MGP MGP , PDN PDN S.R.G. S.R.G. , M.P.D. M.P.D. N.S..R.. N.S..R.. , G..M..P.. ___ ___ ___
+SRG SRG MGP MGP , PDN PDN S.R.G. S.R.G. , M.P.D. M.P.D. N.S..R.. N.S..R.. , G..M..P.. , , , , , , , , ,
 </notation>
 
 <h2>Tisram with Gamakas</h2>
@@ -102,7 +102,7 @@ <h2>Tisram with Gamakas</h2>
 <notation id="tisram-gamakas" showSource="true" caption="Tisram with Gamakas">
 \cycle("|4|2|2|")
 \beatDuration(4)
-(SRG kampitam) MPD NS.R.G. (M.P.D. jaru N.S..) , (S..D..N.. kampitam) N..S..P.. P..M..G.. (MGR jaru S) , ___ ___ ___ ___ , ___ ___ ___ ___
+~ SRG MPD NS.R.G. M.P.D. ~/ N.S.. , ~ S..D..N.. N..S..P.. P..M..G.. MGR ~/ S , , , , , , , , , , , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Converting from Chatusram to Tisram</h2>
@@ -113,10 +113,10 @@ <h2>Converting from Chatusram to Tisram</h2>
 \cycle("|4|2|2|")
 \beatDuration(4)
 \line("Original (Chatusram - 4 per beat)")
-SRGM PDNS. R.G.M.P. D.N.S..R.. , ___ ___ ___ ___ , ___ ___ ___ ___ , ___ ___ ___ ___
+SRGM PDNS. R.G.M.P. D.N.S..R.. , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
 
 \line("Converted (Tisram - 3 per beat)")
-SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... ___ ___ , ___ ___ ___ ___
+SRG MPD NS. R.G. , M.P. D.N. S..R.. G..M.. , P..D.. N..S... , , , , , , , , , , , , , , , , , , ,
 </notation>
 
 <h2>Practical Tips</h2>
diff --git a/docs/content/index.html b/docs/content/index.html
index 0f561db..e3f67e4 100644
--- a/docs/content/index.html
+++ b/docs/content/index.html
@@ -47,7 +47,7 @@ <h2>Quick Example</h2>
     <notation id="example1" showSource="true" caption="Basic Notation Example">
 Sw: S R G M P D N S.
 Sh: sa ri ga ma pa dha ni sa
-    </notation>
+</notation>
 
     <p class="note">See more in the <a href="{{.Site.PathPrefix}}/examples/">Examples</a> section</p>
 </div>
diff --git a/docs/content/reference/embellishments/index.html b/docs/content/reference/embellishments/index.html
index 5cd1e63..e91ed13 100644
--- a/docs/content/reference/embellishments/index.html
+++ b/docs/content/reference/embellishments/index.html
@@ -22,7 +22,7 @@ <h3>Kampitam (~)</h3>
 
 <notation id="kampitam" showSource="true" caption="Kampitam">
 \beatDuration(4)
-S R ~ G M P ~
+S ~ R G ~ M P
 </notation>
 
 <p>Example usage: <code>p , S..n S..n S..n</code> shows kampitam oscillating between notes.</p>
@@ -75,7 +75,7 @@ <h3>Kandippu (~✓ or ~./ or ~.\)</h3>
 
 <notation id="kandippu" showSource="true" caption="Kandippu">
 \beatDuration(4)
-S. , , , n ~./ , P , , ,
+S. , , , ~./ n , P , , ,
 </notation>
 
 <h3>Vaali (~~)</h3>
@@ -115,7 +115,7 @@ <h3>Spuritam (~∴ or ~:-)</h3>
 
 <notation id="spuritam" showSource="true" caption="Spuritam">
 \beatDuration(4)
-[S R] ~:- [G M]
+[S R] [~:- G M]
 </notation>
 
 <h3>Prathyagatam (~∵ or ~-:)</h3>
@@ -124,7 +124,7 @@ <h3>Prathyagatam (~∵ or ~-:)</h3>
 
 <notation id="prathyagatam" showSource="true" caption="Prathyagatam">
 \beatDuration(4)
-[M G] ~-: [R S]
+[M G] [~-: R S]
 </notation>
 
 <h2>Gamaka Summary Table</h2>
diff --git a/docs/content/reference/syntax/index.html b/docs/content/reference/syntax/index.html
index d8ab904..3a6ba16 100644
--- a/docs/content/reference/syntax/index.html
+++ b/docs/content/reference/syntax/index.html
@@ -69,7 +69,7 @@ <h3>Spaces (Karvais)</h3>
   <tbody>
     <tr><td><code>,</code></td><td>Space (Karvai)</td><td>1 unit</td></tr>
     <tr><td><code>;</code></td><td>Double space</td><td>2 units</td></tr>
-    <tr><td><code>_</code></td><td>Silent space</td><td>1 unit (not displayed)</td></tr>
+    <tr><td><code>_</code></td><td>Silent space (not implemented yet)</td><td>1 unit (not displayed)</td></tr>
   </tbody>
 </table>
 
@@ -77,7 +77,7 @@ <h3>Spaces (Karvais)</h3>
 S , R ; G , , M
 </notation>
 
-<p>Silent spaces consume duration without displaying the space symbol, useful to avoid clutter.</p>
+<p>Silent spaces are meant to consume duration without displaying the space symbol, to avoid clutter. They are not implemented yet, so use <code>,</code> for now.</p>
 
 <h3>Rests</h3>
 
@@ -147,7 +147,7 @@ <h2>Embellishments</h2>
 <p>Embellishments start with a tilde and continue until whitespace:</p>
 
 <notation id="embellishments" showSource="true" caption="Embellishments">
-S ~kampita R G ~jaru M
+S ~ R G ~/ M
 </notation>
 
 <p>See the <a href="{{.Site.PathPrefix}}/reference/embellishments/">Embellishments Reference</a> for details.</p>
@@ -197,20 +197,22 @@ <h3>Per-Role Markers</h3>
 
 <h2>Comments</h2>
 
-<p>Use <code>//</code> for line comments:</p>
+<p>Use <code>//</code> for line comments. Everything from the <code>//</code> to the end of the
+line is skipped, whether it starts the line or trails the notation on it:</p>
 
-<pre><code>// This is a comment
+<notation id="line-comments" showSource="true" caption="Line Comments">
+// This is a comment
 S R G M
-// Comments are ignored by the parser
-P D N S.
-</code></pre>
+P D N S.   // and this one trails the notation
+</notation>
 
-<p>Block comments are also supported:</p>
+<p>Block comments work the same way and can span lines:</p>
 
-<pre><code>/* This is a
+<notation id="block-comments" showSource="true" caption="Block Comments">
+/* This is a
    multi-line comment */
 S R G M
-</code></pre>
+</notation>
 
 <h2>Grammar Summary</h2>
 
diff --git a/docs/content/tutorials/01-basics/index.html b/docs/content/tutorials/01-basics/index.html
index 8ce2aa9..ed33d6e 100644
--- a/docs/content/tutorials/01-basics/index.html
+++ b/docs/content/tutorials/01-basics/index.html
@@ -48,7 +48,7 @@ <h2 id="spaces-karvais">Spaces (Karvais)</h2>
 <p>Spaces indicate empty durations where the previous note continues. Use commas:</p>
 
 <notation id="spacing" showSource="true" caption="Notes with Spaces">
-, S , R , , G M; P ; 
+, S , R , , G M; P ;
 D N S. ,
 </notation>
 
@@ -65,8 +65,8 @@ <h2 id="spaces-karvais">Spaces (Karvais)</h2>
 
 <notation id="double-space" showSource="true" caption="Double Spaces">
 S ; R ; G ,
-M ; P ; D , 
-N , ; S. ; , 
+M ; P ; D ,
+N , ; S. ; ,
 </notation>
 
 <h2 id="groups">Groups</h2>
diff --git a/docs/content/tutorials/02-commands/index.html b/docs/content/tutorials/02-commands/index.html
index 0685b69..eab2a78 100644
--- a/docs/content/tutorials/02-commands/index.html
+++ b/docs/content/tutorials/02-commands/index.html
@@ -23,16 +23,16 @@ <h2 id="beat-duration">Beat Duration</h2>
 
 <notation id="beat-duration-4" showSource="true" caption="Four Notes per Beat (Second Speed)">
 \beatDuration(4)
-    S S R - S S R - S R     S S R R     G G M M       
-    R R G - R R G - R G     R R G G     M M P P       
-    G G M - G G M - G M     G G M M     P P D D       
-    M M P - M M P - M P     M M P P     D D N N       
-    P P D - P P D - P D     P P D D     N N S. S.       
-    S. S. N - S. S. N - S. N     S. S. N N     D D P P       
-    N N D - N N D - N D     N N D D     P P M M       
-    D D P - D D P - D P     D D P P     M M G G       
-    P P M - P P M - P M     P P M M     G G R R       
-    M M G - M M G - M G     M M G G     R R S S     
+    S S R - S S R - S R     S S R R     G G M M
+    R R G - R R G - R G     R R G G     M M P P
+    G G M - G G M - G M     G G M M     P P D D
+    M M P - M M P - M P     M M P P     D D N N
+    P P D - P P D - P D     P P D D     N N S. S.
+    S. S. N - S. S. N - S. N     S. S. N N     D D P P
+    N N D - N N D - N D     N N D D     P P M M
+    D D P - D D P - D P     D D P P     M M G G
+    P P M - P P M - P M     P P M M     G G R R
+    M M G - M M G - M G     M M G G     R R S S
 </notation>
 
 <p>This is commonly used to notate different speeds in Carnatic music without changing the actual notation.</p>
diff --git a/docs/tests/examples.spec.ts b/docs/tests/examples.spec.ts
new file mode 100644
index 0000000..4fb7db8
--- /dev/null
+++ b/docs/tests/examples.spec.ts
@@ -0,0 +1,107 @@
+import * as fs from "fs";
+import * as path from "path";
+import { load } from "../../src/loader";
+
+const CONTENT_ROOT = path.resolve(__dirname, "..", "content");
+
+type Example = { file: string; id: string; body: string };
+
+function htmlFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...htmlFiles(full));
+    else if (entry.name.endsWith(".html")) out.push(full);
+  }
+  return out;
+}
+
+function decode(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+
+// Drops commented-out regions, which never reach the browser and so are not examples. A single
+// regex replace leaves a dangling `<!--` behind when a comment is unterminated, so this walks the
+// string the way a browser does: a comment runs to the next `-->`, and one that never closes
+// swallows the rest of the document.
+export function stripComments(html: string): string {
+  let out = "";
+  let cursor = 0;
+  while (cursor < html.length) {
+    const start = html.indexOf("<!--", cursor);
+    if (start < 0) {
+      out += html.slice(cursor);
+      break;
+    }
+    out += html.slice(cursor, start);
+    const end = html.indexOf("-->", start + "<!--".length);
+    if (end < 0) break;
+    cursor = end + "-->".length;
+  }
+  return out;
+}
+
+function collect(): Example[] {
+  const out: Example[] = [];
+  for (const file of htmlFiles(CONTENT_ROOT)) {
+    const src = stripComments(fs.readFileSync(file, "utf8"));
+    for (const m of src.matchAll(/<notation\s([^>]*)>([\s\S]*?)<\/notation>/g)) {
+      const body = decode(m[2]).trim();
+      // The visual-tests page builds its <notation> elements from a Go range, so its body is a
+      // template rather than notation.
+      if (body.includes("{{")) continue;
+      const id = /id="([^"]*)"/.exec(m[1])?.[1] ?? path.basename(path.dirname(file));
+      out.push({ file: path.relative(CONTENT_ROOT, file), id, body });
+    }
+  }
+  return out;
+}
+
+const examples = collect();
+
+describe("stripComments", () => {
+  test("removes a comment and keeps what surrounds it", () => {
+    expect(stripComments("a<!-- b -->c")).toBe("ac");
+  });
+
+  test("removes every comment in the string", () => {
+    expect(stripComments("a<!--x-->b<!--y-->c")).toBe("abc");
+  });
+
+  test("drops the rest of the document when a comment never closes", () => {
+    expect(stripComments("a<!-- b")).toBe("a");
+  });
+
+  test("leaves no comment opener behind", () => {
+    expect(stripComments("<!--<!-- -->tail")).toBe("tail");
+    expect(stripComments("a<!--b-->c<!--d")).not.toContain("<!--");
+  });
+});
+
+describe("Docs site examples", () => {
+  test("the page set is non-empty", () => {
+    expect(examples.length).toBeGreaterThan(100);
+  });
+
+  // NotationBlock.updatePreview renders nothing when load() reports errors, so an example that
+  // does not parse is a blank box on the published site with the reason only in the console.
+  describe.each(examples.map((e) => [`${e.file} #${e.id}`, e] as const))("%s", (_label, example) => {
+    test("parses with no errors", () => {
+      const [, , errors] = load(example.body + "\n");
+      expect(errors.map((e: any) => e.message)).toEqual([]);
+    });
+
+    // Underscores lex as ordinary identifier characters, so a silent space renders as visible
+    // text rather than failing. Guards against that reappearing while issue 17 is open.
+    test("has no underscore literal standing in for a silent space", () => {
+      const [notation] = load(example.body + "\n");
+      const literals = JSON.stringify(notation.debugValue()).match(/"value":"(_+)"/g) ?? [];
+      expect(literals).toEqual([]);
+    });
+  });
+});