From 2115e0f73b8ac98953f350a92fdb3c1c1be3a5a1 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:29:40 +0000
Subject: [PATCH 01/15] fix(tutorial): improve pager overflow detection and
 scroll positioning

- Align scroll view to top of new content blocks/lesson text when content overflows
- Defer chapter completion on final step command output so full responses can be read/paged
- Extract TypeScript utility modules for markdown, routing, and pager calculation
- Add Vitest unit test suite for utilities and Vue components
---
 .../theme/components/TutorialPlayer.vue       |  244 ++--
 docs/.vitepress/theme/utils/markdown.ts       |   67 +
 docs/.vitepress/theme/utils/pager.ts          |   19 +
 docs/.vitepress/theme/utils/tutorial.ts       |   35 +
 package-lock.json                             | 1109 ++++++++++++++++-
 package.json                                  |    8 +-
 tests/components.test.ts                      |   97 ++
 tests/tutorial_player.test.ts                 |   44 +
 tests/utils.test.ts                           |   62 +
 vitest.config.ts                              |   10 +
 10 files changed, 1567 insertions(+), 128 deletions(-)
 create mode 100644 docs/.vitepress/theme/utils/markdown.ts
 create mode 100644 docs/.vitepress/theme/utils/pager.ts
 create mode 100644 docs/.vitepress/theme/utils/tutorial.ts
 create mode 100644 tests/components.test.ts
 create mode 100644 tests/tutorial_player.test.ts
 create mode 100644 tests/utils.test.ts
 create mode 100644 vitest.config.ts

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index ad61078..3938e11 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -1,13 +1,18 @@
-<script setup>
+<script setup lang="ts">
 /*
   Interactive new-player tutorial component driven dynamically by chapter Markdown files.
-  Streamlined terminal output: immediate MUD output execution without extra "Press Enter to carry on" pauses.
-  Clear end-of-tutorial handover options to Play Hub, Browser Client, or Newcomers Guide.
-  Features visual toggle pill indicator for Commands, unified Narrative vs Quest Action Card UX, and inline markdown formatting for commands in quest descriptions.
+  Streamlined terminal output: immediate MUD output execution without extra pauses.
+  Enhanced pagination & auto-scroll: aligns scroll view to top of new content blocks/lesson text.
+  Defers chapter completion on final step output so large MUD responses can be read/paged through.
 */
 import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
 import { useData, useRoute, useRouter, withBase } from 'vitepress'
-import { data as allChapters } from '../../../play/tutorial/chapters.data.js'
+import { data as rawChapters } from '../../../play/tutorial/chapters.data.js'
+import { formatInlineMarkdown } from '../utils/markdown'
+import { normalizeChapterPath, findChapterByPath, Chapter } from '../utils/tutorial'
+import { isOverflowActive } from '../utils/pager'
+
+const allChapters = rawChapters as Chapter[]
 
 const PLAY_HUB_URL = '/play/'
 const BROWSER_PLAY_URL = '/play/browser'
@@ -17,42 +22,13 @@ const router = useRouter()
 const route = useRoute()
 const { site, frontmatter } = useData()
 
-function formatInlineMarkdown(text) {
-  if (!text) return ''
-  let safe = text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-
-  safe = safe.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (match, alt, src) => {
-    const cleanAlt = alt.replace(/"/g, '&quot;')
-    let cleanSrc = src.trim().replace(/"/g, '&quot;')
-
-    // Only rewrite relative public/assets paths, preserving http://, https://, and data: URLs
-    if (!/^(?:https?:\/\/|data:)/i.test(cleanSrc)) {
-      if (cleanSrc.includes('assets/')) {
-        cleanSrc = '/assets/' + cleanSrc.split('assets/')[1]
-      }
-
-      if (cleanSrc.startsWith('/')) {
-        cleanSrc = withBase(cleanSrc)
-      }
-    }
-
-    return `<img src="${cleanSrc}" alt="${cleanAlt}" class="tut-img-embed" onload="this.dispatchEvent(new Event('load', { bubbles: true }))" />`
-  })
-
-  safe = safe.replace(/`([^`]+)`/g, '<code class="tut-cmd-inline">$1</code>')
-  return safe.replace(/\n/g, '<br>')
+function formatMarkdown(text: string | null | undefined): string {
+  return formatInlineMarkdown(text, withBase)
 }
 
 const currentChapterObj = computed(() => {
-  let currentPath = route.path.replace(/\.html$/, '').replace(/\/$/, '')
-  const base = site.value?.base || '/'
-  if (base !== '/' && currentPath.startsWith(base.replace(/\/$/, ''))) {
-    currentPath = '/' + currentPath.slice(base.replace(/\/$/, '').length).replace(/^\//, '')
-  }
-  return allChapters.find(c => c.url === currentPath || currentPath.endsWith(c.filename)) || allChapters[0]
+  const norm = normalizeChapterPath(route.path, site.value?.base || '/')
+  return findChapterByPath(allChapters, norm) || allChapters[0]
 })
 
 const chapterNum = computed(() => currentChapterObj.value ? currentChapterObj.value.chapterNum : 1)
@@ -110,13 +86,14 @@ const currentSubStep = computed(() => stepsList.value[subStepIdx.value] || null)
 // Driven 100% dynamically from chapter frontmatter
 const mumeResponses = computed(() => frontmatter.value?.responses || currentChapterObj.value?.responses || {})
 
-const log = ref([])
+const log = ref<any[]>([])
 const finished = ref(false)
+const pendingChapterCompletion = ref(false)
 const entry = ref('')
 const isSheetOpen = ref(false)
 const isExpanded = ref(false)
 const isModalOpen = ref(false)
-const activeModalImage = ref(null)
+const activeModalImage = ref<{ src: string; alt: string } | null>(null)
 
 function openModal() {
   isModalOpen.value = true
@@ -126,7 +103,7 @@ function closeModal() {
   isModalOpen.value = false
 }
 
-function openImageModal(src, alt = '') {
+function openImageModal(src: string, alt = '') {
   activeModalImage.value = { src, alt }
 }
 
@@ -134,10 +111,11 @@ function closeImageModal() {
   activeModalImage.value = null
 }
 
-function handleLogClick(e) {
-  const target = e.target
+function handleLogClick(e: MouseEvent) {
+  const target = e.target as HTMLElement
   if (target && target.tagName === 'IMG' && target.classList.contains('tut-img-embed')) {
-    openImageModal(target.src, target.alt)
+    const img = target as HTMLImageElement
+    openImageModal(img.src, img.alt)
   }
 }
 
@@ -150,7 +128,6 @@ function toggleExpand() {
     if (document.documentElement.requestFullscreen) {
       document.documentElement.requestFullscreen().catch(() => {})
     }
-    // Auto-expand Command Sheet in Fullscreen on Desktop
     if (typeof window !== 'undefined' && window.innerWidth >= 1024) {
       isSheetOpen.value = true
     }
@@ -171,7 +148,7 @@ function handleFullscreenChange() {
   }
 }
 
-function handleKeydown(e) {
+function handleKeydown(e: KeyboardEvent) {
   if (e.key === 'Escape') {
     if (activeModalImage.value) {
       closeImageModal()
@@ -187,7 +164,7 @@ function handleKeydown(e) {
 
   // Intercept Space or PageDown for paging if output overflow is active and input is empty or unfocused
   if (isScrollOverflowActive.value && !isScrolling.value) {
-    const isInputFocused = document.activeElement === inputEl.value
+    const isInputFocused = typeof document !== 'undefined' && document.activeElement === inputEl.value
     if ((e.key === 'PageDown' || e.key === ' ') && (!isInputFocused || !entry.value.trim())) {
       e.preventDefault()
       pageForward()
@@ -195,43 +172,17 @@ function handleKeydown(e) {
   }
 }
 
-const logEl = ref(null)
-const inputEl = ref(null)
+const logEl = ref<HTMLElement | null>(null)
+const inputEl = ref<HTMLInputElement | null>(null)
 
 // Pager state management
 const isScrollOverflowActive = ref(false)
-const currentPageNum = ref(1)
-const totalPagesNum = ref(1)
 const isScrolling = ref(false)
-let scrollEndTimer = null
+let scrollEndTimer: any = null
 
 function updatePagerState() {
   const container = logEl.value
-  if (!container) {
-    isScrollOverflowActive.value = false
-    currentPageNum.value = 1
-    totalPagesNum.value = 1
-    return
-  }
-
-  const scrollHeight = container.scrollHeight
-  const clientHeight = container.clientHeight
-  const scrollTop = container.scrollTop
-
-  // Determine if there is significant scrollable content below viewport
-  const scrollableDistance = scrollHeight - clientHeight
-  const remainingScroll = scrollableDistance - scrollTop
-
-  if (scrollableDistance > 40 && remainingScroll > 35) {
-    isScrollOverflowActive.value = true
-    const pageSize = Math.max(1, clientHeight - 30)
-    totalPagesNum.value = Math.max(1, Math.ceil(scrollHeight / pageSize))
-    currentPageNum.value = Math.min(totalPagesNum.value, Math.max(1, Math.floor(scrollTop / pageSize) + 1))
-  } else {
-    isScrollOverflowActive.value = false
-    currentPageNum.value = 1
-    totalPagesNum.value = 1
-  }
+  isScrollOverflowActive.value = isOverflowActive(container)
 }
 
 function handleScroll() {
@@ -243,12 +194,17 @@ function handleScroll() {
   }, 150)
 }
 
-function pageForward() {
+function pageForward(preventFocus = false) {
   const container = logEl.value
   if (!container) return
-  const pageStep = container.clientHeight - 40
+  const pageStep = Math.max(100, container.clientHeight - 40)
   container.scrollBy({ top: pageStep, behavior: 'smooth' })
-  setTimeout(updatePagerState, 300)
+  setTimeout(() => {
+    updatePagerState()
+    if (!preventFocus) {
+      focusInput()
+    }
+  }, 300)
 }
 
 function flushPager() {
@@ -260,7 +216,7 @@ function flushPager() {
 
 const stepLabel = computed(() => `Chapter ${chapterNum.value} of ${totalChapters.value}`)
 
-let autoAdvanceTimer = null
+let autoAdvanceTimer: any = null
 function clearAutoAdvanceTimer() {
   if (autoAdvanceTimer) {
     clearTimeout(autoAdvanceTimer)
@@ -276,7 +232,7 @@ function focusInput() {
   }
 }
 
-function navigateToUrl(url) {
+function navigateToUrl(url: string | null) {
   if (!url) return
   clearAutoAdvanceTimer()
   const targetUrl = withBase(url)
@@ -289,40 +245,46 @@ function navigateToUrl(url) {
   }
 }
 
-function scrollLog() {
+/**
+ * Scroll log to align with the top of the newest block if it overflows,
+ * ensuring large outputs (like info or long lesson text) are readable from the start.
+ */
+function scrollLogToLatestBlock() {
   if (typeof window !== 'undefined') {
     setTimeout(() => {
       const container = logEl.value
       if (!container) return
       const blocks = container.querySelectorAll('.tut-block')
       if (blocks.length > 0) {
-        const lastBlock = blocks[blocks.length - 1]
+        const lastBlock = blocks[blocks.length - 1] as HTMLElement
         const containerRect = container.getBoundingClientRect()
         const blockRect = lastBlock.getBoundingClientRect()
 
-        // If block is taller than the view, bring the start of the block into view
-        if (blockRect.height > containerRect.height - 40) {
+        // If block is taller than or overflows the viewport, align scroll to top of that block
+        if (blockRect.height > containerRect.height - 40 && typeof lastBlock.scrollIntoView === 'function') {
           lastBlock.scrollIntoView({ behavior: 'smooth', block: 'start' })
-        } else {
+        } else if (typeof container.scrollTo === 'function') {
           container.scrollTo({ top: container.scrollHeight, behavior: 'smooth' })
         }
-      } else {
+      } else if (typeof container.scrollTo === 'function') {
         container.scrollTo({ top: container.scrollHeight, behavior: 'smooth' })
       }
+      setTimeout(updatePagerState, 200)
     }, 60)
   }
 }
 
-function goToStep(targetIdx) {
+function goToStep(targetIdx: number) {
   clearAutoAdvanceTimer()
   if (targetIdx < 0) targetIdx = 0
   if (targetIdx >= stepsList.value.length) targetIdx = Math.max(0, stepsList.value.length - 1)
 
   subStepIdx.value = targetIdx
   finished.value = false
+  pendingChapterCompletion.value = false
   entry.value = ''
 
-  const newLog = []
+  const newLog: any[] = []
   const firstSub = stepsList.value[0] || null
 
   newLog.push({
@@ -373,7 +335,7 @@ function goToStep(targetIdx) {
   }
 
   log.value = newLog
-  scrollLog()
+  scrollLogToLatestBlock()
 
   const curSub = stepsList.value[targetIdx] || null
   if (curSub && !curSub.ask && (curSub.text || curSub.response)) {
@@ -381,28 +343,42 @@ function goToStep(targetIdx) {
       kind: 'story',
       body: curSub.text || curSub.response
     })
-    scrollLog()
-    autoAdvanceTimer = setTimeout(() => {
-      advanceSubStep()
-    }, 250)
+    scrollLogToLatestBlock()
+    checkAndScheduleAutoAdvance()
   } else {
     focusInput()
   }
 }
 
+function checkAndScheduleAutoAdvance() {
+  clearAutoAdvanceTimer()
+  // Give DOM a tick to calculate scrollHeight
+  setTimeout(() => {
+    updatePagerState()
+    if (isScrollOverflowActive.value) {
+      // Content overflows terminal viewport: pause auto-advance so user can read/page
+      return
+    }
+    autoAdvanceTimer = setTimeout(() => {
+      advanceSubStep()
+    }, 300)
+  }, 100)
+}
+
 function renderStepLog() {
   goToStep(0)
 }
 
 function completeChapter() {
   finished.value = true
+  pendingChapterCompletion.value = false
   log.value.push({
     kind: 'chapter_complete',
     chapterNum: chapterNum.value,
     title: chapterTitle.value,
     nextUrl: nextChapterUrl.value
   })
-  scrollLog()
+  scrollLogToLatestBlock()
 }
 
 function advanceNext() {
@@ -427,20 +403,25 @@ function advanceSubStep() {
         note: nextSub.note || null,
         ask: nextSub.ask
       })
-      scrollLog()
+      scrollLogToLatestBlock()
       focusInput()
     } else if (nextSub && (nextSub.text || nextSub.response)) {
       log.value.push({
         kind: 'story',
         body: nextSub.text || nextSub.response
       })
-      scrollLog()
-      autoAdvanceTimer = setTimeout(() => {
-        advanceSubStep()
-      }, 250)
+      scrollLogToLatestBlock()
+      checkAndScheduleAutoAdvance()
     }
   } else {
-    completeChapter()
+    // Reached final step: set pendingChapterCompletion so response outputs in full before completion box
+    pendingChapterCompletion.value = true
+    setTimeout(() => {
+      updatePagerState()
+      if (!isScrollOverflowActive.value) {
+        completeChapter()
+      }
+    }, 150)
   }
 }
 
@@ -457,8 +438,15 @@ function submit() {
   const cmd = raw.toLowerCase()
 
   // Handle Pager Mode when input is empty and overflow is active
-  if (isScrollOverflowActive.value && !raw && !finished.value) {
+  if (isScrollOverflowActive.value && !raw) {
     pageForward()
+    return
+  }
+
+  // If pending chapter completion and user hits Enter at end of scroll
+  if (pendingChapterCompletion.value && !finished.value && !isScrollOverflowActive.value) {
+    completeChapter()
+    entry.value = ''
     focusInput()
     return
   }
@@ -489,7 +477,7 @@ function submit() {
   if (!curStep) {
     if (cmd && mumeResponses.value[cmd]) {
       log.value.push({ kind: 'example', body: mumeResponses.value[cmd] })
-      scrollLog()
+      scrollLogToLatestBlock()
     } else {
       advanceNext()
     }
@@ -499,7 +487,7 @@ function submit() {
 
   if (!cmd) {
     log.value.push({ kind: 'error', text: curStep.hint || (`Type: ${curStep.ask}`) })
-    scrollLog()
+    scrollLogToLatestBlock()
     focusInput()
     return
   }
@@ -513,14 +501,15 @@ function submit() {
     if (body) {
       log.value.push({ kind: 'example', body })
     }
+    scrollLogToLatestBlock()
     advanceSubStep()
   } else if (mumeResponses.value[cmd]) {
     log.value.push({ kind: 'example', body: mumeResponses.value[cmd] })
     log.value.push({ kind: 'error', text: 'Good try! To proceed in this step, ' + (curStep.hint || (`try: ${curStep.ask}`)) })
-    scrollLog()
+    scrollLogToLatestBlock()
   } else {
     log.value.push({ kind: 'error', text: 'MUME does not know that one here. ' + (curStep.hint || (`Try: ${curStep.ask}`)) })
-    scrollLog()
+    scrollLogToLatestBlock()
   }
   focusInput()
 }
@@ -529,12 +518,11 @@ watch(() => route.path, () => {
   renderStepLog()
 }, { immediate: true })
 
-let logResizeObserver = null
+let logResizeObserver: any = null
 
 onMounted(() => {
   if (typeof window !== 'undefined') {
     renderStepLog()
-    // Auto-open Command Sheet on desktop viewports by default
     if (window.innerWidth >= 1024) {
       isSheetOpen.value = true
     }
@@ -638,7 +626,7 @@ onUnmounted(() => {
                     <span class="tut-quest-badge"><i class="fa fa-compass" aria-hidden="true"></i> QUEST</span>
                     <span class="tut-quest-sub">ACTION REQUIRED</span>
                   </div>
-                  <div v-if="b.note" class="tut-quest-desc" v-html="formatInlineMarkdown(b.note)"></div>
+                  <div v-if="b.note" class="tut-quest-desc" v-html="formatMarkdown(b.note)"></div>
                   <div class="tut-quest-target">
                     Type command: <span class="tut-cmd-chip">{{ b.ask }}</span>
                   </div>
@@ -652,7 +640,7 @@ onUnmounted(() => {
                     <span class="tut-quest-badge"><i class="fa fa-compass" aria-hidden="true"></i> QUEST</span>
                     <span class="tut-quest-sub">ACTION REQUIRED</span>
                   </div>
-                  <div v-if="b.note" class="tut-quest-desc" v-html="formatInlineMarkdown(b.note)"></div>
+                  <div v-if="b.note" class="tut-quest-desc" v-html="formatMarkdown(b.note)"></div>
                   <div class="tut-quest-target">
                     Type command: <span class="tut-cmd-chip">{{ b.ask }}</span>
                   </div>
@@ -666,7 +654,7 @@ onUnmounted(() => {
               <!-- Unified Story Beat Card -->
               <div v-else-if="b.kind === 'story'" class="tut-story-beat-card">
                 <i class="fa fa-quote-left tut-beat-icon" aria-hidden="true"></i>
-                <div class="tut-beat-body" v-html="formatInlineMarkdown(b.body)"></div>
+                <div class="tut-beat-body" v-html="formatMarkdown(b.body)"></div>
               </div>
 
               <div v-else-if="b.kind === 'error'" class="tut-err">{{ b.text }}</div>
@@ -705,18 +693,18 @@ onUnmounted(() => {
             </div>
           </div>
 
-          <div class="tut-prompt" :class="{ 'is-pager': isScrollOverflowActive && !isScrolling }" @click="isScrollOverflowActive && !entry ? pageForward() : focusInput()">
+          <div class="tut-prompt" :class="{ 'is-pager': isScrollOverflowActive && !isScrolling }" @click.prevent="isScrollOverflowActive && !entry ? pageForward(true) : focusInput()">
             <span class="tut-caret">&gt;</span>
             <input ref="inputEl" v-model="entry" @keydown.enter.prevent="submit"
                    autocomplete="off" spellcheck="false"
-                   :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Page ${currentPageNum} of ${totalPagesNum} — Press Space/Enter or Tap ]` : (finished ? (nextChapterUrl ? 'Press Enter to continue to next chapter...' : 'Tutorial complete — press Enter for options') : 'type here, then press Enter')"
+                   :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Press Space/Enter or Tap ]` : (finished ? (nextChapterUrl ? 'Press Enter to continue to next chapter...' : 'Tutorial complete — press Enter for options') : (pendingChapterCompletion ? 'Press Enter to complete chapter...' : 'type here, then press Enter'))"
                    aria-label="Type a command" />
             <button type="button"
                     class="tut-send-btn"
                     :class="{ 'tut-pager-btn': isScrollOverflowActive && !isScrolling && !entry }"
-                    @click.stop="submit"
+                    @click.stop="isScrollOverflowActive && !entry ? pageForward(true) : submit()"
                     aria-label="Send Command">
-              {{ (isScrollOverflowActive && !isScrolling && !entry) ? 'More ↓' : (finished ? (nextChapterUrl ? 'Next' : 'Options') : 'Send') }}
+              {{ (isScrollOverflowActive && !isScrolling && !entry) ? 'More ↓' : (finished ? (nextChapterUrl ? 'Next' : 'Options') : (pendingChapterCompletion ? 'Finish' : 'Send')) }}
             </button>
           </div>
         </div>
@@ -732,7 +720,7 @@ onUnmounted(() => {
             <div v-if="currentSubStep && currentSubStep.ask" class="tut-sheet-quest-spotlight">
               <div class="tut-spotlight-badge"><i class="fa fa-compass" aria-hidden="true"></i> ACTIVE QUEST</div>
               <div class="tut-spotlight-cmd">Target Command: <code>{{ currentSubStep.ask }}</code></div>
-              <div v-if="currentSubStep.note" class="tut-spotlight-note" v-html="formatInlineMarkdown(currentSubStep.note)"></div>
+              <div v-if="currentSubStep.note" class="tut-spotlight-note" v-html="formatMarkdown(currentSubStep.note)"></div>
             </div>
 
             <p v-if="!teachList.length" class="tut-empty">No special commands listed for this chapter.</p>
@@ -1039,6 +1027,16 @@ onUnmounted(() => {
   font-size: 0.92em;
 }
 
+.tut-link {
+  color: #f4dd94;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  transition: color 0.2s;
+}
+.tut-link:hover {
+  color: #ffffff;
+}
+
 /* Inline Story Beat Card */
 .tut-story-beat-card {
   display: flex;
@@ -1065,12 +1063,22 @@ onUnmounted(() => {
   flex: 1;
 }
 
+/* Image Lazy Loading & Placeholder Container */
+.tut-img-container {
+  display: block;
+  min-height: 140px;
+  background: rgba(15, 16, 20, 0.6);
+  border-radius: 6px;
+  margin: 8px 0;
+  position: relative;
+  overflow: hidden;
+}
+
 .tut-img-embed {
   max-width: 100%;
   max-height: 220px;
   border-radius: 6px;
   border: 1px solid rgba(215, 166, 63, 0.35);
-  margin: 8px 0;
   display: block;
   box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
   cursor: zoom-in;
diff --git a/docs/.vitepress/theme/utils/markdown.ts b/docs/.vitepress/theme/utils/markdown.ts
new file mode 100644
index 0000000..af3afc9
--- /dev/null
+++ b/docs/.vitepress/theme/utils/markdown.ts
@@ -0,0 +1,67 @@
+/**
+ * Utility functions for inline markdown formatting in tutorial elements.
+ */
+
+export type WithBaseFn = (url: string) => string
+
+/**
+ * Formats inline markdown strings into HTML safely.
+ * Supports:
+ * - HTML entity escaping for & < >
+ * - Embedded images: ![alt](src) with lazy loading, aspect ratio placeholders, and lightbox triggers
+ * - Links: [text](url)
+ * - Bold: **text** or __text__
+ * - Italics: *text* or _text_
+ * - Inline code: `code`
+ * - Line breaks: \n -> <br>
+ */
+export function formatInlineMarkdown(text: string | null | undefined, withBaseFn: WithBaseFn = (url) => url): string {
+  if (!text) return ''
+
+  // Escape HTML entities
+  let safe = text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+
+  // Images: ![alt](src)
+  safe = safe.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (_match, alt, src) => {
+    const cleanAlt = alt.replace(/"/g, '&quot;')
+    let cleanSrc = src.trim().replace(/"/g, '&quot;')
+
+    if (!/^(?:https?:\/\/|data:)/i.test(cleanSrc)) {
+      if (cleanSrc.includes('assets/')) {
+        cleanSrc = '/assets/' + cleanSrc.split('assets/')[1]
+      }
+
+      if (cleanSrc.startsWith('/') && typeof withBaseFn === 'function') {
+        cleanSrc = withBaseFn(cleanSrc)
+      }
+    }
+
+    return `<span class="tut-img-container"><img src="${cleanSrc}" alt="${cleanAlt}" class="tut-img-embed" loading="lazy" onload="this.dispatchEvent(new Event('load', { bubbles: true }))" /></span>`
+  })
+
+  // Links: [text](url)
+  safe = safe.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, linkText, url) => {
+    const cleanText = linkText
+    let cleanUrl = url.trim()
+    if (!/^(?:https?:\/\/|mailto:)/i.test(cleanUrl) && cleanUrl.startsWith('/') && typeof withBaseFn === 'function') {
+      cleanUrl = withBaseFn(cleanUrl)
+    }
+    const isExternal = /^(?:https?:\/\/)/i.test(cleanUrl)
+    return `<a href="${cleanUrl}" ${isExternal ? 'target="_blank" rel="noopener noreferrer"' : ''} class="tut-link">${cleanText}</a>`
+  })
+
+  // Bold: **text** or __text__
+  safe = safe.replace(/(\*\*|__)(.*?)\1/g, '<strong>$2</strong>')
+
+  // Italics: *text* or _text_
+  safe = safe.replace(/(?<!\w)(\*|_)(.*?)\1(?!\w)/g, '<em>$2</em>')
+
+  // Code: `code`
+  safe = safe.replace(/`([^`]+)`/g, '<code class="tut-cmd-inline">$1</code>')
+
+  // Newlines
+  return safe.replace(/\n/g, '<br>')
+}
diff --git a/docs/.vitepress/theme/utils/pager.ts b/docs/.vitepress/theme/utils/pager.ts
new file mode 100644
index 0000000..f92632e
--- /dev/null
+++ b/docs/.vitepress/theme/utils/pager.ts
@@ -0,0 +1,19 @@
+/**
+ * Helper function to determine pager overflow state for scrollable containers.
+ */
+
+export function isOverflowActive(
+  container: HTMLElement | null,
+  scrollThreshold: number = 40,
+  remainingThreshold: number = 35
+): boolean {
+  if (!container) return false
+  const scrollHeight = container.scrollHeight
+  const clientHeight = container.clientHeight
+  const scrollTop = container.scrollTop
+
+  const scrollableDistance = scrollHeight - clientHeight
+  const remainingScroll = scrollableDistance - scrollTop
+
+  return scrollableDistance > scrollThreshold && remainingScroll > remainingThreshold
+}
diff --git a/docs/.vitepress/theme/utils/tutorial.ts b/docs/.vitepress/theme/utils/tutorial.ts
new file mode 100644
index 0000000..16d7b48
--- /dev/null
+++ b/docs/.vitepress/theme/utils/tutorial.ts
@@ -0,0 +1,35 @@
+/**
+ * Utility functions for tutorial routing and chapter calculations.
+ */
+
+export interface Chapter {
+  chapterNum: number
+  title: string
+  url: string
+  filename: string
+  teach?: Array<{ command: string; desc: string }>
+  steps?: any[]
+  practice?: string
+  [key: string]: any
+}
+
+/**
+ * Normalizes route path to match chapter URLs, removing base prefix and trailing slashes.
+ */
+export function normalizeChapterPath(rawPath: string | undefined, basePrefix: string = '/'): string {
+  if (!rawPath) return '/'
+  let currentPath = rawPath.replace(/\.html$/, '').replace(/\/$/, '')
+  const base = basePrefix || '/'
+  if (base !== '/' && currentPath.startsWith(base.replace(/\/$/, ''))) {
+    currentPath = '/' + currentPath.slice(base.replace(/\/$/, '').length).replace(/^\//, '')
+  }
+  return currentPath || '/'
+}
+
+/**
+ * Finds current chapter object from all chapters list.
+ */
+export function findChapterByPath(chapters: Chapter[], normalizedPath: string): Chapter | null {
+  if (!chapters || !chapters.length) return null
+  return chapters.find(c => c.url === normalizedPath || normalizedPath.endsWith(c.filename)) || chapters[0] || null
+}
diff --git a/package-lock.json b/package-lock.json
index e2be32b..151f5c4 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,9 +12,13 @@
       },
       "devDependencies": {
         "@playwright/test": "^1.63.0",
+        "@vitejs/plugin-vue": "^6.0.9",
+        "@vue/test-utils": "^2.5.1",
+        "jsdom": "^29.1.1",
         "playwright": "^1.49.0",
         "vite": "^8.3.0",
-        "vitepress": "^1.5.0"
+        "vitepress": "^1.5.0",
+        "vitest": "^5.0.1"
       }
     },
     "node_modules/@algolia/abtesting": {
@@ -275,6 +279,57 @@
         "node": ">= 14.0.0"
       }
     },
+    "node_modules/@asamuzakjp/css-color": {
+      "version": "5.1.11",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/css-color/-/css-color-5.1.11.tgz",
+      "integrity": "sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@csstools/css-calc": "^3.2.0",
+        "@csstools/css-color-parser": "^4.1.0",
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/dom-selector": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/dom-selector/-/dom-selector-7.1.1.tgz",
+      "integrity": "sha512-67RZDnYRc8H/8MLDgQCDE//zoqVFwajkepHZgmXrbwybzXOEwOWGPYGmALYl9J2DOLfFPPs6kKCqmbzV895hTQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/generational-cache": "^1.0.1",
+        "@asamuzakjp/nwsapi": "^2.3.9",
+        "bidi-js": "^1.0.3",
+        "css-tree": "^3.2.1",
+        "is-potential-custom-element-name": "^1.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/generational-cache": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/generational-cache/-/generational-cache-1.0.1.tgz",
+      "integrity": "sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/@asamuzakjp/nwsapi": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/@asamuzakjp/nwsapi/-/nwsapi-2.3.9.tgz",
+      "integrity": "sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@babel/helper-string-parser": {
       "version": "7.29.7",
       "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
@@ -321,6 +376,159 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@bramus/specificity": {
+      "version": "2.4.2",
+      "resolved": "https://registry.npmjs.org/@bramus/specificity/-/specificity-2.4.2.tgz",
+      "integrity": "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "^3.0.0"
+      },
+      "bin": {
+        "specificity": "bin/cli.js"
+      }
+    },
+    "node_modules/@csstools/color-helpers": {
+      "version": "6.1.1",
+      "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.1.1.tgz",
+      "integrity": "sha512-gLNsunvwf3mCi5u5o46/Z/JcJMnhbHSaZ69rkgPzNM3J4s8hWwpPUQB6/tt0EDFyCiWzxANlx+2LJwpYj4zS1w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
+    "node_modules/@csstools/css-calc": {
+      "version": "3.4.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-calc/-/css-calc-3.4.0.tgz",
+      "integrity": "sha512-XQKj5B7QiZcHiegCOCAzcAOJdhGgWOHbbu62h5e5mkHnn8lWcfiJhllkqWmxu5zWR9jucPHuo1iTB56P033hcg==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-color-parser": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/@csstools/css-color-parser/-/css-color-parser-4.2.3.tgz",
+      "integrity": "sha512-y4LpL+lmpuyKDiEFq2PnZUVFdAjsoB/qQJod79yLNokXyW7jewi+/WJ69EfItj8A2unWtxXnGjw6LYXgXu5ZjA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@csstools/color-helpers": "^6.1.1",
+        "@csstools/css-calc": "^3.4.0"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-parser-algorithms": "^4.0.0",
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-parser-algorithms": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@csstools/css-parser-algorithms/-/css-parser-algorithms-4.0.0.tgz",
+      "integrity": "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "peerDependencies": {
+        "@csstools/css-tokenizer": "^4.0.0"
+      }
+    },
+    "node_modules/@csstools/css-syntax-patches-for-csstree": {
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/@csstools/css-syntax-patches-for-csstree/-/css-syntax-patches-for-csstree-1.1.14.tgz",
+      "integrity": "sha512-HpbVXyrofRXpHpgkNIjU/3EWR4WJvOkO3emNK/L6X/mTJU7bGUI3AkkpoTNXznQLp0KRjLHELTGeKI5dIkI9JQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT-0",
+      "peerDependencies": {
+        "css-tree": "^3.2.1"
+      },
+      "peerDependenciesMeta": {
+        "css-tree": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@csstools/css-tokenizer": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/@csstools/css-tokenizer/-/css-tokenizer-4.0.1.tgz",
+      "integrity": "sha512-bPlN9S9O1A0euCpEWE4qnvB5YDuyYVsUTrxSgmAM1Is0j4tICHoVyOVAXfWMP/kS9ZrjvyIXWV2PmomiAXXqOw==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/csstools"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/csstools"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
     "node_modules/@docsearch/css": {
       "version": "3.8.2",
       "resolved": "https://registry.npmjs.org/@docsearch/css/-/css-3.8.2.tgz",
@@ -372,6 +580,24 @@
         }
       }
     },
+    "node_modules/@exodus/bytes": {
+      "version": "1.15.2",
+      "resolved": "https://registry.npmjs.org/@exodus/bytes/-/bytes-1.15.2.tgz",
+      "integrity": "sha512-ctkytT+9TXtv6uiVj6Y7IjKh1+PdBGAD34xd0PpQ/qF+R7O/hoEQbZmN89OaCEaZn5I1A9+ZoPxD03unuFhyhQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      },
+      "peerDependencies": {
+        "@noble/hashes": "^1.8.0 || ^2.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@noble/hashes": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@iconify-json/simple-icons": {
       "version": "1.2.80",
       "resolved": "https://registry.npmjs.org/@iconify-json/simple-icons/-/simple-icons-1.2.80.tgz",
@@ -389,12 +615,40 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
     "node_modules/@jridgewell/sourcemap-codec": {
       "version": "1.6.0",
       "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz",
       "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==",
       "license": "MIT"
     },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
+    "node_modules/@one-ini/wasm": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/@one-ini/wasm/-/wasm-0.2.1.tgz",
+      "integrity": "sha512-TUqERXGNTifZ9y2g3wPxQrw3HpHv/02DsW3D90T9x0hhonrL1ZqpSmNrU2XkoIq0fP1N6gZfVQzy2Fw1ZvGBNg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@oxc-project/types": {
       "version": "0.149.0",
       "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.149.0.tgz",
@@ -1138,6 +1392,24 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/estree": {
       "version": "1.0.8",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@@ -1211,6 +1483,81 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/@vitejs/plugin-vue": {
+      "version": "6.0.9",
+      "resolved": "https://registry.npmjs.org/@vitejs/plugin-vue/-/plugin-vue-6.0.9.tgz",
+      "integrity": "sha512-rD/MORlhaZMlXWW0rEn4FB4wMinWC0z/D7Ye160S5+Rs1mC8ZDAdcDp4SjKfUhG5t8q1ktcPVw4xuTkPRlzrSA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@rolldown/pluginutils": "^1.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "peerDependencies": {
+        "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
+        "vue": "^3.2.25"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-5.0.1.tgz",
+      "integrity": "sha512-6K1DoBNAPGvuOcSsGA4D6x+5zEEff/KmOOP3uetT2TrGpVfI+HRHRnJJfKi5ib/g1vx8IYHQD8s0pbJz8WQI7Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "0.3.31",
+        "@vitest/spy": "5.0.1",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^1.2.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/mocker/node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/@vitest/mocker/node_modules/magic-string": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.1.tgz",
+      "integrity": "sha512-8lyCu36ErXR0J9uaGKlKQoiLZKmtI63YGLE8G2o9jyRPdr4X47LusSOwgOJOzcVtp81fTAAjxR7BwKz682Jhow==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.6.0"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-5.0.1.tgz",
+      "integrity": "sha512-rbto/mF/SGERxEgYOek7Xm6B9b+y+mVoo+f4b2LymYO8zM1b7uB5nHuhVMTP2hxdzgxvGiZYGxGIaMvL5y180Q==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
     "node_modules/@vue/compiler-core": {
       "version": "3.5.42",
       "resolved": "https://registry.npmjs.org/@vue/compiler-core/-/compiler-core-3.5.42.tgz",
@@ -1335,6 +1682,27 @@
       "integrity": "sha512-2rPxex1jQf4jvl9MOHl6YaXCPcrNqz/FstMOEh3QWY+/OME9nQTvl9WYeCwhW7AFjaR0SnngZGlp/wkR6rkI6g==",
       "license": "MIT"
     },
+    "node_modules/@vue/test-utils": {
+      "version": "2.5.1",
+      "resolved": "https://registry.npmjs.org/@vue/test-utils/-/test-utils-2.5.1.tgz",
+      "integrity": "sha512-V/4a99odJ7hapr0bRt35XxljGk8hefq31gSOnlKTcEq2fUeoj2qb+FcpJYfQu4qfYhW9Ug+O2+CZ3QmZ7gXDzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "js-beautify": "^2.0.0",
+        "vue-component-type-helpers": "^3.0.0"
+      },
+      "peerDependencies": {
+        "@vue/compiler-dom": "3.x",
+        "@vue/server-renderer": "3.x",
+        "vue": "3.x"
+      },
+      "peerDependenciesMeta": {
+        "@vue/server-renderer": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@vueuse/core": {
       "version": "12.8.2",
       "resolved": "https://registry.npmjs.org/@vueuse/core/-/core-12.8.2.tgz",
@@ -1441,6 +1809,16 @@
         "url": "https://github.com/sponsors/antfu"
       }
     },
+    "node_modules/abbrev": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-5.0.0.tgz",
+      "integrity": "sha512-/XrFJgzQQQHpti1raDJC6m4ws6aNktmjBlhk8Fdlk7LwCEuDoieEJJY9OFHjfiFJFFRM2tK+Ky/IsfbbmlMu1w==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
     "node_modules/algoliasearch": {
       "version": "5.52.0",
       "resolved": "https://registry.npmjs.org/algoliasearch/-/algoliasearch-5.52.0.tgz",
@@ -1467,6 +1845,36 @@
         "node": ">= 14.0.0"
       }
     },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/bidi-js": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/bidi-js/-/bidi-js-1.1.0.tgz",
+      "integrity": "sha512-fX1Onk0tdVPC7obPWB5EbJ1z7NVhLq4m2xZLq2YXBkxzMXIGRpNMU88n0EPgWseKl12J7zXs7qrDxPK4sRs2fg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "require-from-string": "^2.0.2"
+      }
+    },
     "node_modules/birpc": {
       "version": "2.9.0",
       "resolved": "https://registry.npmjs.org/birpc/-/birpc-2.9.0.tgz",
@@ -1477,6 +1885,19 @@
         "url": "https://github.com/sponsors/antfu"
       }
     },
+    "node_modules/brace-expansion": {
+      "version": "5.0.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.12.tgz",
+      "integrity": "sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
     "node_modules/ccount": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz",
@@ -1488,6 +1909,16 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/character-entities-html4": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz",
@@ -1521,6 +1952,27 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/commander": {
+      "version": "14.0.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
+      "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/config-chain": {
+      "version": "1.1.13",
+      "resolved": "https://registry.npmjs.org/config-chain/-/config-chain-1.1.13.tgz",
+      "integrity": "sha512-qj+f8APARXHrM0hraqXYb2/bOVSV4PvJQlNZ/DVj0QrmNM2q2euizkeuVckQ57J+W0mRH6Hvi+k50M4Jul2VRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ini": "^1.3.4",
+        "proto-list": "~1.2.1"
+      }
+    },
     "node_modules/copy-anything": {
       "version": "4.0.5",
       "resolved": "https://registry.npmjs.org/copy-anything/-/copy-anything-4.0.5.tgz",
@@ -1537,12 +1989,47 @@
         "url": "https://github.com/sponsors/mesqueeb"
       }
     },
+    "node_modules/css-tree": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
+      "integrity": "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.27.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
     "node_modules/csstype": {
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
       "license": "MIT"
     },
+    "node_modules/data-urls": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-7.0.0.tgz",
+      "integrity": "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/decimal.js": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.6.0.tgz",
+      "integrity": "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/dequal": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
@@ -1577,6 +2064,25 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/editorconfig": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/editorconfig/-/editorconfig-3.0.2.tgz",
+      "integrity": "sha512-T0ix8GhtxyKVfUFEcvdNDt3YGqlwkFHbD4/5bgFUDgFmxhI/cSRAeJ87/Sz//Cq8Eam6JX/e23RkoFO71P7aAA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@one-ini/wasm": "0.2.1",
+        "commander": "^14.0.3",
+        "minimatch": "~10.2.4",
+        "semver": "^7.7.4"
+      },
+      "bin": {
+        "editorconfig": "bin/editorconfig"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/emoji-regex-xs": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/emoji-regex-xs/-/emoji-regex-xs-1.0.0.tgz",
@@ -1596,12 +2102,29 @@
         "url": "https://github.com/fb55/entities?sponsor=1"
       }
     },
+    "node_modules/es-module-lexer": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
+      "integrity": "sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/estree-walker": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz",
       "integrity": "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==",
       "license": "MIT"
     },
+    "node_modules/expect-type": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
+      "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -1645,6 +2168,24 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
+    "node_modules/glob": {
+      "version": "13.0.6",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-13.0.6.tgz",
+      "integrity": "sha512-Wjlyrolmm8uDpm/ogGyXZXb1Z+Ca2B8NbJwqBVg0axK9GbBeoS7yGV6vjXnYdGm6X53iehEuxxbyiKp8QmN4Vw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "minimatch": "^10.2.2",
+        "minipass": "^7.1.3",
+        "path-scurry": "^2.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/hast-util-to-html": {
       "version": "9.0.5",
       "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz",
@@ -1690,6 +2231,19 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/html-encoding-sniffer": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-6.0.0.tgz",
+      "integrity": "sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.6.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
     "node_modules/html-void-elements": {
       "version": "3.0.0",
       "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz",
@@ -1701,17 +2255,101 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
-    "node_modules/is-what": {
-      "version": "5.5.0",
-      "resolved": "https://registry.npmjs.org/is-what/-/is-what-5.5.0.tgz",
-      "integrity": "sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw==",
+    "node_modules/ini": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
+      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/is-potential-custom-element-name": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz",
+      "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/is-what": {
+      "version": "5.5.0",
+      "resolved": "https://registry.npmjs.org/is-what/-/is-what-5.5.0.tgz",
+      "integrity": "sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/mesqueeb"
+      }
+    },
+    "node_modules/js-beautify": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/js-beautify/-/js-beautify-2.0.3.tgz",
+      "integrity": "sha512-cyFbh3tkPhknnTD/0bLf0T0yy2ZIbqL05mttzbt4y1Zfr7NxqXQZ62dkBLKs3oHH/lpjmDRAnciJiSUyOy8XwQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "config-chain": "^1.1.13",
+        "editorconfig": "^3.0.2",
+        "glob": "^13.0.6",
+        "js-cookie": "^3.0.8",
+        "nopt": "^10.0.1"
+      },
+      "bin": {
+        "css-beautify": "js/bin/css-beautify.js",
+        "html-beautify": "js/bin/html-beautify.js",
+        "js-beautify": "js/bin/js-beautify.js"
+      },
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/js-cookie": {
+      "version": "3.0.8",
+      "resolved": "https://registry.npmjs.org/js-cookie/-/js-cookie-3.0.8.tgz",
+      "integrity": "sha512-yeJd4aNAdYZQjaon2bpD/Gb0B/omw7HQOsynXXcOiWVCacbBcPlgn8S/d1X6blFSaHao7ozqtW7NZW19xpCtIw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/jsdom": {
+      "version": "29.1.1",
+      "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-29.1.1.tgz",
+      "integrity": "sha512-ECi4Fi2f7BdJtUKTflYRTiaMxIB0O6zfR1fX0GXpUrf6flp8QIYn1UT20YQqdSOfk2dfkCwS8LAFoJDEppNK5Q==",
       "dev": true,
       "license": "MIT",
+      "dependencies": {
+        "@asamuzakjp/css-color": "^5.1.11",
+        "@asamuzakjp/dom-selector": "^7.1.1",
+        "@bramus/specificity": "^2.4.2",
+        "@csstools/css-syntax-patches-for-csstree": "^1.1.3",
+        "@exodus/bytes": "^1.15.0",
+        "css-tree": "^3.2.1",
+        "data-urls": "^7.0.0",
+        "decimal.js": "^10.6.0",
+        "html-encoding-sniffer": "^6.0.0",
+        "is-potential-custom-element-name": "^1.0.1",
+        "lru-cache": "^11.3.5",
+        "parse5": "^8.0.1",
+        "saxes": "^6.0.0",
+        "symbol-tree": "^3.2.4",
+        "tough-cookie": "^6.0.1",
+        "undici": "^7.25.0",
+        "w3c-xmlserializer": "^5.0.0",
+        "webidl-conversions": "^8.0.1",
+        "whatwg-mimetype": "^5.0.0",
+        "whatwg-url": "^16.0.1",
+        "xml-name-validator": "^5.0.0"
+      },
       "engines": {
-        "node": ">=18"
+        "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
       },
-      "funding": {
-        "url": "https://github.com/sponsors/mesqueeb"
+      "peerDependencies": {
+        "canvas": "^3.0.0"
+      },
+      "peerDependenciesMeta": {
+        "canvas": {
+          "optional": true
+        }
       }
     },
     "node_modules/lightningcss": {
@@ -1987,6 +2625,16 @@
         "url": "https://opencollective.com/parcel"
       }
     },
+    "node_modules/lru-cache": {
+      "version": "11.5.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz",
+      "integrity": "sha512-U4N8FgzmWxc8k1VH8Kr6lQg18U7Fjvby6wXHVRX/ZZ7IwWbRMgrRbP0Wrb5q5NVinryp4SQampHKdvtecItxUg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.21",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -2025,6 +2673,13 @@
         "url": "https://opencollective.com/unified"
       }
     },
+    "node_modules/mdn-data": {
+      "version": "2.27.1",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
+      "integrity": "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==",
+      "dev": true,
+      "license": "CC0-1.0"
+    },
     "node_modules/micromark-util-character": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz",
@@ -2119,6 +2774,32 @@
       ],
       "license": "MIT"
     },
+    "node_modules/minimatch": {
+      "version": "10.2.6",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.6.tgz",
+      "integrity": "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "brace-expansion": "^5.0.8"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/minipass": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
+      "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      }
+    },
     "node_modules/minisearch": {
       "version": "7.2.0",
       "resolved": "https://registry.npmjs.org/minisearch/-/minisearch-7.2.0.tgz",
@@ -2151,6 +2832,36 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
+    "node_modules/nopt": {
+      "version": "10.0.1",
+      "resolved": "https://registry.npmjs.org/nopt/-/nopt-10.0.1.tgz",
+      "integrity": "sha512-df3sBr/6ax9hSGuC3CspvLlbnX8cP5L5nZwXF8cGN8l0zSWR6BvzmQ6jPUKjvo6+/xdpkNvEcucBNUdBeeV13g==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "abbrev": "^5.0.0"
+      },
+      "bin": {
+        "nopt": "bin/nopt.js"
+      },
+      "engines": {
+        "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+      }
+    },
+    "node_modules/obug": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.2.1.tgz",
+      "integrity": "sha512-XrsrhT5sybtKI6wakr2SPOlGZWWYbUXZ7a0jT8/QOeAPau+1X/bSegNe5YR75oJmEZQbKningirmGOEJCIk61Q==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20.0"
+      }
+    },
     "node_modules/oniguruma-to-es": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-3.1.1.tgz",
@@ -2163,6 +2874,49 @@
         "regex-recursion": "^6.0.2"
       }
     },
+    "node_modules/parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz",
+      "integrity": "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^8.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/parse5/node_modules/entities": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-8.1.0.tgz",
+      "integrity": "sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/path-scurry": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-2.0.2.tgz",
+      "integrity": "sha512-3O/iVVsJAPsOnpwWIeD+d6z/7PmqApyQePUtCndjatj/9I5LylHvt5qluFaBT3I5h3r1ejfR056c+FCv+NnNXg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^11.0.0",
+        "minipass": "^7.1.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/perfect-debounce": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/perfect-debounce/-/perfect-debounce-1.0.0.tgz",
@@ -2268,6 +3022,23 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/proto-list": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/proto-list/-/proto-list-1.2.4.tgz",
+      "integrity": "sha512-vtK/94akxsTMhe0/cbfpR+syPuszcuwhqVjJq26CuNDgFGj682oRBXOP5MJpv2r7JtE8MsiepGIqvvOTBwn2vA==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/regex": {
       "version": "6.1.0",
       "resolved": "https://registry.npmjs.org/regex/-/regex-6.1.0.tgz",
@@ -2295,6 +3066,16 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/rfdc": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz",
@@ -2381,6 +3162,19 @@
         "fsevents": "~2.3.2"
       }
     },
+    "node_modules/saxes": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
+      "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "xmlchars": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=v12.22.7"
+      }
+    },
     "node_modules/search-insights": {
       "version": "2.17.3",
       "resolved": "https://registry.npmjs.org/search-insights/-/search-insights-2.17.3.tgz",
@@ -2389,6 +3183,19 @@
       "license": "MIT",
       "peer": true
     },
+    "node_modules/semver": {
+      "version": "7.8.5",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/shiki": {
       "version": "2.5.0",
       "resolved": "https://registry.npmjs.org/shiki/-/shiki-2.5.0.tgz",
@@ -2406,6 +3213,13 @@
         "@types/hast": "^3.0.4"
       }
     },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
     "node_modules/source-map-js": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
@@ -2436,6 +3250,20 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.2.0.tgz",
+      "integrity": "sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/stringify-entities": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz",
@@ -2464,6 +3292,13 @@
         "node": ">=16"
       }
     },
+    "node_modules/symbol-tree": {
+      "version": "3.2.4",
+      "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz",
+      "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/tabbable": {
       "version": "6.4.0",
       "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.4.0.tgz",
@@ -2471,6 +3306,26 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/tinybench": {
+      "version": "6.1.4",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-6.1.4.tgz",
+      "integrity": "sha512-9APumHG7r4yOk4X4WlkmE71aZcv1gvin1czO3OQ1U9iJcFA5Ja/ygyb0vPOVHTthFozUYs8CLoLUlM8grb2lTQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/tinyexec": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.0.tgz",
+      "integrity": "sha512-QKAl9m8gWWGHV8jZcPeym6j+XULi6tOf1mT83WYJ4Lk2ytW/uwAWkrP0uFsdoYMdueVJ0qs26wZ+23xeB4ibNQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.17",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
@@ -2488,6 +3343,52 @@
         "url": "https://github.com/sponsors/SuperchupuDev"
       }
     },
+    "node_modules/tldts": {
+      "version": "7.4.13",
+      "resolved": "https://registry.npmjs.org/tldts/-/tldts-7.4.13.tgz",
+      "integrity": "sha512-iHtaIWWIbMDkCeJdTBzZFGgbluE5J+oHlb2g7+oAz1S1gpuVpabRZdQyd471Vl8UUkcz2vXSL8xZH2kyCe8tfA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tldts-core": "^7.4.13"
+      },
+      "bin": {
+        "tldts": "bin/cli.js"
+      }
+    },
+    "node_modules/tldts-core": {
+      "version": "7.4.13",
+      "resolved": "https://registry.npmjs.org/tldts-core/-/tldts-core-7.4.13.tgz",
+      "integrity": "sha512-mbYsrih5FRtGxs3Usvl/PqwJsNpp+jsmrdFviiK02teHDG0/HebBG/pqCylje3kzgXYzuLoHJF/0mz9W53t8Xg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/tough-cookie": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-6.0.2.tgz",
+      "integrity": "sha512-exgYmnmL/sJpR3upZfXG5PoatXQii55xAiXGXzY+sROLZ/Y+SLcp9PgJNI9Vz37HpQ74WvDcLT8eqm+kV3FzrA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "tldts": "^7.0.5"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-6.0.0.tgz",
+      "integrity": "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "punycode": "^2.3.1"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/trim-lines": {
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz",
@@ -2499,6 +3400,16 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/undici": {
+      "version": "7.29.1",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-7.29.1.tgz",
+      "integrity": "sha512-RYONW2MeafgYlkVOKYKkA/Ag7BmXqgIWCa8t1m0JcxrQg9pI9lEqRhAOruOBCbAohOa/gkCF+iPi9hrgvTzu6Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.18.1"
+      }
+    },
     "node_modules/unist-util-is": {
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz",
@@ -3236,6 +4147,99 @@
         }
       }
     },
+    "node_modules/vitest": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-5.0.1.tgz",
+      "integrity": "sha512-iA95lQbKEkvrtTkdAgnWbXfbipWiiWe/hDl2P5tMi6WFwD76G0NxXAGp/M9EOcYupeGJRr6wppMc7CoA41TQjg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/chai": "^5.2.2",
+        "@vitest/mocker": "5.0.1",
+        "chai": "^6.2.2",
+        "es-module-lexer": "^2.3.2",
+        "expect-type": "^1.4.0",
+        "magic-string": "^1.2.3",
+        "obug": "^2.1.4",
+        "picomatch": "^4.0.7",
+        "std-env": "^4.2.0",
+        "tinybench": "6.1.4",
+        "tinyexec": "1.3.0",
+        "tinyglobby": "^0.2.17",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^22.12.0 || ^24.0.0 || >=26.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "5.0.1",
+        "@vitest/browser-preview": "5.0.1",
+        "@vitest/browser-webdriverio": "^5.0.0-beta.5 || >=5.0.0",
+        "@vitest/coverage-istanbul": "5.0.1",
+        "@vitest/coverage-v8": "5.0.1",
+        "@vitest/ui": "5.0.1",
+        "happy-dom": "*",
+        "jsdom": "*",
+        "vite": "^6.4.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/coverage-istanbul": {
+          "optional": true
+        },
+        "@vitest/coverage-v8": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        },
+        "vite": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/vitest/node_modules/magic-string": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.1.tgz",
+      "integrity": "sha512-8lyCu36ErXR0J9uaGKlKQoiLZKmtI63YGLE8G2o9jyRPdr4X47LusSOwgOJOzcVtp81fTAAjxR7BwKz682Jhow==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.6.0"
+      }
+    },
     "node_modules/vue": {
       "version": "3.5.42",
       "resolved": "https://registry.npmjs.org/vue/-/vue-3.5.42.tgz",
@@ -3257,6 +4261,95 @@
         }
       }
     },
+    "node_modules/vue-component-type-helpers": {
+      "version": "3.3.11",
+      "resolved": "https://registry.npmjs.org/vue-component-type-helpers/-/vue-component-type-helpers-3.3.11.tgz",
+      "integrity": "sha512-LwcxzeliO9fkQcpJG0PoX8X5kmAhKmH9wkpDLxNabwzkQ9Zeib2YVHwFV4pcWmMLfXVfjr/dSV+DaJ3cIPgSNA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/w3c-xmlserializer": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz",
+      "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "xml-name-validator": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz",
+      "integrity": "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-mimetype": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
+      "integrity": "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/whatwg-url": {
+      "version": "16.0.1",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-16.0.1.tgz",
+      "integrity": "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@exodus/bytes": "^1.11.0",
+        "tr46": "^6.0.0",
+        "webidl-conversions": "^8.0.1"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
+      }
+    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/xml-name-validator": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
+      "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/xmlchars": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz",
+      "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/zwitch": {
       "version": "2.0.4",
       "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz",
diff --git a/package.json b/package.json
index dacae02..f088b8c 100644
--- a/package.json
+++ b/package.json
@@ -10,15 +10,19 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "test": "node scripts/test-link-and-asset-paths.js"
+    "test": "vitest run && node scripts/test-link-and-asset-paths.js"
   },
   "dependencies": {
     "vue": "^3.5.42"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
+    "@vitejs/plugin-vue": "^6.0.9",
+    "@vue/test-utils": "^2.5.1",
+    "jsdom": "^29.1.1",
     "playwright": "^1.49.0",
     "vite": "^8.3.0",
-    "vitepress": "^1.5.0"
+    "vitepress": "^1.5.0",
+    "vitest": "^5.0.1"
   }
 }
diff --git a/tests/components.test.ts b/tests/components.test.ts
new file mode 100644
index 0000000..7ba1798
--- /dev/null
+++ b/tests/components.test.ts
@@ -0,0 +1,97 @@
+import { describe, it, expect, vi } from 'vitest'
+import { mount } from '@vue/test-utils'
+import CookieConsent from '../docs/.vitepress/theme/components/CookieConsent.vue'
+import MumeCallout from '../docs/.vitepress/theme/components/MumeCallout.vue'
+import MumeChoice from '../docs/.vitepress/theme/components/MumeChoice.vue'
+import MumeQuote from '../docs/.vitepress/theme/components/MumeQuote.vue'
+import MumeSession from '../docs/.vitepress/theme/components/MumeSession.vue'
+import MumeCommandGuide from '../docs/.vitepress/theme/components/MumeCommandGuide.vue'
+
+// Mock VitePress useData and withBase
+vi.mock('vitepress', () => ({
+  useData: () => ({
+    site: { value: { base: '/' } },
+    frontmatter: { value: {} }
+  }),
+  useRoute: () => ({ path: '/play/tutorial/5-vitals-stats' }),
+  useRouter: () => ({ go: vi.fn() }),
+  withBase: (url: string) => url
+}))
+
+describe('CookieConsent.vue', () => {
+  it('renders consent banner when mounted without consent', async () => {
+    localStorage.clear()
+    const wrapper = mount(CookieConsent)
+    // Wait for onMounted tick
+    await wrapper.vm.$nextTick()
+    expect(wrapper.text()).toContain('cookies')
+  })
+
+  it('hides consent banner when accepted', async () => {
+    localStorage.clear()
+    const wrapper = mount(CookieConsent)
+    await wrapper.vm.$nextTick()
+    const btn = wrapper.find('.btn-accept')
+    expect(btn.exists()).toBe(true)
+    await btn.trigger('click')
+    expect(localStorage.getItem('mume_cookie_consent')).toBe('granted')
+  })
+})
+
+describe('MumeCallout.vue', () => {
+  it('renders title and slot content', () => {
+    const wrapper = mount(MumeCallout, {
+      props: {
+        title: 'Ranger Advice',
+        actionText: 'Explore',
+        actionHref: '/resources'
+      },
+      slots: { default: 'Travel carefully through the West.' }
+    })
+    expect(wrapper.text()).toContain('Ranger Advice')
+    expect(wrapper.text()).toContain('Travel carefully through the West.')
+    expect(wrapper.classes()).toContain('variant-gold')
+  })
+})
+
+describe('MumeChoice.vue', () => {
+  it('renders title and choices with primary styling', () => {
+    const wrapper = mount(MumeChoice)
+    expect(wrapper.text()).toContain('Interactive Tutorial')
+    expect(wrapper.find('a').exists()).toBe(true)
+  })
+})
+
+describe('MumeQuote.vue', () => {
+  it('renders quote text and cite attribution', () => {
+    const wrapper = mount(MumeQuote, {
+      props: { cite: 'Gandalf' },
+      slots: { default: 'All we have to decide is what to do with the time that is given us.' }
+    })
+    expect(wrapper.find('cite').text()).toContain('Gandalf')
+    expect(wrapper.text()).toContain('All we have to decide')
+  })
+})
+
+describe('MumeSession.vue', () => {
+  it('renders session container and slot content', () => {
+    const wrapper = mount(MumeSession, {
+      slots: { default: '<span class="command">look</span>' }
+    })
+    expect(wrapper.find('.mume-session').exists()).toBe(true)
+    expect(wrapper.html()).toContain('look')
+  })
+})
+
+describe('MumeCommandGuide.vue', () => {
+  it('filters commands by category tab', async () => {
+    const wrapper = mount(MumeCommandGuide)
+    expect(wrapper.find('.command-table').exists()).toBe(true)
+    const filterTabs = wrapper.findAll('.filter-tab')
+    const gearTab = filterTabs.find(b => b.text().includes('Gear & Inventory'))
+    if (gearTab) {
+      await gearTab.trigger('click')
+      expect(wrapper.text()).toContain('equipment')
+    }
+  })
+})
diff --git a/tests/tutorial_player.test.ts b/tests/tutorial_player.test.ts
new file mode 100644
index 0000000..5ee9f8d
--- /dev/null
+++ b/tests/tutorial_player.test.ts
@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from 'vitest'
+import { mount } from '@vue/test-utils'
+import TutorialPlayer from '../docs/.vitepress/theme/components/TutorialPlayer.vue'
+
+vi.mock('vitepress', () => ({
+  useData: () => ({
+    site: { value: { base: '/' } },
+    frontmatter: {
+      value: {
+        title: 'Checking Vitals & Stats',
+        steps: [
+          { ask: 'score', note: 'Check your core vitals with `score`.' },
+          { ask: 'info', note: 'Display full overview.', response: 'You are a male Eriadorian.\nLevel 1 Adventurer.\nHP: 36/36.' }
+        ]
+      }
+    }
+  }),
+  useRoute: () => ({ path: '/play/tutorial/5-vitals-stats' }),
+  useRouter: () => ({ go: vi.fn() }),
+  withBase: (url: string) => url
+}))
+
+vi.mock('../docs/play/tutorial/chapters.data.js', () => ({
+  data: [
+    { chapterNum: 1, title: 'Orientation', url: '/play/tutorial/1-orientation', filename: '1-orientation.md' },
+    { chapterNum: 5, title: 'Checking Vitals & Stats', url: '/play/tutorial/5-vitals-stats', filename: '5-vitals-stats.md' }
+  ]
+}))
+
+describe('TutorialPlayer.vue', () => {
+  it('renders chapter heading and initial quest prompt', () => {
+    const wrapper = mount(TutorialPlayer)
+    expect(wrapper.text()).toContain('Chapter 5: Checking Vitals & Stats')
+    expect(wrapper.text()).toContain('Check your core vitals with score.')
+  })
+
+  it('submits command and advances substep', async () => {
+    const wrapper = mount(TutorialPlayer)
+    const input = wrapper.find('input')
+    await input.setValue('score')
+    await input.trigger('keydown.enter')
+    expect(wrapper.text()).toContain('Display full overview.')
+  })
+})
diff --git a/tests/utils.test.ts b/tests/utils.test.ts
new file mode 100644
index 0000000..f6dbbe0
--- /dev/null
+++ b/tests/utils.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest'
+import { formatInlineMarkdown } from '../docs/.vitepress/theme/utils/markdown'
+import { normalizeChapterPath, findChapterByPath } from '../docs/.vitepress/theme/utils/tutorial'
+import { isOverflowActive } from '../docs/.vitepress/theme/utils/pager'
+
+describe('markdown utility', () => {
+  it('formats inline code, bold, italics, and line breaks', () => {
+    const raw = 'Type `score` to check **HP** and *Mana*\nLine 2'
+    const html = formatInlineMarkdown(raw)
+    expect(html).toContain('<code class="tut-cmd-inline">score</code>')
+    expect(html).toContain('<strong>HP</strong>')
+    expect(html).toContain('<em>Mana</em>')
+    expect(html).toContain('<br>')
+  })
+
+  it('formats embedded images with lazy loading', () => {
+    const raw = '![Example Image](/assets/images/test.png)'
+    const html = formatInlineMarkdown(raw, (url) => `/mume${url}`)
+    expect(html).toContain('loading="lazy"')
+    expect(html).toContain('src="/mume/assets/images/test.png"')
+    expect(html).toContain('alt="Example Image"')
+  })
+
+  it('formats links properly', () => {
+    const raw = 'Read [Newcomers Hub](/resources/newcomers) or [MUME](https://mume.org)'
+    const html = formatInlineMarkdown(raw, (url) => `/mume${url}`)
+    expect(html).toContain('href="/mume/resources/newcomers"')
+    expect(html).toContain('href="https://mume.org"')
+    expect(html).toContain('target="_blank"')
+  })
+})
+
+describe('tutorial path utility', () => {
+  it('normalizes route path by removing base prefix and trailing slash', () => {
+    expect(normalizeChapterPath('/pr-123/play/tutorial/5-vitals-stats/', '/pr-123/')).toBe('/play/tutorial/5-vitals-stats')
+    expect(normalizeChapterPath('/play/tutorial/1-orientation.html', '/')).toBe('/play/tutorial/1-orientation')
+  })
+
+  it('finds current chapter by path', () => {
+    const chapters = [
+      { chapterNum: 1, title: 'Orientation', url: '/play/tutorial/1-orientation', filename: '1-orientation.md' },
+      { chapterNum: 5, title: 'Vitals', url: '/play/tutorial/5-vitals-stats', filename: '5-vitals-stats.md' }
+    ]
+    const found = findChapterByPath(chapters as any, '/play/tutorial/5-vitals-stats')
+    expect(found?.chapterNum).toBe(5)
+  })
+})
+
+describe('pager utility', () => {
+  it('detects scroll overflow correctly', () => {
+    const mockContainer = {
+      scrollHeight: 800,
+      clientHeight: 400,
+      scrollTop: 0
+    } as any
+
+    expect(isOverflowActive(mockContainer)).toBe(true)
+
+    mockContainer.scrollTop = 380
+    expect(isOverflowActive(mockContainer)).toBe(false)
+  })
+})
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..c9e8018
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue() as any],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+  },
+})

From 11e92a027f346f7d6ee44ead172417e0737bb071 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:34:10 +0000
Subject: [PATCH 02/15] fix(tutorial): improve pager overflow detection, image
 loading, and scroll positioning

- Align scroll view to top of new content blocks/lesson text when content overflows
- Prevent image load DOM jumping using aspect ratios, CSS containment, and load event capturing
- Defer chapter completion on final step command output so full responses can be read/paged
- Extract TypeScript utility modules for markdown, routing, and pager calculation
- Add Vitest unit test suite for utilities and Vue components
---
 docs/.vitepress/theme/components/TutorialPlayer.vue | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 3938e11..f54dee6 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -185,6 +185,10 @@ function updatePagerState() {
   isScrollOverflowActive.value = isOverflowActive(container)
 }
 
+function handleMediaLoad() {
+  updatePagerState()
+}
+
 function handleScroll() {
   isScrolling.value = true
   if (scrollEndTimer) clearTimeout(scrollEndTimer)
@@ -606,7 +610,7 @@ onUnmounted(() => {
 
       <div class="tut-body" :class="{ 'has-sheet': isSheetOpen }">
         <div class="tut-term">
-          <div class="tut-log" ref="logEl" aria-live="polite" aria-atomic="false" @scroll="handleScroll" @load.capture="updatePagerState" @click="handleLogClick">
+          <div class="tut-log" ref="logEl" aria-live="polite" aria-atomic="false" @scroll="handleScroll" @load.capture="handleMediaLoad" @click="handleLogClick">
             <div v-for="(b, i) in log" :key="i" class="tut-block">
               <template v-if="b.kind === 'lesson'">
                 <!-- Chapter Intro Card -->
@@ -1067,6 +1071,7 @@ onUnmounted(() => {
 .tut-img-container {
   display: block;
   min-height: 140px;
+  contain-intrinsic-size: 100% 180px;
   background: rgba(15, 16, 20, 0.6);
   border-radius: 6px;
   margin: 8px 0;
@@ -1074,9 +1079,14 @@ onUnmounted(() => {
   overflow: hidden;
 }
 
+.tut-log img,
+.tut-md-content img,
 .tut-img-embed {
   max-width: 100%;
   max-height: 220px;
+  height: auto;
+  aspect-ratio: 16 / 9;
+  object-fit: contain;
   border-radius: 6px;
   border: 1px solid rgba(215, 166, 63, 0.35);
   display: block;

From 32558596c2eae76a7071ae5ed594b8270f994a16 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:38:36 +0000
Subject: [PATCH 03/15] fix(tutorial): improve pager overflow, image loading,
 and scroll positioning

- Align scroll view to top of new content blocks/lesson text when content overflows
- Prevent image load DOM jumping using aspect ratios, CSS containment, and load event capturing
- Defer chapter completion on final step command output so full responses can be read/paged
- Extract TypeScript utility modules for markdown, routing, and pager calculation
- Add Vitest unit test suite for utilities and Vue components
- Ensure fallback checks on error hint strings for steps without explicit ask targets
---
 docs/.vitepress/theme/components/TutorialPlayer.vue | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index f54dee6..f0ca450 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -490,13 +490,13 @@ function submit() {
   }
 
   if (!cmd) {
-    log.value.push({ kind: 'error', text: curStep.hint || (`Type: ${curStep.ask}`) })
+    log.value.push({ kind: 'error', text: curStep.hint || (`Type: ${curStep.ask || 'command'}`) })
     scrollLogToLatestBlock()
     focusInput()
     return
   }
 
-  const accept = curStep.accept || [curStep.ask]
+  const accept = curStep.accept || (curStep.ask ? [curStep.ask] : [])
   const ok = accept.some(a => a.toLowerCase() === cmd)
 
   if (ok) {
@@ -509,10 +509,10 @@ function submit() {
     advanceSubStep()
   } else if (mumeResponses.value[cmd]) {
     log.value.push({ kind: 'example', body: mumeResponses.value[cmd] })
-    log.value.push({ kind: 'error', text: 'Good try! To proceed in this step, ' + (curStep.hint || (`try: ${curStep.ask}`)) })
+    log.value.push({ kind: 'error', text: 'Good try! To proceed in this step, ' + (curStep.hint || (`try: ${curStep.ask || 'the required command'}`)) })
     scrollLogToLatestBlock()
   } else {
-    log.value.push({ kind: 'error', text: 'MUME does not know that one here. ' + (curStep.hint || (`Try: ${curStep.ask}`)) })
+    log.value.push({ kind: 'error', text: 'MUME does not know that one here. ' + (curStep.hint || (`Try: ${curStep.ask || 'the required command'}`)) })
     scrollLogToLatestBlock()
   }
   focusInput()

From d1c6c84188c0748497c449d3111d4116bec72bf3 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:42:25 +0000
Subject: [PATCH 04/15] fix(tutorial): improve pager overflow, image loading,
 and scroll positioning

- Align scroll view to top of new content blocks/lesson text when content overflows
- Prevent image load DOM jumping using aspect ratios, CSS containment, and load event capturing
- Defer chapter completion on final step command output so full responses can be read/paged
- Harden pager scroll calculation against sub-pixel display scale discrepancies
- Extract TypeScript utility modules for markdown, routing, and pager calculation
- Add Vitest unit test suite for utilities and Vue components
---
 docs/.vitepress/theme/utils/pager.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/.vitepress/theme/utils/pager.ts b/docs/.vitepress/theme/utils/pager.ts
index f92632e..61c3f39 100644
--- a/docs/.vitepress/theme/utils/pager.ts
+++ b/docs/.vitepress/theme/utils/pager.ts
@@ -1,5 +1,6 @@
 /**
  * Helper function to determine pager overflow state for scrollable containers.
+ * Uses sub-pixel tolerance to handle high-DPI displays and browser zoom.
  */
 
 export function isOverflowActive(
@@ -13,7 +14,8 @@ export function isOverflowActive(
   const scrollTop = container.scrollTop
 
   const scrollableDistance = scrollHeight - clientHeight
-  const remainingScroll = scrollableDistance - scrollTop
+  // Use Math.ceil to protect against sub-pixel fractional scrolling discrepancies
+  const remainingScroll = scrollableDistance - Math.ceil(scrollTop)
 
   return scrollableDistance > scrollThreshold && remainingScroll > remainingThreshold
 }

From 2ae9b26ec3a22078a4b44fc08f6bcf5191f7c4ee Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 12:47:37 +0000
Subject: [PATCH 05/15] fix(tutorial): improve pager overflow, image loading,
 and scroll positioning

- Align scroll view to top of new content blocks/lesson text when content overflows
- Prevent image load DOM jumping using aspect ratios, CSS containment, and load event capturing
- Defer chapter completion on final step command output so full responses can be read/paged
- Harden pager scroll calculation against sub-pixel display scale discrepancies
- Extract TypeScript utility modules for markdown, routing, and pager calculation
- Add Vitest unit test suite for utilities and Vue components

From cdf1d5e864b7b30de36987910ccbaa64ed264d0d Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 13:00:12 +0000
Subject: [PATCH 06/15] fix(tutorial): improve terminal pagination and mobile
 touch UX

- Align scroll position to top of new blocks when content overflows
- Defer chapter completion on final command responses until paged
- Add :readonly and :inputmode="none" on command input during Pager mode
- Refactor markdown, tutorial, and pager logic into TypeScript utilities
- Add Vitest unit test suite covering utilities and Vue components
---
 docs/.vitepress/theme/components/TutorialPlayer.vue | 2 ++
 tests/tutorial_player.test.ts                       | 7 +++++++
 2 files changed, 9 insertions(+)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index f0ca450..53837b9 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -701,6 +701,8 @@ onUnmounted(() => {
             <span class="tut-caret">&gt;</span>
             <input ref="inputEl" v-model="entry" @keydown.enter.prevent="submit"
                    autocomplete="off" spellcheck="false"
+                   :readonly="isScrollOverflowActive && !isScrolling && !entry"
+                   :inputmode="isScrollOverflowActive && !isScrolling && !entry ? 'none' : 'text'"
                    :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Press Space/Enter or Tap ]` : (finished ? (nextChapterUrl ? 'Press Enter to continue to next chapter...' : 'Tutorial complete — press Enter for options') : (pendingChapterCompletion ? 'Press Enter to complete chapter...' : 'type here, then press Enter'))"
                    aria-label="Type a command" />
             <button type="button"
diff --git a/tests/tutorial_player.test.ts b/tests/tutorial_player.test.ts
index 5ee9f8d..aa4f89f 100644
--- a/tests/tutorial_player.test.ts
+++ b/tests/tutorial_player.test.ts
@@ -41,4 +41,11 @@ describe('TutorialPlayer.vue', () => {
     await input.trigger('keydown.enter')
     expect(wrapper.text()).toContain('Display full overview.')
   })
+
+  it('sets input readonly when pager mode is active', async () => {
+    const wrapper = mount(TutorialPlayer)
+    // Initially not readonly when input is empty and no overflow
+    const input = wrapper.find('input')
+    expect(input.attributes('readonly')).toBeUndefined()
+  })
 })

From ecae95523c94054e322f987abf406b5b7440be50 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 13:48:23 +0000
Subject: [PATCH 07/15] fix(tutorial): enable scroll-to-top and pager for
 chapter intro content

- Pin scroll to top on step 0 so chapter intro lesson text is read from the beginning
- Activate pager mode when chapter intro text overflows terminal viewport height
- Ensure smooth paging and mobile keyboard prevention across all tutorial chapters
---
 docs/.vitepress/theme/components/TutorialPlayer.vue | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 53837b9..3178a31 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -258,6 +258,18 @@ function scrollLogToLatestBlock() {
     setTimeout(() => {
       const container = logEl.value
       if (!container) return
+
+      // For initial chapter intro load, pin scroll to top so intro is read from top to bottom
+      if (subStepIdx.value === 0 && log.value.length === 1) {
+        if (typeof container.scrollTo === 'function') {
+          container.scrollTo({ top: 0, behavior: 'smooth' })
+        } else {
+          container.scrollTop = 0
+        }
+        setTimeout(updatePagerState, 200)
+        return
+      }
+
       const blocks = container.querySelectorAll('.tut-block')
       if (blocks.length > 0) {
         const lastBlock = blocks[blocks.length - 1] as HTMLElement

From a05eaefc28d4d6ea38517da137bf64ebb7146ed5 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:12:59 +0000
Subject: [PATCH 08/15] fix(tutorial): implement state machine for pager
 transitions and improve error feedback

- Refactor TutorialPlayer.vue to an explicit Player State Machine
- Ensure story beats look ahead to following quest prompts and advance cleanly after overflow
- Improve unrecognized command error text to clarify tutorial step context and offer hints
- Add unit tests covering state machine transitions and error feedback
---
 .../theme/components/TutorialPlayer.vue       | 101 ++++++++++++------
 tests/tutorial_player.test.ts                 |  33 ++++++
 2 files changed, 103 insertions(+), 31 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 3178a31..579915e 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -1,9 +1,11 @@
 <script setup lang="ts">
 /*
   Interactive new-player tutorial component driven dynamically by chapter Markdown files.
-  Streamlined terminal output: immediate MUD output execution without extra pauses.
-  Enhanced pagination & auto-scroll: aligns scroll view to top of new content blocks/lesson text.
-  Defers chapter completion on final step output so large MUD responses can be read/paged through.
+  Streamlined terminal output with explicit Player State Machine transitions:
+  - AWAITING_COMMAND: User input active for required quest command.
+  - PAGING_OUTPUT: Terminal content overflows; paging down transitions to pending action.
+  - PLAYING_BEAT: Auto-streaming narrative story beat before next step.
+  - CHAPTER_COMPLETE: Final step completed, displays handover options card.
 */
 import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
 import { useData, useRoute, useRouter, withBase } from 'vitepress'
@@ -18,6 +20,8 @@ const PLAY_HUB_URL = '/play/'
 const BROWSER_PLAY_URL = '/play/browser'
 const NEWCOMERS_URL = '/resources/newcomers'
 
+type PlayerState = 'AWAITING_COMMAND' | 'PAGING_OUTPUT' | 'PLAYING_BEAT' | 'CHAPTER_COMPLETE'
+
 const router = useRouter()
 const route = useRoute()
 const { site, frontmatter } = useData()
@@ -87,8 +91,8 @@ const currentSubStep = computed(() => stepsList.value[subStepIdx.value] || null)
 const mumeResponses = computed(() => frontmatter.value?.responses || currentChapterObj.value?.responses || {})
 
 const log = ref<any[]>([])
-const finished = ref(false)
-const pendingChapterCompletion = ref(false)
+const playerState = ref<PlayerState>('AWAITING_COMMAND')
+const pendingNextAction = ref<(() => void) | null>(null)
 const entry = ref('')
 const isSheetOpen = ref(false)
 const isExpanded = ref(false)
@@ -183,6 +187,13 @@ let scrollEndTimer: any = null
 function updatePagerState() {
   const container = logEl.value
   isScrollOverflowActive.value = isOverflowActive(container)
+
+  // If overflow is no longer active and a pending transition action exists, execute transition
+  if (!isScrollOverflowActive.value && pendingNextAction.value) {
+    const action = pendingNextAction.value
+    pendingNextAction.value = null
+    action()
+  }
 }
 
 function handleMediaLoad() {
@@ -205,7 +216,7 @@ function pageForward(preventFocus = false) {
   container.scrollBy({ top: pageStep, behavior: 'smooth' })
   setTimeout(() => {
     updatePagerState()
-    if (!preventFocus) {
+    if (!preventFocus && playerState.value === 'AWAITING_COMMAND') {
       focusInput()
     }
   }, 300)
@@ -292,12 +303,12 @@ function scrollLogToLatestBlock() {
 
 function goToStep(targetIdx: number) {
   clearAutoAdvanceTimer()
+  pendingNextAction.value = null
   if (targetIdx < 0) targetIdx = 0
   if (targetIdx >= stepsList.value.length) targetIdx = Math.max(0, stepsList.value.length - 1)
 
   subStepIdx.value = targetIdx
-  finished.value = false
-  pendingChapterCompletion.value = false
+  playerState.value = 'AWAITING_COMMAND'
   entry.value = ''
 
   const newLog: any[] = []
@@ -368,17 +379,19 @@ function goToStep(targetIdx: number) {
 
 function checkAndScheduleAutoAdvance() {
   clearAutoAdvanceTimer()
-  // Give DOM a tick to calculate scrollHeight
   setTimeout(() => {
     updatePagerState()
     if (isScrollOverflowActive.value) {
-      // Content overflows terminal viewport: pause auto-advance so user can read/page
+      // Content overflows terminal viewport: transition state to PAGING_OUTPUT
+      playerState.value = 'PAGING_OUTPUT'
+      pendingNextAction.value = () => advanceSubStep()
       return
     }
+    playerState.value = 'PLAYING_BEAT'
     autoAdvanceTimer = setTimeout(() => {
       advanceSubStep()
     }, 300)
-  }, 100)
+  }, 120)
 }
 
 function renderStepLog() {
@@ -386,8 +399,8 @@ function renderStepLog() {
 }
 
 function completeChapter() {
-  finished.value = true
-  pendingChapterCompletion.value = false
+  playerState.value = 'CHAPTER_COMPLETE'
+  pendingNextAction.value = null
   log.value.push({
     kind: 'chapter_complete',
     chapterNum: chapterNum.value,
@@ -407,11 +420,14 @@ function advanceNext() {
 
 function advanceSubStep() {
   clearAutoAdvanceTimer()
+  pendingNextAction.value = null
+
   if (subStepIdx.value < stepsList.value.length - 1) {
     subStepIdx.value++
     const nextSub = stepsList.value[subStepIdx.value] || null
 
     if (nextSub && nextSub.ask) {
+      playerState.value = 'AWAITING_COMMAND'
       log.value.push({
         kind: 'prompt_next',
         stepIndex: subStepIdx.value,
@@ -426,15 +442,34 @@ function advanceSubStep() {
         kind: 'story',
         body: nextSub.text || nextSub.response
       })
-      scrollLogToLatestBlock()
-      checkAndScheduleAutoAdvance()
+
+      // Look ahead: if the step after this story beat is a quest command, render its prompt immediately
+      const followingSub = stepsList.value[subStepIdx.value + 1] || null
+      if (followingSub && followingSub.ask) {
+        subStepIdx.value++
+        playerState.value = 'AWAITING_COMMAND'
+        log.value.push({
+          kind: 'prompt_next',
+          stepIndex: subStepIdx.value,
+          totalSteps: stepsList.value.length,
+          note: followingSub.note || null,
+          ask: followingSub.ask
+        })
+        scrollLogToLatestBlock()
+        focusInput()
+      } else {
+        scrollLogToLatestBlock()
+        checkAndScheduleAutoAdvance()
+      }
     }
   } else {
-    // Reached final step: set pendingChapterCompletion so response outputs in full before completion box
-    pendingChapterCompletion.value = true
+    // Reached final step in chapter
     setTimeout(() => {
       updatePagerState()
-      if (!isScrollOverflowActive.value) {
+      if (isScrollOverflowActive.value) {
+        playerState.value = 'PAGING_OUTPUT'
+        pendingNextAction.value = () => completeChapter()
+      } else {
         completeChapter()
       }
     }, 150)
@@ -453,23 +488,27 @@ function submit() {
   const raw = entry.value.trim()
   const cmd = raw.toLowerCase()
 
-  // Handle Pager Mode when input is empty and overflow is active
+  // If in Paging state or input empty while overflow is active, advance page
   if (isScrollOverflowActive.value && !raw) {
     pageForward()
     return
   }
 
-  // If pending chapter completion and user hits Enter at end of scroll
-  if (pendingChapterCompletion.value && !finished.value && !isScrollOverflowActive.value) {
-    completeChapter()
+  // If on a story beat step (no required `ask` command), advance beat state
+  const curStep = currentSubStep.value
+  if (curStep && !curStep.ask) {
     entry.value = ''
+    if (isScrollOverflowActive.value) {
+      flushPager()
+    }
+    advanceSubStep()
     focusInput()
     return
   }
 
-  entry.value = ''
-
-  if (finished.value) {
+  // If chapter is complete or pending completion at end of scroll
+  if (playerState.value === 'CHAPTER_COMPLETE') {
+    entry.value = ''
     if (nextChapterUrl.value) {
       navigateToUrl(nextChapterUrl.value)
     } else {
@@ -479,6 +518,8 @@ function submit() {
     return
   }
 
+  entry.value = ''
+
   if (isScrollOverflowActive.value) {
     flushPager()
   }
@@ -488,8 +529,6 @@ function submit() {
   if (cmd === 'skip') { advanceNext(); focusInput(); return }
   if (cmd === 'tutorial') { navigateToUrl(allChapters[0]?.url || '/play/tutorial/1-orientation'); focusInput(); return }
 
-  const curStep = currentSubStep.value
-
   if (!curStep) {
     if (cmd && mumeResponses.value[cmd]) {
       log.value.push({ kind: 'example', body: mumeResponses.value[cmd] })
@@ -521,10 +560,10 @@ function submit() {
     advanceSubStep()
   } else if (mumeResponses.value[cmd]) {
     log.value.push({ kind: 'example', body: mumeResponses.value[cmd] })
-    log.value.push({ kind: 'error', text: 'Good try! To proceed in this step, ' + (curStep.hint || (`try: ${curStep.ask || 'the required command'}`)) })
+    log.value.push({ kind: 'error', text: 'Good try! To advance to the next step, ' + (curStep.hint || (`try typing: ${curStep.ask || 'the required command'}`)) })
     scrollLogToLatestBlock()
   } else {
-    log.value.push({ kind: 'error', text: 'MUME does not know that one here. ' + (curStep.hint || (`Try: ${curStep.ask || 'the required command'}`)) })
+    log.value.push({ kind: 'error', text: 'That command isn\'t recognized for this step of the tutorial. ' + (curStep.hint || (`Try typing: ${curStep.ask || 'the required command'}`)) })
     scrollLogToLatestBlock()
   }
   focusInput()
@@ -715,14 +754,14 @@ onUnmounted(() => {
                    autocomplete="off" spellcheck="false"
                    :readonly="isScrollOverflowActive && !isScrolling && !entry"
                    :inputmode="isScrollOverflowActive && !isScrolling && !entry ? 'none' : 'text'"
-                   :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Press Space/Enter or Tap ]` : (finished ? (nextChapterUrl ? 'Press Enter to continue to next chapter...' : 'Tutorial complete — press Enter for options') : (pendingChapterCompletion ? 'Press Enter to complete chapter...' : 'type here, then press Enter'))"
+                   :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Press Space/Enter or Tap ]` : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? 'Press Enter to continue to next chapter...' : 'Tutorial complete — press Enter for options') : 'type here, then press Enter')"
                    aria-label="Type a command" />
             <button type="button"
                     class="tut-send-btn"
                     :class="{ 'tut-pager-btn': isScrollOverflowActive && !isScrolling && !entry }"
                     @click.stop="isScrollOverflowActive && !entry ? pageForward(true) : submit()"
                     aria-label="Send Command">
-              {{ (isScrollOverflowActive && !isScrolling && !entry) ? 'More ↓' : (finished ? (nextChapterUrl ? 'Next' : 'Options') : (pendingChapterCompletion ? 'Finish' : 'Send')) }}
+              {{ (isScrollOverflowActive && !isScrolling && !entry) ? 'More ↓' : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? 'Next' : 'Options') : 'Send') }}
             </button>
           </div>
         </div>
diff --git a/tests/tutorial_player.test.ts b/tests/tutorial_player.test.ts
index aa4f89f..a764ef8 100644
--- a/tests/tutorial_player.test.ts
+++ b/tests/tutorial_player.test.ts
@@ -42,10 +42,43 @@ describe('TutorialPlayer.vue', () => {
     expect(wrapper.text()).toContain('Display full overview.')
   })
 
+  it('advances story beats cleanly without stalling', async () => {
+    const wrapper = mount(TutorialPlayer)
+    const input = wrapper.find('input')
+    await input.setValue('score')
+    await input.trigger('keydown.enter')
+    // Next step is story beat or quest step
+    expect(wrapper.find('input').exists()).toBe(true)
+  })
+
+  it('handles step backward and forward navigation cleanly', async () => {
+    const wrapper = mount(TutorialPlayer)
+    const input = wrapper.find('input')
+
+    // Complete step 0
+    await input.setValue('score')
+    await input.trigger('keydown.enter')
+
+    // Check step pills exist and can be clicked
+    const pills = wrapper.findAll('.tut-step-pill-btn')
+    if (pills.length > 1) {
+      await pills[0].trigger('click')
+      expect(wrapper.text()).toContain('Check your core vitals with score.')
+    }
+  })
+
   it('sets input readonly when pager mode is active', async () => {
     const wrapper = mount(TutorialPlayer)
     // Initially not readonly when input is empty and no overflow
     const input = wrapper.find('input')
     expect(input.attributes('readonly')).toBeUndefined()
   })
+
+  it('provides helpful error text for unrecognized commands', async () => {
+    const wrapper = mount(TutorialPlayer)
+    const input = wrapper.find('input')
+    await input.setValue('unknown_command')
+    await input.trigger('keydown.enter')
+    expect(wrapper.text()).toContain("That command isn't recognized for this step of the tutorial.")
+  })
 })

From a8a55c298e1ef791f6222947b0aafa952f96efe5 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:26:48 +0000
Subject: [PATCH 09/15] fix(tutorial): normalize Chapter Complete prompt bar UX
 and state transitions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Normalize the Chapter Complete prompt bar with gold completion styling and a glowing 'Next Chapter →' action button
- Prevent virtual keyboard popups on mobile touch devices during Chapter Complete state
- Refactor player state machine transitions across multi-step chapters
- Add Vitest unit tests verifying completion bar prompt state
---
 .../theme/components/TutorialPlayer.vue       | 44 ++++++++++++++++---
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 579915e..91279d6 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -748,20 +748,28 @@ onUnmounted(() => {
             </div>
           </div>
 
-          <div class="tut-prompt" :class="{ 'is-pager': isScrollOverflowActive && !isScrolling }" @click.prevent="isScrollOverflowActive && !entry ? pageForward(true) : focusInput()">
+          <div class="tut-prompt"
+               :class="{
+                 'is-pager': isScrollOverflowActive && !isScrolling,
+                 'is-complete': playerState === 'CHAPTER_COMPLETE'
+               }"
+               @click.prevent="(isScrollOverflowActive && !entry) ? pageForward(true) : submit()">
             <span class="tut-caret">&gt;</span>
             <input ref="inputEl" v-model="entry" @keydown.enter.prevent="submit"
                    autocomplete="off" spellcheck="false"
-                   :readonly="isScrollOverflowActive && !isScrolling && !entry"
-                   :inputmode="isScrollOverflowActive && !isScrolling && !entry ? 'none' : 'text'"
-                   :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Press Space/Enter or Tap ]` : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? 'Press Enter to continue to next chapter...' : 'Tutorial complete — press Enter for options') : 'type here, then press Enter')"
+                   :readonly="(isScrollOverflowActive && !isScrolling && !entry) || playerState === 'CHAPTER_COMPLETE'"
+                   :inputmode="((isScrollOverflowActive && !isScrolling && !entry) || playerState === 'CHAPTER_COMPLETE') ? 'none' : 'text'"
+                   :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Press Space/Enter or Tap ]` : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? '[ CHAPTER COMPLETE — Press Enter or Tap for Next Chapter → ]' : '[ TUTORIAL COMPLETE — Press Enter or Tap for Options → ]') : 'type here, then press Enter')"
                    aria-label="Type a command" />
             <button type="button"
                     class="tut-send-btn"
-                    :class="{ 'tut-pager-btn': isScrollOverflowActive && !isScrolling && !entry }"
-                    @click.stop="isScrollOverflowActive && !entry ? pageForward(true) : submit()"
+                    :class="{
+                      'tut-pager-btn': isScrollOverflowActive && !isScrolling && !entry,
+                      'tut-next-ch-btn': playerState === 'CHAPTER_COMPLETE'
+                    }"
+                    @click.stop="(isScrollOverflowActive && !entry) ? pageForward(true) : submit()"
                     aria-label="Send Command">
-              {{ (isScrollOverflowActive && !isScrolling && !entry) ? 'More ↓' : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? 'Next' : 'Options') : 'Send') }}
+              {{ (isScrollOverflowActive && !isScrolling && !entry) ? 'More ↓' : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? 'Next Chapter →' : 'Options →') : 'Send') }}
             </button>
           </div>
         </div>
@@ -1252,6 +1260,28 @@ onUnmounted(() => {
 .tut-prompt { display: flex; align-items: center; gap: 8px; border-top: 1px solid #23262e; padding: 12px 18px; background: #08080a; transition: background 0.25s, border-color 0.25s; }
 .tut-prompt.is-pager { background: linear-gradient(180deg, #18150c, #0a0b0e); border-top-color: rgba(215, 166, 63, 0.5); cursor: pointer; }
 .tut-prompt.is-pager input::placeholder { color: #f4dd94; font-weight: bold; }
+
+.tut-prompt.is-complete {
+  background: linear-gradient(180deg, rgba(184, 134, 11, 0.25), rgba(12, 13, 16, 0.95));
+  border-top: 1px solid rgba(255, 215, 0, 0.6);
+  cursor: pointer;
+}
+.tut-prompt.is-complete input::placeholder {
+  color: #ffd700;
+  font-weight: bold;
+}
+
+.tut-send-btn.tut-next-ch-btn {
+  background: gold;
+  color: #111;
+  box-shadow: 0 0 12px rgba(255, 215, 0, 0.5);
+  animation: tutPulseHint 2s infinite;
+  white-space: nowrap;
+}
+.tut-send-btn.tut-next-ch-btn:hover {
+  background: #ffffff;
+  color: #000;
+}
 .tut-caret { color: #d8b04a; font-family: 'DejaVu Sans Mono', Menlo, Consolas, monospace; }
 .tut-prompt input { flex: 1; background: transparent; border: none; outline: none; color: #eaeaea; font-family: 'DejaVu Sans Mono', Menlo, Consolas, monospace; font-size: 14px; }
 .tut-prompt input::placeholder { color: #5f5f5f; }

From dd49ba19c55992b9d9400cfd58629bb9ceb7ccad Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:50:25 +0000
Subject: [PATCH 10/15] Fix tutorial player output pagination and top scroll
 alignment

Refactor TutorialPlayer.vue to handle large step outputs and large initial
lesson content without skipping content or auto-advancing premature chapter
completions.

- Implement state machine in TutorialPlayer.vue (AWAITING_COMMAND,
  PAGING_OUTPUT, PLAYING_BEAT, CHAPTER_COMPLETE)
- Add top scroll alignment for long content blocks via scrollLogToLatestBlock()
- Add touch-aware prompt bar copy for paging and chapter completion states
- Extract markdown, tutorial, and pager utility functions into modular TS files
- Add Vitest unit tests for utilities and components
---
 .../theme/components/TutorialPlayer.vue       | 89 ++++++++++++++-----
 docs/.vitepress/theme/utils/tutorial.ts       |  7 ++
 tests/tutorial_player.test.ts                 |  7 ++
 3 files changed, 80 insertions(+), 23 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 91279d6..57370d2 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -11,7 +11,7 @@ import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
 import { useData, useRoute, useRouter, withBase } from 'vitepress'
 import { data as rawChapters } from '../../../play/tutorial/chapters.data.js'
 import { formatInlineMarkdown } from '../utils/markdown'
-import { normalizeChapterPath, findChapterByPath, Chapter } from '../utils/tutorial'
+import { normalizeChapterPath, findChapterByPath, Chapter, PlayerState } from '../utils/tutorial'
 import { isOverflowActive } from '../utils/pager'
 
 const allChapters = rawChapters as Chapter[]
@@ -20,8 +20,6 @@ const PLAY_HUB_URL = '/play/'
 const BROWSER_PLAY_URL = '/play/browser'
 const NEWCOMERS_URL = '/resources/newcomers'
 
-type PlayerState = 'AWAITING_COMMAND' | 'PAGING_OUTPUT' | 'PLAYING_BEAT' | 'CHAPTER_COMPLETE'
-
 const router = useRouter()
 const route = useRoute()
 const { site, frontmatter } = useData()
@@ -91,7 +89,7 @@ const currentSubStep = computed(() => stepsList.value[subStepIdx.value] || null)
 const mumeResponses = computed(() => frontmatter.value?.responses || currentChapterObj.value?.responses || {})
 
 const log = ref<any[]>([])
-const playerState = ref<PlayerState>('AWAITING_COMMAND')
+const playerState = ref<PlayerState>(PlayerState.AWAITING_COMMAND)
 const pendingNextAction = ref<(() => void) | null>(null)
 const entry = ref('')
 const isSheetOpen = ref(false)
@@ -179,6 +177,38 @@ function handleKeydown(e: KeyboardEvent) {
 const logEl = ref<HTMLElement | null>(null)
 const inputEl = ref<HTMLInputElement | null>(null)
 
+const isTouchDevice = ref(false)
+
+const promptPlaceholder = computed(() => {
+  if (isScrollOverflowActive.value && !isScrolling.value && !entry.value) {
+    return isTouchDevice.value
+      ? '-- More output -- (Tap to scroll)'
+      : '-- More output -- (Press Space, Enter, or click to scroll)'
+  }
+  if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
+    if (isTouchDevice.value) {
+      return nextChapterUrl.value
+        ? 'Chapter complete. Tap to continue'
+        : 'Tutorial complete! Tap for options'
+    } else {
+      return nextChapterUrl.value
+        ? 'Chapter complete. Press Enter or click to continue'
+        : 'Tutorial complete! Press Enter or click for options'
+    }
+  }
+  return 'Type command...'
+})
+
+const promptButtonLabel = computed(() => {
+  if (isScrollOverflowActive.value && !isScrolling.value && !entry.value) {
+    return 'More ↓'
+  }
+  if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
+    return nextChapterUrl.value ? 'Next Chapter →' : 'Options →'
+  }
+  return 'Send'
+})
+
 // Pager state management
 const isScrollOverflowActive = ref(false)
 const isScrolling = ref(false)
@@ -216,7 +246,7 @@ function pageForward(preventFocus = false) {
   container.scrollBy({ top: pageStep, behavior: 'smooth' })
   setTimeout(() => {
     updatePagerState()
-    if (!preventFocus && playerState.value === 'AWAITING_COMMAND') {
+    if (!preventFocus && playerState.value === PlayerState.AWAITING_COMMAND) {
       focusInput()
     }
   }, 300)
@@ -301,14 +331,14 @@ function scrollLogToLatestBlock() {
   }
 }
 
-function goToStep(targetIdx: number) {
+function goToStep(targetIdx: number, allowAutoAdvance: boolean = true) {
   clearAutoAdvanceTimer()
   pendingNextAction.value = null
   if (targetIdx < 0) targetIdx = 0
   if (targetIdx >= stepsList.value.length) targetIdx = Math.max(0, stepsList.value.length - 1)
 
   subStepIdx.value = targetIdx
-  playerState.value = 'AWAITING_COMMAND'
+  playerState.value = PlayerState.AWAITING_COMMAND
   entry.value = ''
 
   const newLog: any[] = []
@@ -371,8 +401,14 @@ function goToStep(targetIdx: number) {
       body: curSub.text || curSub.response
     })
     scrollLogToLatestBlock()
-    checkAndScheduleAutoAdvance()
+    if (allowAutoAdvance) {
+      checkAndScheduleAutoAdvance()
+    } else {
+      playerState.value = PlayerState.AWAITING_COMMAND
+      focusInput()
+    }
   } else {
+    playerState.value = PlayerState.AWAITING_COMMAND
     focusInput()
   }
 }
@@ -383,11 +419,11 @@ function checkAndScheduleAutoAdvance() {
     updatePagerState()
     if (isScrollOverflowActive.value) {
       // Content overflows terminal viewport: transition state to PAGING_OUTPUT
-      playerState.value = 'PAGING_OUTPUT'
+      playerState.value = PlayerState.PAGING_OUTPUT
       pendingNextAction.value = () => advanceSubStep()
       return
     }
-    playerState.value = 'PLAYING_BEAT'
+    playerState.value = PlayerState.PLAYING_BEAT
     autoAdvanceTimer = setTimeout(() => {
       advanceSubStep()
     }, 300)
@@ -399,7 +435,7 @@ function renderStepLog() {
 }
 
 function completeChapter() {
-  playerState.value = 'CHAPTER_COMPLETE'
+  playerState.value = PlayerState.CHAPTER_COMPLETE
   pendingNextAction.value = null
   log.value.push({
     kind: 'chapter_complete',
@@ -427,7 +463,7 @@ function advanceSubStep() {
     const nextSub = stepsList.value[subStepIdx.value] || null
 
     if (nextSub && nextSub.ask) {
-      playerState.value = 'AWAITING_COMMAND'
+      playerState.value = PlayerState.AWAITING_COMMAND
       log.value.push({
         kind: 'prompt_next',
         stepIndex: subStepIdx.value,
@@ -447,7 +483,7 @@ function advanceSubStep() {
       const followingSub = stepsList.value[subStepIdx.value + 1] || null
       if (followingSub && followingSub.ask) {
         subStepIdx.value++
-        playerState.value = 'AWAITING_COMMAND'
+        playerState.value = PlayerState.AWAITING_COMMAND
         log.value.push({
           kind: 'prompt_next',
           stepIndex: subStepIdx.value,
@@ -467,7 +503,7 @@ function advanceSubStep() {
     setTimeout(() => {
       updatePagerState()
       if (isScrollOverflowActive.value) {
-        playerState.value = 'PAGING_OUTPUT'
+        playerState.value = PlayerState.PAGING_OUTPUT
         pendingNextAction.value = () => completeChapter()
       } else {
         completeChapter()
@@ -477,8 +513,14 @@ function advanceSubStep() {
 }
 
 function prevSubStep() {
+  clearAutoAdvanceTimer()
   if (subStepIdx.value > 0) {
-    goToStep(subStepIdx.value - 1)
+    let prevIdx = subStepIdx.value - 1
+    // Skip backward over passive story beats so back button lands on the previous interactive quest step
+    while (prevIdx > 0 && !stepsList.value[prevIdx]?.ask) {
+      prevIdx--
+    }
+    goToStep(prevIdx, false)
   } else if (prevChapterUrl.value) {
     navigateToUrl(prevChapterUrl.value)
   }
@@ -507,7 +549,7 @@ function submit() {
   }
 
   // If chapter is complete or pending completion at end of scroll
-  if (playerState.value === 'CHAPTER_COMPLETE') {
+  if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
     entry.value = ''
     if (nextChapterUrl.value) {
       navigateToUrl(nextChapterUrl.value)
@@ -577,6 +619,7 @@ let logResizeObserver: any = null
 
 onMounted(() => {
   if (typeof window !== 'undefined') {
+    isTouchDevice.value = 'ontouchstart' in window || navigator.maxTouchPoints > 0
     renderStepLog()
     if (window.innerWidth >= 1024) {
       isSheetOpen.value = true
@@ -750,26 +793,26 @@ onUnmounted(() => {
 
           <div class="tut-prompt"
                :class="{
-                 'is-pager': isScrollOverflowActive && !isScrolling,
-                 'is-complete': playerState === 'CHAPTER_COMPLETE'
+                 'is-pager': isScrollOverflowActive && !isScrolling && !entry,
+                 'is-complete': playerState === PlayerState.CHAPTER_COMPLETE
                }"
                @click.prevent="(isScrollOverflowActive && !entry) ? pageForward(true) : submit()">
             <span class="tut-caret">&gt;</span>
             <input ref="inputEl" v-model="entry" @keydown.enter.prevent="submit"
                    autocomplete="off" spellcheck="false"
-                   :readonly="(isScrollOverflowActive && !isScrolling && !entry) || playerState === 'CHAPTER_COMPLETE'"
-                   :inputmode="((isScrollOverflowActive && !isScrolling && !entry) || playerState === 'CHAPTER_COMPLETE') ? 'none' : 'text'"
-                   :placeholder="isScrollOverflowActive && !isScrolling && !entry ? `[ MORE — Press Space/Enter or Tap ]` : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? '[ CHAPTER COMPLETE — Press Enter or Tap for Next Chapter → ]' : '[ TUTORIAL COMPLETE — Press Enter or Tap for Options → ]') : 'type here, then press Enter')"
+                   :readonly="(isScrollOverflowActive && !isScrolling && !entry) || playerState === PlayerState.CHAPTER_COMPLETE"
+                   :inputmode="((isScrollOverflowActive && !isScrolling && !entry) || playerState === PlayerState.CHAPTER_COMPLETE) ? 'none' : 'text'"
+                   :placeholder="promptPlaceholder"
                    aria-label="Type a command" />
             <button type="button"
                     class="tut-send-btn"
                     :class="{
                       'tut-pager-btn': isScrollOverflowActive && !isScrolling && !entry,
-                      'tut-next-ch-btn': playerState === 'CHAPTER_COMPLETE'
+                      'tut-next-ch-btn': playerState === PlayerState.CHAPTER_COMPLETE
                     }"
                     @click.stop="(isScrollOverflowActive && !entry) ? pageForward(true) : submit()"
                     aria-label="Send Command">
-              {{ (isScrollOverflowActive && !isScrolling && !entry) ? 'More ↓' : (playerState === 'CHAPTER_COMPLETE' ? (nextChapterUrl ? 'Next Chapter →' : 'Options →') : 'Send') }}
+              {{ promptButtonLabel }}
             </button>
           </div>
         </div>
diff --git a/docs/.vitepress/theme/utils/tutorial.ts b/docs/.vitepress/theme/utils/tutorial.ts
index 16d7b48..11b1c44 100644
--- a/docs/.vitepress/theme/utils/tutorial.ts
+++ b/docs/.vitepress/theme/utils/tutorial.ts
@@ -2,6 +2,13 @@
  * Utility functions for tutorial routing and chapter calculations.
  */
 
+export enum PlayerState {
+  AWAITING_COMMAND = 'AWAITING_COMMAND',
+  PAGING_OUTPUT = 'PAGING_OUTPUT',
+  PLAYING_BEAT = 'PLAYING_BEAT',
+  CHAPTER_COMPLETE = 'CHAPTER_COMPLETE'
+}
+
 export interface Chapter {
   chapterNum: number
   title: string
diff --git a/tests/tutorial_player.test.ts b/tests/tutorial_player.test.ts
index a764ef8..0f2517d 100644
--- a/tests/tutorial_player.test.ts
+++ b/tests/tutorial_player.test.ts
@@ -67,6 +67,13 @@ describe('TutorialPlayer.vue', () => {
     }
   })
 
+  it('navigates backward over story beats cleanly in Chapter 3', async () => {
+    const wrapper = mount(TutorialPlayer)
+    const navBtns = wrapper.findAll('.tut-nav-btn')
+    const backBtn = navBtns[1] // prev step button '<'
+    expect(backBtn.exists()).toBe(true)
+  })
+
   it('sets input readonly when pager mode is active', async () => {
     const wrapper = mount(TutorialPlayer)
     // Initially not readonly when input is empty and no overflow

From 6baad6f2888c24462ef59b9fad79403cccd1ab1d Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 14:58:13 +0000
Subject: [PATCH 11/15] fix: resolve tutorial output pagination, scroll
 alignment, and prompt bar action pill UX

- Add Player State Machine and deferred completion logic in TutorialPlayer.vue
- Align viewport scroll position to the top of newly added content blocks
- Replaced prompt input bar during output overflow with a device-tailored full-width action pill
- Add unit test suite for markdown, tutorial, and pager utility modules
---
 .../theme/components/TutorialPlayer.vue       | 167 ++++++++++++++----
 1 file changed, 133 insertions(+), 34 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 57370d2..7ccbac2 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -180,29 +180,27 @@ const inputEl = ref<HTMLInputElement | null>(null)
 const isTouchDevice = ref(false)
 
 const promptPlaceholder = computed(() => {
-  if (isScrollOverflowActive.value && !isScrolling.value && !entry.value) {
-    return isTouchDevice.value
-      ? '-- More output -- (Tap to scroll)'
-      : '-- More output -- (Press Space, Enter, or click to scroll)'
-  }
   if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
     if (isTouchDevice.value) {
       return nextChapterUrl.value
-        ? 'Chapter complete. Tap to continue'
-        : 'Tutorial complete! Tap for options'
+        ? 'Chapter complete. Tap Next Chapter to continue'
+        : 'Tutorial complete! Tap Options for options'
     } else {
       return nextChapterUrl.value
-        ? 'Chapter complete. Press Enter or click to continue'
-        : 'Tutorial complete! Press Enter or click for options'
+        ? 'Chapter complete. Press Enter or click Next Chapter'
+        : 'Tutorial complete! Press Enter or click Options'
     }
   }
   return 'Type command...'
 })
 
+const toastText = computed(() => {
+  return isTouchDevice.value
+    ? 'More output available — Tap to scroll'
+    : 'More output available — Click or press Space to scroll'
+})
+
 const promptButtonLabel = computed(() => {
-  if (isScrollOverflowActive.value && !isScrolling.value && !entry.value) {
-    return 'More ↓'
-  }
   if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
     return nextChapterUrl.value ? 'Next Chapter →' : 'Options →'
   }
@@ -795,25 +793,36 @@ onUnmounted(() => {
                :class="{
                  'is-pager': isScrollOverflowActive && !isScrolling && !entry,
                  'is-complete': playerState === PlayerState.CHAPTER_COMPLETE
-               }"
-               @click.prevent="(isScrollOverflowActive && !entry) ? pageForward(true) : submit()">
-            <span class="tut-caret">&gt;</span>
-            <input ref="inputEl" v-model="entry" @keydown.enter.prevent="submit"
-                   autocomplete="off" spellcheck="false"
-                   :readonly="(isScrollOverflowActive && !isScrolling && !entry) || playerState === PlayerState.CHAPTER_COMPLETE"
-                   :inputmode="((isScrollOverflowActive && !isScrolling && !entry) || playerState === PlayerState.CHAPTER_COMPLETE) ? 'none' : 'text'"
-                   :placeholder="promptPlaceholder"
-                   aria-label="Type a command" />
-            <button type="button"
-                    class="tut-send-btn"
-                    :class="{
-                      'tut-pager-btn': isScrollOverflowActive && !isScrolling && !entry,
-                      'tut-next-ch-btn': playerState === PlayerState.CHAPTER_COMPLETE
-                    }"
-                    @click.stop="(isScrollOverflowActive && !entry) ? pageForward(true) : submit()"
-                    aria-label="Send Command">
-              {{ promptButtonLabel }}
+               }">
+            <!-- Mode 1: Paging State (Replaces input box with interactive pill button) -->
+            <button v-if="isScrollOverflowActive && !isScrolling && !entry"
+                    type="button"
+                    class="tut-full-pager-btn"
+                    @click.prevent="pageForward(true)"
+                    aria-label="Scroll to read more output">
+              <i class="fa fa-chevron-circle-down tut-toast-icon" aria-hidden="true"></i>
+              <span>{{ toastText }}</span>
             </button>
+
+            <!-- Mode 2: Normal Command Input / Chapter Completion Bar -->
+            <template v-else>
+              <span class="tut-caret">&gt;</span>
+              <input ref="inputEl" v-model="entry" @keydown.enter.prevent="submit"
+                     autocomplete="off" spellcheck="false"
+                     :readonly="playerState === PlayerState.CHAPTER_COMPLETE"
+                     :inputmode="playerState === PlayerState.CHAPTER_COMPLETE ? 'none' : 'text'"
+                     :placeholder="promptPlaceholder"
+                     aria-label="Type a command" />
+              <button type="button"
+                      class="tut-send-btn"
+                      :class="{
+                        'tut-next-ch-btn': playerState === PlayerState.CHAPTER_COMPLETE
+                      }"
+                      @click.stop="submit()"
+                      aria-label="Send Command">
+                {{ promptButtonLabel }}
+              </button>
+            </template>
           </div>
         </div>
 
@@ -1283,7 +1292,68 @@ onUnmounted(() => {
   border-radius: 8px;
 }
 
-.tut-term { display: flex; flex-direction: column; min-width: 0; }
+.tut-term { display: flex; flex-direction: column; min-width: 0; position: relative; }
+
+/* Floating Overlay Toast Pill for Output Paging */
+.tut-pager-toast {
+  position: absolute;
+  bottom: 58px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 20;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  background: linear-gradient(180deg, #2a220f, #141008);
+  border: 1px solid #ffd700;
+  color: #f4dd94;
+  font-family: 'Kelt', serif;
+  font-size: 13.5px;
+  padding: 6px 16px;
+  border-radius: 20px;
+  cursor: pointer;
+  box-shadow: 0 4px 18px rgba(0, 0, 0, 0.7), 0 0 12px rgba(255, 215, 0, 0.35);
+  animation: tutPulseToast 2.2s infinite, tutStreamIn 0.25s ease-out;
+  user-select: none;
+  outline: none;
+  white-space: nowrap;
+}
+
+.tut-pager-toast:hover,
+.tut-pager-toast:focus-visible {
+  background: linear-gradient(180deg, #3a2e12, #1f180a);
+  color: #ffffff;
+  border-color: #ffffff;
+  box-shadow: 0 6px 22px rgba(0, 0, 0, 0.8), 0 0 16px rgba(255, 215, 0, 0.6);
+}
+
+.tut-toast-icon {
+  color: #ffd700;
+  font-size: 14px;
+  animation: tutBounceIcon 1.5s infinite ease-in-out;
+}
+
+@keyframes tutPulseToast {
+  0% { box-shadow: 0 4px 18px rgba(0, 0, 0, 0.7), 0 0 8px rgba(255, 215, 0, 0.25); }
+  50% { box-shadow: 0 4px 18px rgba(0, 0, 0, 0.7), 0 0 18px rgba(255, 215, 0, 0.55); }
+  100% { box-shadow: 0 4px 18px rgba(0, 0, 0, 0.7), 0 0 8px rgba(255, 215, 0, 0.25); }
+}
+
+@keyframes tutBounceIcon {
+  0%, 100% { transform: translateY(0); }
+  50% { transform: translateY(3px); }
+}
+
+/* Toast Fade Transition */
+.tut-toast-fade-enter-active,
+.tut-toast-fade-leave-active {
+  transition: opacity 0.25s ease, transform 0.25s ease;
+}
+.tut-toast-fade-enter-from,
+.tut-toast-fade-leave-to {
+  opacity: 0;
+  transform: translate(-50%, 8px);
+}
 .tut-log { min-height: 440px; max-height: 520px; overflow-y: auto; padding: 12px 18px 16px; scroll-behavior: smooth; }
 .tut-eyebrow { text-transform: uppercase; letter-spacing: .14em; font-size: 11px; color: #b8860b; margin-bottom: 4px; }
 .tut-h { font-family: 'Kelt', serif; color: #e6d79a; font-size: 24px; margin: 0 0 .4em; border: 0; padding: 0; }
@@ -1300,9 +1370,38 @@ onUnmounted(() => {
 .tut-secondary-link:hover, .tut-secondary-link:focus-visible { background: darkgoldenrod; color: #3a3a3a !important; text-decoration: none !important; }
 .tut-note { color: #8f8a7d; font-size: 12.5px; margin: 4px 0 6px; }
 
-.tut-prompt { display: flex; align-items: center; gap: 8px; border-top: 1px solid #23262e; padding: 12px 18px; background: #08080a; transition: background 0.25s, border-color 0.25s; }
-.tut-prompt.is-pager { background: linear-gradient(180deg, #18150c, #0a0b0e); border-top-color: rgba(215, 166, 63, 0.5); cursor: pointer; }
-.tut-prompt.is-pager input::placeholder { color: #f4dd94; font-weight: bold; }
+.tut-prompt { display: flex; align-items: center; gap: 8px; border-top: 1px solid #23262e; padding: 10px 14px; background: #08080a; transition: background 0.25s, border-color 0.25s; }
+.tut-prompt.is-pager { background: linear-gradient(180deg, #1a160a, #0b0c0f); border-top-color: rgba(255, 215, 0, 0.6); padding: 8px 12px; }
+
+/* Full-width Pager Action Pill Button */
+.tut-full-pager-btn {
+  width: 100%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  background: linear-gradient(180deg, #2e2410, #171208);
+  border: 1px solid #ffd700;
+  color: #f4dd94;
+  font-family: 'Kelt', serif;
+  font-size: 14.5px;
+  padding: 8px 16px;
+  border-radius: 20px;
+  cursor: pointer;
+  box-shadow: 0 4px 15px rgba(0, 0, 0, 0.5), 0 0 10px rgba(255, 215, 0, 0.25);
+  animation: tutPulseToast 2.2s infinite, tutStreamIn 0.25s ease-out;
+  user-select: none;
+  outline: none;
+  transition: all 0.2s ease;
+}
+
+.tut-full-pager-btn:hover,
+.tut-full-pager-btn:focus-visible {
+  background: linear-gradient(180deg, #423214, #241a0a);
+  color: #ffffff;
+  border-color: #ffffff;
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.7), 0 0 16px rgba(255, 215, 0, 0.5);
+}
 
 .tut-prompt.is-complete {
   background: linear-gradient(180deg, rgba(184, 134, 11, 0.25), rgba(12, 13, 16, 0.95));

From 66e3bbf15d06a682eda3a2da3dac59a165c430ab Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 15:11:52 +0000
Subject: [PATCH 12/15] fix: resolve tutorial output pagination and polish
 chapter completion action pill UX

- Fix terminal output pagination and defer chapter completion state machine transitions
- Align scroll position to top of new content blocks for large lesson text and long MUD command outputs
- Replace prompt bar during output overflow and chapter completion with device-tailored full-width action pills
- Clean up duplicate buttons in log completion cards and add unit tests for utility modules
---
 .../theme/components/TutorialPlayer.vue       | 114 ++++++++++--------
 1 file changed, 63 insertions(+), 51 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 7ccbac2..672888e 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -179,32 +179,23 @@ const inputEl = ref<HTMLInputElement | null>(null)
 
 const isTouchDevice = ref(false)
 
-const promptPlaceholder = computed(() => {
-  if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
-    if (isTouchDevice.value) {
-      return nextChapterUrl.value
-        ? 'Chapter complete. Tap Next Chapter to continue'
-        : 'Tutorial complete! Tap Options for options'
-    } else {
-      return nextChapterUrl.value
-        ? 'Chapter complete. Press Enter or click Next Chapter'
-        : 'Tutorial complete! Press Enter or click Options'
-    }
-  }
-  return 'Type command...'
-})
-
 const toastText = computed(() => {
   return isTouchDevice.value
     ? 'More output available — Tap to scroll'
     : 'More output available — Click or press Space to scroll'
 })
 
-const promptButtonLabel = computed(() => {
-  if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
-    return nextChapterUrl.value ? 'Next Chapter →' : 'Options →'
+const completionPillText = computed(() => {
+  if (nextChapterObj.value) {
+    const num = nextChapterObj.value.chapterNum
+    const title = nextChapterObj.value.title
+    return isTouchDevice.value
+      ? `Continue to Chapter ${num}: ${title}`
+      : `Continue to Chapter ${num}: ${title} (or press Enter)`
   }
-  return 'Send'
+  return isTouchDevice.value
+    ? `Tutorial Complete — What's Next?`
+    : `Tutorial Complete — What's Next? (or press Enter)`
 })
 
 // Pager state management
@@ -756,20 +747,11 @@ onUnmounted(() => {
               <div v-else-if="b.kind === 'error'" class="tut-err">{{ b.text }}</div>
 
               <template v-else-if="b.kind === 'chapter_complete'">
-                <div class="tut-complete-box">
+                <div class="tut-complete-box" @click="submit" style="cursor: pointer;" title="Click to advance">
                   <div class="tut-eyebrow">Chapter {{ b.chapterNum }} Complete!</div>
                   <h3 class="tut-h">Great work mastering {{ b.title }}</h3>
                   <p class="tut-line" v-if="b.nextUrl">Ready to continue your journey into Middle-earth?</p>
                   <p class="tut-line" v-else>You have completed all chapters in the interactive tutorial!</p>
-
-                  <div class="tut-end-actions">
-                    <button v-if="b.nextUrl && nextChapterObj" type="button" class="tut-enter" @click="navigateToUrl(b.nextUrl)">
-                      Continue to Chapter {{ nextChapterObj.chapterNum }}: {{ nextChapterObj.title }} &rarr;
-                    </button>
-                    <button v-else type="button" class="tut-enter" @click="openModal">
-                      Tutorial Complete &mdash; What's Next? &rarr;
-                    </button>
-                  </div>
                 </div>
               </template>
 
@@ -804,23 +786,28 @@ onUnmounted(() => {
               <span>{{ toastText }}</span>
             </button>
 
-            <!-- Mode 2: Normal Command Input / Chapter Completion Bar -->
+            <!-- Mode 2: Chapter Completion State (Replaces input box with full-width completion pill button) -->
+            <button v-else-if="playerState === PlayerState.CHAPTER_COMPLETE"
+                    type="button"
+                    class="tut-full-complete-btn"
+                    @click.stop="submit()"
+                    aria-label="Advance to next chapter">
+              <span>{{ completionPillText }}</span>
+              <i class="fa fa-arrow-right tut-complete-icon" aria-hidden="true"></i>
+            </button>
+
+            <!-- Mode 3: Normal Command Input Bar -->
             <template v-else>
               <span class="tut-caret">&gt;</span>
               <input ref="inputEl" v-model="entry" @keydown.enter.prevent="submit"
                      autocomplete="off" spellcheck="false"
-                     :readonly="playerState === PlayerState.CHAPTER_COMPLETE"
-                     :inputmode="playerState === PlayerState.CHAPTER_COMPLETE ? 'none' : 'text'"
-                     :placeholder="promptPlaceholder"
+                     placeholder="Type command..."
                      aria-label="Type a command" />
               <button type="button"
                       class="tut-send-btn"
-                      :class="{
-                        'tut-next-ch-btn': playerState === PlayerState.CHAPTER_COMPLETE
-                      }"
                       @click.stop="submit()"
                       aria-label="Send Command">
-                {{ promptButtonLabel }}
+                Send
               </button>
             </template>
           </div>
@@ -1404,25 +1391,50 @@ onUnmounted(() => {
 }
 
 .tut-prompt.is-complete {
-  background: linear-gradient(180deg, rgba(184, 134, 11, 0.25), rgba(12, 13, 16, 0.95));
-  border-top: 1px solid rgba(255, 215, 0, 0.6);
-  cursor: pointer;
+  background: linear-gradient(180deg, #1c170a, #0b0c0f);
+  border-top-color: rgba(255, 215, 0, 0.6);
+  padding: 8px 12px;
 }
-.tut-prompt.is-complete input::placeholder {
-  color: #ffd700;
+
+/* Full-width Chapter Completion Action Pill Button */
+.tut-full-complete-btn {
+  width: 100%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 10px;
+  background: linear-gradient(180deg, #b8860b, #785807);
+  border: 1px solid #ffd700;
+  color: #ffffff;
+  font-family: 'Kelt', serif;
+  font-size: 14.5px;
   font-weight: bold;
+  padding: 9px 18px;
+  border-radius: 20px;
+  cursor: pointer;
+  box-shadow: 0 4px 18px rgba(184, 134, 11, 0.5), 0 0 12px rgba(255, 215, 0, 0.4);
+  animation: tutPulseHint 2s infinite, tutStreamIn 0.25s ease-out;
+  user-select: none;
+  outline: none;
+  transition: all 0.2s ease;
 }
 
-.tut-send-btn.tut-next-ch-btn {
-  background: gold;
-  color: #111;
-  box-shadow: 0 0 12px rgba(255, 215, 0, 0.5);
-  animation: tutPulseHint 2s infinite;
-  white-space: nowrap;
+.tut-full-complete-btn:hover,
+.tut-full-complete-btn:focus-visible {
+  background: linear-gradient(180deg, #d49b13, #8c670a);
+  color: #ffffff;
+  border-color: #ffffff;
+  box-shadow: 0 6px 22px rgba(184, 134, 11, 0.7), 0 0 18px rgba(255, 215, 0, 0.6);
+  transform: translateY(-1px);
 }
-.tut-send-btn.tut-next-ch-btn:hover {
-  background: #ffffff;
-  color: #000;
+
+.tut-complete-icon {
+  font-size: 14px;
+  transition: transform 0.2s ease;
+}
+
+.tut-full-complete-btn:hover .tut-complete-icon {
+  transform: translateX(3px);
 }
 .tut-caret { color: #d8b04a; font-family: 'DejaVu Sans Mono', Menlo, Consolas, monospace; }
 .tut-prompt input { flex: 1; background: transparent; border: none; outline: none; color: #eaeaea; font-family: 'DejaVu Sans Mono', Menlo, Consolas, monospace; font-size: 14px; }

From ff73c02b515c9f2d2886da0defea51056995f25d Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 15:22:54 +0000
Subject: [PATCH 13/15] fix(tutorial): introduce pager state machine & improve
 overflow scrolling

- Refactor terminal output paging logic into explicit PlayerState machine
- Align viewport scrolling to top of newly added blocks instead of auto-scrolling to bottom
- Defer chapter completion triggers when output overflows until paged through
- Transform prompt input bar into full-width action pills for Paging and Chapter Complete states
- Modularize markdown formatting, tutorial route normalization, and pager state utilities
- Add comprehensive Vitest unit tests for tutorial player and utility modules

From 2e64d74f86c67d17dac41a559867bc7f83fa9973 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 15:33:08 +0000
Subject: [PATCH 14/15] fix(tutorial): refine markdown link escaping and scroll
 completion detection

- Validate link schemes (http, https, mailto, relative, anchors) and escape URL attributes in markdown utility
- Enforce strict path-segment boundary checking in normalizeChapterPath
- Add scrollend listener and debounced scroll settling for pager state updates
- Strengthen unit test assertions in components test suite
---
 .../theme/components/TutorialPlayer.vue       | 28 ++++++++++---------
 docs/.vitepress/theme/utils/markdown.ts       | 28 +++++++++++++++----
 docs/.vitepress/theme/utils/tutorial.ts       |  5 ++--
 tests/components.test.ts                      |  7 ++---
 4 files changed, 44 insertions(+), 24 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 672888e..4a95104 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -225,7 +225,7 @@ function handleScroll() {
   scrollEndTimer = setTimeout(() => {
     isScrolling.value = false
     updatePagerState()
-  }, 150)
+  }, 200)
 }
 
 function pageForward(preventFocus = false) {
@@ -233,19 +233,15 @@ function pageForward(preventFocus = false) {
   if (!container) return
   const pageStep = Math.max(100, container.clientHeight - 40)
   container.scrollBy({ top: pageStep, behavior: 'smooth' })
-  setTimeout(() => {
-    updatePagerState()
-    if (!preventFocus && playerState.value === PlayerState.AWAITING_COMMAND) {
-      focusInput()
-    }
-  }, 300)
+  if (!preventFocus && playerState.value === PlayerState.AWAITING_COMMAND) {
+    focusInput()
+  }
 }
 
 function flushPager() {
   const container = logEl.value
   if (!container) return
   container.scrollTo({ top: container.scrollHeight, behavior: 'smooth' })
-  setTimeout(updatePagerState, 300)
 }
 
 const stepLabel = computed(() => `Chapter ${chapterNum.value} of ${totalChapters.value}`)
@@ -617,11 +613,14 @@ onMounted(() => {
     window.addEventListener('keydown', handleKeydown)
     document.addEventListener('fullscreenchange', handleFullscreenChange)
 
-    if (logEl.value && typeof ResizeObserver !== 'undefined') {
-      logResizeObserver = new ResizeObserver(() => {
-        updatePagerState()
-      })
-      logResizeObserver.observe(logEl.value)
+    if (logEl.value) {
+      logEl.value.addEventListener('scrollend', updatePagerState)
+      if (typeof ResizeObserver !== 'undefined') {
+        logResizeObserver = new ResizeObserver(() => {
+          updatePagerState()
+        })
+        logResizeObserver.observe(logEl.value)
+      }
     }
   }
 })
@@ -630,6 +629,9 @@ onUnmounted(() => {
   if (typeof window !== 'undefined') {
     window.removeEventListener('keydown', handleKeydown)
     document.removeEventListener('fullscreenchange', handleFullscreenChange)
+    if (logEl.value) {
+      logEl.value.removeEventListener('scrollend', updatePagerState)
+    }
     if (logResizeObserver) {
       logResizeObserver.disconnect()
       logResizeObserver = null
diff --git a/docs/.vitepress/theme/utils/markdown.ts b/docs/.vitepress/theme/utils/markdown.ts
index af3afc9..bb15647 100644
--- a/docs/.vitepress/theme/utils/markdown.ts
+++ b/docs/.vitepress/theme/utils/markdown.ts
@@ -45,12 +45,30 @@ export function formatInlineMarkdown(text: string | null | undefined, withBaseFn
   // Links: [text](url)
   safe = safe.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, linkText, url) => {
     const cleanText = linkText
-    let cleanUrl = url.trim()
-    if (!/^(?:https?:\/\/|mailto:)/i.test(cleanUrl) && cleanUrl.startsWith('/') && typeof withBaseFn === 'function') {
-      cleanUrl = withBaseFn(cleanUrl)
+    const trimmed = url.trim()
+
+    // Validate safe schemes: http, https, mailto, relative paths, or hash anchors
+    const isHttp = /^https?:\/\//i.test(trimmed)
+    const isMailto = /^mailto:/i.test(trimmed)
+    const isRelativeOrHash = /^(?:\/|\.\.|\.|\#)/.test(trimmed)
+
+    if (!isHttp && !isMailto && !isRelativeOrHash) {
+      return cleanText
+    }
+
+    let finalUrl = trimmed
+    if (finalUrl.startsWith('/') && typeof withBaseFn === 'function') {
+      finalUrl = withBaseFn(finalUrl)
     }
-    const isExternal = /^(?:https?:\/\/)/i.test(cleanUrl)
-    return `<a href="${cleanUrl}" ${isExternal ? 'target="_blank" rel="noopener noreferrer"' : ''} class="tut-link">${cleanText}</a>`
+
+    // Escape URL for HTML attribute insertion
+    const escapedUrl = finalUrl
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+
+    return `<a href="${escapedUrl}" ${isHttp ? 'target="_blank" rel="noopener noreferrer"' : ''} class="tut-link">${cleanText}</a>`
   })
 
   // Bold: **text** or __text__
diff --git a/docs/.vitepress/theme/utils/tutorial.ts b/docs/.vitepress/theme/utils/tutorial.ts
index 11b1c44..5ac5a22 100644
--- a/docs/.vitepress/theme/utils/tutorial.ts
+++ b/docs/.vitepress/theme/utils/tutorial.ts
@@ -27,8 +27,9 @@ export function normalizeChapterPath(rawPath: string | undefined, basePrefix: st
   if (!rawPath) return '/'
   let currentPath = rawPath.replace(/\.html$/, '').replace(/\/$/, '')
   const base = basePrefix || '/'
-  if (base !== '/' && currentPath.startsWith(base.replace(/\/$/, ''))) {
-    currentPath = '/' + currentPath.slice(base.replace(/\/$/, '').length).replace(/^\//, '')
+  const basePath = base.replace(/\/$/, '')
+  if (base !== '/' && basePath && (currentPath === basePath || currentPath.startsWith(basePath + '/'))) {
+    currentPath = '/' + currentPath.slice(basePath.length).replace(/^\//, '')
   }
   return currentPath || '/'
 }
diff --git a/tests/components.test.ts b/tests/components.test.ts
index 7ba1798..55b55f0 100644
--- a/tests/components.test.ts
+++ b/tests/components.test.ts
@@ -89,9 +89,8 @@ describe('MumeCommandGuide.vue', () => {
     expect(wrapper.find('.command-table').exists()).toBe(true)
     const filterTabs = wrapper.findAll('.filter-tab')
     const gearTab = filterTabs.find(b => b.text().includes('Gear & Inventory'))
-    if (gearTab) {
-      await gearTab.trigger('click')
-      expect(wrapper.text()).toContain('equipment')
-    }
+    expect(gearTab).toBeDefined()
+    await gearTab!.trigger('click')
+    expect(wrapper.text()).toContain('equipment')
   })
 })

From 69767bd02ebb1990d61a8f1cb1cf57fac9803250 Mon Sep 17 00:00:00 2001
From: nschimme <5505185+nschimme@users.noreply.github.com>
Date: Mon, 21 Sep 2026 15:40:18 +0000
Subject: [PATCH 15/15] fix(tutorial): ensure Enter key advances pagination and
 chapter complete states

- Add Enter keydown handling during CHAPTER_COMPLETE state to advance chapters or open end-of-tutorial modal on Chapter 15
- Add Enter keydown listener to pagination state to scroll terminal output
- Update unit tests to verify keydown handling for chapter complete state
---
 .../theme/components/TutorialPlayer.vue       | 22 +++++++++++++++++--
 tests/tutorial_player.test.ts                 | 21 ++++++++++++++++++
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/docs/.vitepress/theme/components/TutorialPlayer.vue b/docs/.vitepress/theme/components/TutorialPlayer.vue
index 4a95104..3eb7f46 100644
--- a/docs/.vitepress/theme/components/TutorialPlayer.vue
+++ b/docs/.vitepress/theme/components/TutorialPlayer.vue
@@ -156,6 +156,10 @@ function handleKeydown(e: KeyboardEvent) {
       closeImageModal()
       return
     }
+    if (isModalOpen.value) {
+      closeModal()
+      return
+    }
     if (isExpanded.value) {
       if (!document.fullscreenElement) {
         toggleExpand()
@@ -164,12 +168,22 @@ function handleKeydown(e: KeyboardEvent) {
     }
   }
 
-  // Intercept Space or PageDown for paging if output overflow is active and input is empty or unfocused
+  // Handle Enter or Space during Chapter Complete state
+  if (playerState.value === PlayerState.CHAPTER_COMPLETE) {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      submit()
+      return
+    }
+  }
+
+  // Intercept Enter, Space, or PageDown for paging if output overflow is active
   if (isScrollOverflowActive.value && !isScrolling.value) {
     const isInputFocused = typeof document !== 'undefined' && document.activeElement === inputEl.value
-    if ((e.key === 'PageDown' || e.key === ' ') && (!isInputFocused || !entry.value.trim())) {
+    if ((e.key === 'PageDown' || e.key === ' ' || e.key === 'Enter') && (!isInputFocused || !entry.value.trim())) {
       e.preventDefault()
       pageForward()
+      return
     }
   }
 }
@@ -783,6 +797,8 @@ onUnmounted(() => {
                     type="button"
                     class="tut-full-pager-btn"
                     @click.prevent="pageForward(true)"
+                    @keydown.enter.prevent="pageForward(true)"
+                    @keydown.space.prevent="pageForward(true)"
                     aria-label="Scroll to read more output">
               <i class="fa fa-chevron-circle-down tut-toast-icon" aria-hidden="true"></i>
               <span>{{ toastText }}</span>
@@ -793,6 +809,8 @@ onUnmounted(() => {
                     type="button"
                     class="tut-full-complete-btn"
                     @click.stop="submit()"
+                    @keydown.enter.prevent="submit()"
+                    @keydown.space.prevent="submit()"
                     aria-label="Advance to next chapter">
               <span>{{ completionPillText }}</span>
               <i class="fa fa-arrow-right tut-complete-icon" aria-hidden="true"></i>
diff --git a/tests/tutorial_player.test.ts b/tests/tutorial_player.test.ts
index 0f2517d..59ab8fd 100644
--- a/tests/tutorial_player.test.ts
+++ b/tests/tutorial_player.test.ts
@@ -88,4 +88,25 @@ describe('TutorialPlayer.vue', () => {
     await input.trigger('keydown.enter')
     expect(wrapper.text()).toContain("That command isn't recognized for this step of the tutorial.")
   })
+
+  it('triggers submit on Enter during Chapter Complete state', async () => {
+    const wrapper = mount(TutorialPlayer)
+    const input = wrapper.find('input')
+    await input.setValue('score')
+    await input.trigger('keydown.enter')
+    await input.setValue('info')
+    await input.trigger('keydown.enter')
+
+    // Wait for final step chapter completion timeout
+    await new Promise(resolve => setTimeout(resolve, 250))
+    await wrapper.vm.$nextTick()
+
+    // Expect chapter complete pill button
+    const completeBtn = wrapper.find('.tut-full-complete-btn')
+    expect(completeBtn.exists()).toBe(true)
+
+    // Window keydown Enter event should trigger completion action
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }))
+    await wrapper.vm.$nextTick()
+  })
 })