spqw/reveal-js-debugging

Reveal.js Debugging

Use this skill when working on a Reveal.js deck and any of the following happens:

• a slide is blank even though its content exists
• vertical or nested slides behave strangely
• fragments or present slides exist in the DOM but are not visible
• navigation works, but slide layout is broken
• custom CSS appears to break slide positioning

Load alongside

For browser inspection and live page debugging, also load:

• ../chrome-devtools-cli/SKILL.md

Use the Chrome DevTools CLI via bash to inspect the current deck in the browser.

Core lessons

1. Be very careful styling framework-owned section elements

Reveal.js controls slide layout using its own positioning rules on slide sections. A broad rule like this can break nested or vertical slides:

.reveal .slides section {
  position: relative;
}

This can cause active slides to render off-screen while still existing in the DOM and accessibility tree.

Prefer styling an inner wrapper instead, for example:

.theme-shell {
  position: relative;
  height: 100%;
}

Rule of thumb:

• avoid overriding layout-critical properties on .reveal .slides section
• put custom positioning on your own inner container like .theme-shell or .slide-frame

2. Snapshot presence does not guarantee visual correctness

A Reveal.js slide can:

• appear in the accessibility snapshot
• contain the right text in the DOM
• still be visually off-screen or invisible

So use both:

• take_snapshot to confirm semantic presence
• take_screenshot to confirm actual rendering

3. Computed layout is often the fastest signal

If a slide is blank, inspect:

• .slides section.present
• .slides > section.present
• .slides > section > section.present

Check:

• getBoundingClientRect()
• position
• top / left
• display
• transform
• whether the active slide rect is inside the viewport

A strong clue is: the slide is present, but its rect has a large y value outside the viewport.

Fast debugging workflow

1. Open the current deck in Chrome DevTools CLI

chrome-devtools list_pages
chrome-devtools select_page <pageId>
chrome-devtools take_snapshot

2. Navigate to the broken slide

Use Reveal controls or keyboard:

chrome-devtools press_key "ArrowRight" --includeSnapshot true
chrome-devtools press_key "ArrowDown" --includeSnapshot true

3. Compare semantic vs visual state

chrome-devtools take_snapshot
chrome-devtools take_screenshot --fullPage true --filePath "/tmp/reveal-debug.png"

If the snapshot shows content but the screenshot is blank, suspect CSS/layout rather than data/content loading.

4. Inspect active slide geometry

chrome-devtools evaluate_script '() => ({
  present: Array.from(document.querySelectorAll(".slides section.present")).map(el => {
    const r = el.getBoundingClientRect();
    const s = getComputedStyle(el);
    return {
      cls: el.className,
      text: (el.innerText || "").slice(0, 120),
      rect: { x: r.x, y: r.y, w: r.width, h: r.height },
      position: s.position,
      top: s.top,
      left: s.left,
      display: s.display,
      transform: s.transform,
      opacity: s.opacity,
      visibility: s.visibility
    };
  })
})'

5. Inspect suspicious CSS

Look for broad selectors affecting Reveal internals, especially:

• .reveal .slides section
• .reveal section
• section
• .stack
• .present

Common dangerous properties:

• position
• display
• transform
• overflow
• height
• min-height
• top / left

Known good pattern

Use Reveal-managed sections for slide structure and your own wrapper for layout:

<section class="theme-shell">
  <div class="slide-frame">
    <h2>Title</h2>
  </div>
</section>

.reveal .slides section {
  box-sizing: border-box;
}

.theme-shell {
  position: relative;
  height: 100%;
}

Practical heuristic

If Reveal.js looks broken:

1. suspect CSS before JavaScript
2. verify the active slide exists with snapshot/DOM inspection
3. verify it is actually in the viewport with getBoundingClientRect()
4. remove or narrow any global section rules
5. move custom layout onto inner wrapper elements