add pager and image lightbox

[nschimme]

Implements step rewind replay, integrated reactive MUD output pager, click-to-enlarge image lightbox modal, relative image paths in Markdown files, and test validation.

Summary by Sourcery

Enhance the tutorial player with rewindable steps, automatic output paging, and image lightbox previews while validating and documenting embedded Markdown assets.

New Features:

• Add interactive paging for overflowing tutorial output, including keyboard, touch, and prompt controls.
• Add clickable inline Markdown images with an accessible lightbox preview and captions.
• Allow tutorial step indicators to jump directly to earlier or later steps.

Bug Fixes:

• Support relative Markdown image paths and preserve external and data URLs when rendering tutorial content.
• Prevent stale automatic step advancement during navigation.

Enhancements:

• Improve tutorial replay by rebuilding the log when rewinding to a selected step and support multiline Markdown content.

Documentation:

• Document multiline tutorial content, embedded images, and automatic output paging for tutorial authors.
• Update the journey tutorial to demonstrate streamed images and multiline responses.

Tests:

• Validate relative Markdown image references and report missing assets in the link and asset path checks.

[sourcery-ai]

Reviewer's Guide

The tutorial player now rebuilds and rewinds interactive steps, provides reactive paging for overflowing terminal output, renders relative Markdown images with a click-to-enlarge lightbox, and updates tutorial content and validation to support multiline image-bearing story beats.

Sequence diagram for tutorial output paging and step rewind

sequenceDiagram
    participant User
    participant TutorialPlayer
    participant Log as TerminalLog
    participant Pager

    User->>TutorialPlayer: goToStep(targetIdx)
    TutorialPlayer->>TutorialPlayer: clearAutoAdvanceTimer()
    TutorialPlayer->>TutorialPlayer: rebuild log through target step
    TutorialPlayer->>Log: scrollLog()
    Log-->>Pager: overflow detected
    Pager->>Pager: updatePagerState()
    User->>TutorialPlayer: pageForward() via Space, Enter, or PageDown
    TutorialPlayer->>Log: scrollBy()
    Log-->>Pager: scroll event
    Pager->>Pager: updatePagerState()
    Pager-->>User: show current page and More prompt

Loading

Sequence diagram for tutorial image lightbox preview

sequenceDiagram
    participant User
    participant TutorialPlayer
    participant Log as TerminalLog
    participant Lightbox

    TutorialPlayer->>Log: render Markdown image
    User->>Log: click tut-img-embed
    Log->>TutorialPlayer: handleLogClick(event)
    TutorialPlayer->>Lightbox: openImageModal(src, alt)
    Lightbox-->>User: display enlarged image and caption
    User->>TutorialPlayer: press Escape or close button
    TutorialPlayer->>Lightbox: closeImageModal()
    Lightbox-->>User: hide preview

Loading

Flow diagram for relative Markdown image rendering

flowchart LR
    A[Markdown image in story beat] --> B[formatInlineMarkdown]
    B --> C[Normalize assets path]
    C --> D[Apply withBase]
    D --> E[Render tut-img-embed]
    E --> F[Click opens lightbox]

Loading

File-Level Changes

Change	Details	Files
Added interactive step rewind and direct step navigation by rebuilding the terminal log from the selected step history.	Introduced a reusable step-index navigation path for rewind, replay, and step-pill clicks. Reconstructed prior prompts, responses, examples, and story beats when jumping backward or forward. Added timer cancellation to prevent delayed automatic story advancement after navigation or route changes.	docs/.vitepress/theme/components/TutorialPlayer.vue
Added reactive terminal paging for overflowing tutorial output with keyboard, button, input, and touch-device controls.	Tracked scroll overflow, current/total pages, scrolling state, and container resizing. Added smooth page-forward and flush-to-bottom behavior for paging and command submission. Added Space/PageDown and empty-submit interactions while preserving normal command entry behavior.	docs/.vitepress/theme/components/TutorialPlayer.vue
Implemented inline Markdown image rendering and a click-to-enlarge lightbox within the tutorial player.	Parsed and sanitized Markdown image syntax alongside inline code and line breaks. Normalized relative asset paths through the VitePress base path. Added delegated image click handling, modal preview/caption rendering, backdrop and button dismissal, and Escape-key closing.	docs/.vitepress/theme/components/TutorialPlayer.vue
Migrated tutorial content to multiline YAML story and response blocks with images embedded at the relevant journey steps.	Replaced escaped newline response strings with YAML literal blocks. Moved web client and mapper screenshots into sequential story beats using relative Markdown paths. Documented image syntax, authoring guidance, and automatic paging behavior.	docs/play/TUTORIAL.md docs/play/tutorial/15-journey.md
Extended link and asset validation to verify Markdown image references throughout the documentation tree.	Recursively scanned docs Markdown files for image links. Resolved absolute asset paths against docs/public and relative paths against each Markdown file. Reported missing Markdown images and included their count in the test summary.	scripts/test-link-and-asset-paths.js

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 4 issues

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/.vitepress/theme/components/TutorialPlayer.vue" line_range="319" />
<code_context>

-function renderStepLog() {
-  subStepIdx.value = 0
+function goToStep(targetIdx) {
+  clearAutoAdvanceTimer()
+  if (targetIdx < 0) targetIdx = 0
</code_context>
<issue_to_address>
**issue (bug_risk):** goToStep does not clear `entry.value`, so navigating with a step pill or rewind leaves a partially typed command in the input and allows that stale command to be submitted against the newly selected step.

**Triggers:** When the user has typed a command and then navigates backward or selects another step before submitting it.

**Suggested fix:** Set `entry.value = ''` while reconstructing the step state in `goToStep`.

```suggestion
  finished.value = false
  entry.value = ''
```
</issue_to_address>

### Comment 2
<location path="docs/.vitepress/theme/components/TutorialPlayer.vue" line_range="338-339" />
<code_context>
+    if (step) {
+      if (step.ask) {
+        newLog.push({ kind: 'echo', text: step.ask })
+        const rawRes = step.response || step.example || mumeResponses.value[step.ask.toLowerCase()] || ''
+        const body = rawRes ? rawRes.replace(/^>[^\n]*\n?/, '') : ''
+        if (body) {
+          newLog.push({ kind: 'example', body })
</code_context>
<issue_to_address>
**issue (broader_impact):** The rewind replay looks up a response using the canonical `step.ask` rather than the accepted command that originally produced it, so a step whose response exists only under an accepted alias is replayed without its MUD output.

**Triggers:** When a step has an accepted alias and `step.response` is absent, while `mumeResponses` is keyed by that alias instead of the canonical `ask`.

**Suggested fix:** Persist or derive the actual accepted command used for each completed step, or search all accepted aliases when reconstructing the response.
</issue_to_address>

### Comment 3
<location path="docs/.vitepress/theme/components/TutorialPlayer.vue" line_range="31-33" />
<code_context>
+    const cleanAlt = alt.replace(/"/g, '&quot;')
+    let cleanSrc = src.trim().replace(/"/g, '&quot;')
+
+    if (cleanSrc.includes('assets/')) {
+      cleanSrc = '/assets/' + cleanSrc.split('assets/')[1]
+    }
+
</code_context>
<issue_to_address>
**issue (bug_risk):** Any image URL containing `assets/` is forcibly rewritten to a site-local `/assets/...` path, so external URLs such as `https://cdn.example.com/assets/image.png` are changed to `/assets/image.png` and fail to load.

**Triggers:** When tutorial Markdown contains an external image URL whose hostname or path includes `assets/`.

**Suggested fix:** Normalize only the intended relative `public/assets` paths and leave absolute `http://`, `https://`, and data URLs unchanged.

```suggestion
    if (/^(?:\.\.\/|\.\/)*public\/assets\//.test(cleanSrc)) {
      cleanSrc = '/assets/' + cleanSrc.split('public/assets/')[1]
    }
```
</issue_to_address>

### Comment 4
<location path="docs/.vitepress/theme/components/TutorialPlayer.vue" line_range="188" />
<code_context>
+  }
+
+  // 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
+    if (e.key === 'PageDown' || (e.key === ' ' && (!isInputFocused || !entry.value.trim()))) {
+      e.preventDefault()
+      pageForward()
     }
   }
</code_context>
<issue_to_address>
**nitpick (bug_risk):** The global key handler intercepts `PageDown` whenever pager overflow is active, even when the command input is focused and contains text, so PageDown cannot be used normally while entering a command and is always converted into pager navigation.

**Triggers:** When output is overflowing and the user presses PageDown while the input is focused.

**Suggested fix:** Apply the same empty-or-unfocused input guard to PageDown that is applied to Space, unless pager navigation is explicitly intended to override input editing.

```suggestion
    if ((e.key === 'PageDown' || e.key === ' ') && (!isInputFocused || !entry.value.trim())) {
```
</issue_to_address>

Sourcery assessment

Approval pending. 3 findings to address first.

Blocking findings: docs/.vitepress/theme/components/TutorialPlayer.vue:319, docs/.vitepress/theme/components/TutorialPlayer.vue:339, docs/.vitepress/theme/components/TutorialPlayer.vue:33

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

Sourcery assessment

Approved.