Guided Demo

Guided Demo Pattern

Add a self-narrating walkthrough to any HTML/web application. A declarative step array drives a setTimeout loop that toggles CSS classes on DOM elements and writes text character-by-character into a fixed panel. The engine overlays the existing page without modifying its code. When the demo stops, all state resets.

About 100 lines of JS and 30 lines of CSS for the core. Interstitials, speed controls, keyboard shortcuts, and progress bar are optional layering.

Before implementing

Ask the user these questions (skip any already answered in conversation):

1. What are the sections? Tabs, routes, scroll positions, slide indices? Determines how section switching works.
2. Framework? Vanilla HTML works directly. React/Vue/Svelte need the engine as a conditional overlay component, and querySelector must run after render.
3. Presenter talking over it, or self-narrating? Talking over: shorter text, longer pauses. Self-narrating: detailed text, moderate pauses.
4. Interactive elements to trigger? Map to step actions. Confirm CSS selectors are stable (not framework-generated hashes).
5. Offline requirement? Keep everything in one file if so. No CDN dependencies without fallbacks.
6. How many steps? Under 15 for a pitch, 20-30 for a detailed walkthrough. Over 40 loses attention.
7. Touch device support needed? Most guided demos target desktop/laptop presentation contexts. The narrator panel has on-screen prev/play/next buttons that work on touch, but swipe gestures or mobile-specific layout are rarely needed.

Implementation

Read references/implementation.md for all code snippets (vanilla JS / static HTML). If the target application uses React with React Router, also read references/react-integration.md for React-specific patterns covering stale closures, route navigation timing, and component architecture. For other SPA frameworks (Vue, Svelte, etc.), the same concepts apply (poll for elements after route change, store timer-relevant state outside the reactivity system) but the implementation details differ.

The four required pieces are:

1. Narrator panel - fixed-position bar with text container and progress bar
2. Highlight class - outline (not border) with animated glow, no layout shift
3. Typewriter function - recursive setTimeout, narration text set via textContent (never set user-authored narration via innerHTML), blinking cursor via CSS. The innerHTML = '' clearing before each tick is intentional and safe (no user content involved)
4. Playback loop - playStep(idx) that switches sections, runs actions, highlights, types, and auto-advances

Step array

The single source of truth. Each step is a plain object:

const DEMO_SCRIPT = [
  { section: 0, target: '.card', text: "Narration text." },
  { section: 1, target: null, text: "Transition.", transition: true },
  { section: 1, target: '#el', text: "Detail.", action: 'open', actionTarget: 'panel-id' },
];

Properties: section (which view), target (CSS selector or null), text (narrator copy), transition (show interstitial), action/actionTarget (trigger UI change), delay (optional per-step pause override in ms, defaults to PAUSE_MS).

Timing defaults

Writing narrator copy

The typewriter effect means each word lands individually, so writing style matters:

• Short declarative sentences. Each step should make exactly one point.
• Conversational tone, present tense. Address the audience directly.
• Describe what the element means, not what the UI shows: "This column quantifies the cost impact" not "The cost is shown in this column".
• No jargon the audience wouldn't know. Match terminology to the domain, not the implementation.
• Under 30 words per step for presenter-led demos, up to 50 for self-narrating.

Keyboard controls

Gate all keyboard capture behind an isActive flag so it does not interfere with normal page interaction. Space = play/pause, arrows = step, M = toggle TTS narration, Escape = exit and reset.

Text-to-speech narration

Browser-native TTS via the speechSynthesis Web Speech API reads each step's narration aloud alongside the typewriter. Include it in every demo but keep it off by default - never speak without explicit user action. The user toggles it with a speaker icon in the control bar and the M key. See references/implementation.md (Text-to-speech narration) for voice selection, the single call site, and cancellation.