Refine workshop docs rendering for desktop readability (parallax, lightbox, overflow) (#1712)

* Update docs reveal rendering for desktop readability

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Refine parallax SVG generation readability

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Harden docs rendering runtime compatibility

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Simplify slide sizing and parallax injection

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Polish responsive slide sizing styles

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* Clarify parallax configuration intent

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Author: Copilot

scripts/build-docs.js

@@ -237,6 +237,11 @@ const docsCss = `/* Improve link discoverability in rendered workshop docs */
  * Reveal.js overrides
  * ---------------------------------------------------------------- */
 
+/* Reduce default slide scale for desktop reading */
+.reveal {
+  font-size: 1.875rem;
+}
+
 /* Align text left; with center:false slides already start at top,
  * so no top override is needed. */
 .reveal .slides section {
@@ -247,15 +252,33 @@ const docsCss = `/* Improve link discoverability in rendered workshop docs */
  * long content does not get clipped. A single scroll container per
  * slide avoids nested-scrollbar confusion. */
 .reveal .slides .slide-content {
-  --slide-vertical-gap: 5rem;
-  font-size: 0.8em;
-  padding: 0 1.5em;
-  height: calc(100vh - var(--slide-vertical-gap));
-  max-height: calc(100vh - var(--slide-vertical-gap));
+  --slide-top-gap: 1.25rem;
+  /* Extra bottom room keeps content clear of Reveal controls/progress UI. */
+  --slide-bottom-gap: 4.75rem;
+  padding: var(--slide-top-gap) 1.5em var(--slide-bottom-gap);
+  height: calc(100vh - var(--slide-top-gap) - var(--slide-bottom-gap));
+  max-height: calc(100vh - var(--slide-top-gap) - var(--slide-bottom-gap));
+  min-height: 0;
   overflow-y: auto;
+  overflow-x: hidden;
+  scrollbar-gutter: stable;
   box-sizing: border-box;
 }
 
+@supports (height: 100dvh) {
+  .reveal .slides .slide-content {
+    height: calc(100dvh - var(--slide-top-gap) - var(--slide-bottom-gap));
+    max-height: calc(100dvh - var(--slide-top-gap) - var(--slide-bottom-gap));
+  }
+}
+
+/* Ensure slide images fit and advertise lightbox affordance */
+.reveal .slides .slide-content img {
+  max-width: 100%;
+  height: auto;
+  cursor: zoom-in;
+}
+
 /* Visually distinguish side-quest slides with a left border */
 .reveal .slides .side-quest-slide {
   border-left: 4px solid #0969da;
@@ -264,6 +287,29 @@ const docsCss = `/* Improve link discoverability in rendered workshop docs */
 `;
 fs.writeFileSync(path.join(distDir, 'docs.css'), docsCss);
 
+const parallaxBackgroundSvgEncoded = encodeURIComponent([
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1920 1080" preserveAspectRatio="xMidYMid slice">',
+  '<defs>',
+  '<linearGradient id="primaryGradient" x1="0" y1="0" x2="1" y2="1">',
+  '<stop offset="0%" stop-color="#0d1117" />',
+  '<stop offset="45%" stop-color="#271449" />',
+  '<stop offset="100%" stop-color="#8250df" />',
+  '</linearGradient>',
+  '<radialGradient id="topRadialGlow" cx="20%" cy="25%" r="40%">',
+  '<stop offset="0%" stop-color="#a371f7" stop-opacity=".32" />',
+  '<stop offset="100%" stop-color="#a371f7" stop-opacity="0" />',
+  '</radialGradient>',
+  '<radialGradient id="bottomRadialGlow" cx="82%" cy="78%" r="45%">',
+  '<stop offset="0%" stop-color="#6f42c1" stop-opacity=".30" />',
+  '<stop offset="100%" stop-color="#6f42c1" stop-opacity="0" />',
+  '</radialGradient>',
+  '</defs>',
+  '<rect width="1920" height="1080" fill="url(#primaryGradient)" />',
+  '<rect width="1920" height="1080" fill="url(#topRadialGlow)" />',
+  '<rect width="1920" height="1080" fill="url(#bottomRadialGlow)" />',
+  '</svg>',
+].join(''));
+
 // Generate docs runtime JavaScript
 const docsJs = `const legacyHashMatch = window.location.hash.match(/^#\\/([^/]+)$/);
 let legacySectionId = null;
@@ -281,6 +327,24 @@ if (hasLegacySectionTarget) {
   window.history.replaceState(null, '', '#' + legacySectionId);
 }
 
+function enableImageLightbox() {
+  const images = document.querySelectorAll('.slides section img');
+  images.forEach((img) => {
+    if (img.hasAttribute('data-preview-image') || img.hasAttribute('data-preview-video')) {
+      return;
+    }
+    if (img.closest('a[href]')) {
+      return;
+    }
+    const src = img.currentSrc || img.getAttribute('src');
+    if (src) {
+      img.setAttribute('data-preview-image', src);
+    }
+  });
+}
+
+const parallaxBackgroundImage = ${JSON.stringify(`data:image/svg+xml,${parallaxBackgroundSvgEncoded}`)};
+
 Reveal.initialize({
   // URL hash reflects current slide by section id
   hash: true,
@@ -290,8 +354,17 @@ Reveal.initialize({
   center: false,
   // Push slide changes into the browser history
   history: true,
+  // GitHub agentic-purple themed parallax background
+  parallaxBackgroundImage: parallaxBackgroundImage,
+  // Use a larger virtual canvas than the viewport so motion stays subtle.
+  parallaxBackgroundSize: '3200px 1800px',
+  // Horizontal movement is intentionally stronger than vertical to reduce jitter.
+  parallaxBackgroundHorizontal: 180,
+  parallaxBackgroundVertical: 70,
 });
 
+Reveal.on('ready', enableImageLightbox);
+
 if (hasLegacySectionTarget) {
   const target = document.getElementById(legacySectionId);
   const indices = target ? Reveal.getIndices(target) : null;