conversation-replay 0.1.13 → 0.1.15

package/dist/cli.js

@@ -1,5 +1,21 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -7270,7 +7286,7 @@ import { writeFile } from "node:fs/promises";
 // package.json
 var package_default = {
   name: "conversation-replay",
-  version: "0.1.13",
+  version: "0.1.15",
   description: "Create annotated replays of text conversations",
   main: "dist/cli.js",
   type: "module",
@@ -7279,6 +7295,7 @@ var package_default = {
   },
   files: [
     "dist",
+    "schema.json",
     "README.md"
   ],
   scripts: {
@@ -7431,21 +7448,107 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
   const radiusLg = cornerStyle === "straight" ? "0" : "12px";
   const blurAmount = initialBlur ?? 1;
   const tabCss = hasMultipleScenarios ? `
-    /* Tabs - browser-style integrated with canvas */
+    /* Tabs - horizontal scrolling with arrow navigation */
+    .tabs-wrapper {
+      position: relative;
+      margin-left: 12px;
+      margin-right: 12px;
+      margin-bottom: -1px;
+      overflow: hidden;
+    }
+
+    .tab-scroll-btn {
+      position: absolute;
+      top: 0;
+      bottom: 1px;
+      width: 32px;
+      border: none;
+      background: transparent;
+      cursor: pointer;
+      z-index: 4;
+      display: none;
+      align-items: center;
+      justify-content: center;
+      padding: 0;
+      color: var(--text-primary);
+      transition: color 0.2s ease;
+    }
+
+    .tab-scroll-btn:hover {
+      color: var(--accent);
+    }
+
+    .tab-scroll-btn svg {
+      width: 16px;
+      height: 16px;
+      fill: currentColor;
+      /* Glow effect makes icon visible on any background */
+      filter: drop-shadow(0 0 2px rgba(255, 255, 255, 1))
+              drop-shadow(0 0 4px rgba(255, 255, 255, 0.8))
+              drop-shadow(0 0 6px rgba(255, 255, 255, 0.6));
+    }
+
+    :root[data-theme="dark"] .tab-scroll-btn svg {
+      filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.8))
+              drop-shadow(0 0 4px rgba(0, 0, 0, 0.6));
+    }
+
+    .tab-scroll-btn.left {
+      left: 0;
+    }
+
+    .tab-scroll-btn.right {
+      right: 0;
+    }
+
+    /* Use mask-image to fade tabs at edges - works on any background */
+    /* Fade zone is larger so text is fully transparent before reaching the chevron */
+    .tabs-wrapper.can-scroll-right .tabs {
+      -webkit-mask-image: linear-gradient(to right, black 0%, black calc(100% - 60px), transparent calc(100% - 20px), transparent 100%);
+      mask-image: linear-gradient(to right, black 0%, black calc(100% - 60px), transparent calc(100% - 20px), transparent 100%);
+    }
+
+    .tabs-wrapper.can-scroll-left .tabs {
+      -webkit-mask-image: linear-gradient(to left, black 0%, black calc(100% - 60px), transparent calc(100% - 20px), transparent 100%);
+      mask-image: linear-gradient(to left, black 0%, black calc(100% - 60px), transparent calc(100% - 20px), transparent 100%);
+    }
+
+    .tabs-wrapper.can-scroll-left.can-scroll-right .tabs {
+      -webkit-mask-image: linear-gradient(to right, transparent 0%, transparent 20px, black 60px, black calc(100% - 60px), transparent calc(100% - 20px), transparent 100%);
+      mask-image: linear-gradient(to right, transparent 0%, transparent 20px, black 60px, black calc(100% - 60px), transparent calc(100% - 20px), transparent 100%);
+    }
+
+    .tabs-wrapper.can-scroll-left .tab-scroll-btn.left {
+      display: flex;
+    }
+
+    .tabs-wrapper.can-scroll-right .tab-scroll-btn.right {
+      display: flex;
+    }
+
     .tabs {
       display: flex;
       gap: 0;
-      margin-left: 12px;
-      margin-bottom: -1px;
-      flex-wrap: wrap;
+      flex-wrap: nowrap;
+      overflow-x: auto;
+      overflow-y: hidden;
+      -webkit-overflow-scrolling: touch;
+      scroll-snap-type: x mandatory;
+      scroll-behavior: smooth;
+      scrollbar-width: none;
+      -ms-overflow-style: none;
       position: relative;
       z-index: 2;
     }
 
+    .tabs::-webkit-scrollbar {
+      display: none;
+    }
+
     .tab {
       padding: 10px 20px;
       border: 1px solid transparent;
-      border-bottom: none;
+      border-bottom: 1px solid var(--border-color);
       background: transparent;
       color: var(--tab-inactive-color, var(--text-secondary));
       border-radius: var(--radius) var(--radius) 0 0;
@@ -7453,6 +7556,9 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       font-size: 13px;
       font-weight: 500;
       transition: all 0.2s;
+      flex-shrink: 0;
+      scroll-snap-align: start;
+      white-space: nowrap;
     }
 
     .tab:hover {
@@ -7463,50 +7569,32 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       background: var(--bg-chat);
       color: var(--text-primary);
       border-color: var(--border-color);
+      border-bottom-color: var(--bg-chat);
       position: relative;
     }
 
-    .tab.active::after {
-      content: '';
-      position: absolute;
-      bottom: -1px;
-      left: 0;
-      right: 0;
-      height: 2px;
-      background: var(--bg-chat);
-    }
-
     @media (max-width: 600px) {
+      .tabs-wrapper {
+        margin-left: 12px;
+        margin-right: 12px;
+      }
+
       .tabs {
-        flex-wrap: nowrap;
-        overflow: hidden; /* No scrolling - tabs will truncate */
-        padding: 0 12px; /* Align with canvas border-radius */
-        margin-left: 0;
+        padding: 0;
       }
 
       .tab {
-        padding: 10px 12px;
+        padding: 10px 16px;
         font-size: 12px;
-        flex: 1 1 0; /* Shrink equally */
-        text-align: center;
-        min-width: 60px; /* Don't get too small */
-        white-space: nowrap;
-        overflow: hidden;
-        text-overflow: ellipsis;
+        min-width: 100px;
+        max-width: 150px;
+      }
+
+      .tab-scroll-btn {
+        width: 28px;
       }
     }
-    
-    /* In iframe, ensure non-active tabs are visible against potentially dark/complex backgrounds */
-    body.in-iframe .tab:not(.active) {
-       background: rgba(255, 255, 255, 0.5);
-       backdrop-filter: blur(4px);
-       -webkit-backdrop-filter: blur(4px);
-    }
-    
-    :root[data-theme="dark"] body.in-iframe .tab:not(.active) {
-       background: rgba(30, 41, 59, 0.5);
-       color: rgba(248, 250, 252, 0.7);
-    }
+
   ` : "";
   return `
     *, *::before, *::after {
@@ -7601,6 +7689,11 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
         --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.3);
         --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.4);
       }
+
+      .tab-scroll-btn svg {
+        filter: drop-shadow(0 0 2px rgba(0, 0, 0, 0.8))
+                drop-shadow(0 0 4px rgba(0, 0, 0, 0.6));
+      }
     }
 
     /* Dark mode via data-theme attribute (for iframe sync with parent) */
@@ -7792,7 +7885,7 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       display: flex;
       flex-direction: column;
       background: transparent !important;
-      padding: 0 !important;
+      padding: 0;
       margin: 0 !important;
       border: none !important;
       box-shadow: none !important;
@@ -7813,17 +7906,14 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       max-height: none !important; /* Remove height constraint in iframe */
       box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05) !important; /* Subtle shadow in iframe */
       background: var(--bg-chat) !important; /* Ensure opaque background in iframe */
-      margin-bottom: clamp(70px, 15vh, 120px); /* Responsive space for fixed controls */
     }
 
     body.in-iframe .controls-wrapper {
-      position: fixed;
-      bottom: 12px;
-      left: 0;
-      right: 0;
+      position: relative;
+      flex-shrink: 0;
       display: flex;
       justify-content: center;
-      pointer-events: none; /* Let clicks pass through around buttons */
+      padding: 12px 0;
       z-index: 20;
     }
 
@@ -7833,6 +7923,8 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       flex-direction: column;
       gap: 20px;
       padding-bottom: 80px; /* Space for floating controls */
+      padding-left: 32px;   /* Symmetric with right */
+      padding-right: 32px;  /* Clearance for timer circle */
     }
 
     .play-overlay {
@@ -7920,8 +8012,7 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       font-weight: 600;
       letter-spacing: 0.02em;
       margin-bottom: 6px;
-      color: var(--text-muted);
-      opacity: 0.8;
+      color: var(--text-secondary);
       display: flex;
       align-items: center;
       gap: 6px;
@@ -7999,7 +8090,7 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       width: 100%;
       margin: 24px 0;
       padding: 0 0 0 20px;
-      font-size: 15px;
+      font-size: 16px;
       font-style: italic;
       color: var(--annotation-text);
       opacity: 0;
@@ -8012,10 +8103,9 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       left: 0;
       top: 2px;
       bottom: 2px;
-      width: 3px;
+      width: 4px;
       background: var(--annotation-border);
-      border-radius: 1.5px;
-      opacity: 0.5;
+      border-radius: 2px;
     }
 
     .annotation.visible {
@@ -8025,7 +8115,7 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
     }
 
     .annotation-label {
-      font-size: 10px;
+      font-size: 11px;
       font-weight: 700;
       text-transform: uppercase;
       letter-spacing: 0.05em;
@@ -8035,7 +8125,6 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       display: flex;
       align-items: center;
       gap: 6px;
-      opacity: 0.8;
     }
 
     .annotation-content {
@@ -8354,10 +8443,6 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
         min-height: 250px;
       }
 
-      body.in-iframe .chat-container {
-        max-height: 400px;
-      }
-
       .controls {
         gap: 8px;
         padding-top: 12px;
@@ -8416,20 +8501,37 @@ function generateCss(theme, hasMultipleScenarios, colors, cornerStyle, initialBl
       }
 
       .controls {
-        flex-wrap: wrap;
-        justify-content: center;
+        flex-wrap: nowrap;
+        gap: 4px;
+        padding: 6px 8px;
+      }
+
+      .controls .divider {
+        display: none; /* Hide dividers to save space */
       }
 
       .control-btn {
-        flex: 0 0 auto;
+        width: 36px;
+        height: 36px;
+        min-width: 36px;
+        min-height: 36px;
+        padding: 0;
       }
 
       .control-btn.primary {
-        order: -1;
-        flex: 0 0 auto;
-        width: 44px;
-        height: 44px;
-        margin-bottom: 4px;
+        width: 40px;
+        height: 40px;
+      }
+
+      .speed-select {
+        padding: 6px 8px;
+        min-width: 32px;
+        font-size: 12px;
+      }
+
+      .progress {
+        font-size: 11px;
+        min-width: 36px;
       }
     }
 
@@ -8606,6 +8708,7 @@ function generateJs(demo, timerStyle) {
       var isPaused = false;
       var animationTimeout = null;
       var speed = 1;
+      var currentStepBaseDelay = 0; // Base delay before speed adjustment (for mid-playback speed changes)
       var hasStarted = false;
 
       // DOM elements
@@ -8620,6 +8723,8 @@ function generateJs(demo, timerStyle) {
       var timerElement = document.getElementById('timer-element');
       var chatContainer = document.getElementById('chat-container');
       var tabs = document.querySelectorAll('.tab');
+      var tabsContainer = document.querySelector('.tabs');
+      var tabsWrapper = document.querySelector('.tabs-wrapper');
       var infoBtn = document.getElementById('info-btn');
       var infoPopover = document.getElementById('info-popover');
 
@@ -8788,7 +8893,7 @@ function generateJs(demo, timerStyle) {
 
         if (step.footnote) {
           var footnote = document.createElement('p');
-          footnote.style.cssText = 'margin: 8px 0 0 0; font-style: italic; font-size: 12px; color: var(--text-secondary);';
+          footnote.style.cssText = 'margin: 8px 0 0 0; font-style: italic; font-size: 15px; color: var(--text-secondary);';
           footnote.textContent = step.footnote;
           contentWrapper.appendChild(footnote);
         }
@@ -8946,6 +9051,9 @@ function generateJs(demo, timerStyle) {
             playOverlay.classList.add('hidden');
             chatContainer.classList.remove('fading');
 
+            // Ensure new active tab is visible (not in fade zone)
+            scrollActiveTabIntoView();
+
             // Auto-play immediately
             play();
           }, 300);
@@ -8989,6 +9097,7 @@ function generateJs(demo, timerStyle) {
 
         if (currentStepIndex < steps.length) {
           var delay = calculateDelay(step);
+          currentStepBaseDelay = delay * speed; // Store base delay for mid-playback speed changes
           startTimer(delay);
           animationTimeout = setTimeout(showNextStep, delay);
         } else {
@@ -9013,7 +9122,16 @@ function generateJs(demo, timerStyle) {
 
           var steps = getSteps();
           var firstStep = steps[0];
+
+          // Show first step if not already visible (e.g., during auto-advance)
+          if (chatMessages.children.length === 0) {
+            var element = createStepElement(firstStep);
+            element.classList.add('visible');
+            chatMessages.appendChild(element);
+          }
+
           var delay = calculateDelay(firstStep);
+          currentStepBaseDelay = delay * speed; // Store base delay for mid-playback speed changes
           currentStepIndex = 1;
 
           startTimer(delay);
@@ -9044,6 +9162,7 @@ function generateJs(demo, timerStyle) {
           updateButtonStates();
 
           var delay = calculateDelay(steps[0]);
+          currentStepBaseDelay = delay * speed; // Store base delay for mid-playback speed changes
           startTimer(delay);
           animationTimeout = setTimeout(showNextStep, delay);
           return;
@@ -9143,23 +9262,26 @@ function generateJs(demo, timerStyle) {
           } else {
             // Always show initial preview to render the first message
             showInitialPreview();
-            
+
             if (wasPlaying) {
               // If we were playing, continue playing (this will hide the overlay again)
               play();
             } else {
-              // If we weren't playing, ensure the overlay is hidden? 
+              // If we weren't playing, ensure the overlay is hidden?
               // The original comment said "keep overlay hidden" but showInitialPreview shows it.
-              // If we pause, we usually show the play button? 
+              // If we pause, we usually show the play button?
               // Actually, standard behavior is usually to show the play button on a fresh tab.
               // But strictly following the intention of "keep overlay hidden" would mean adding it back?
               // Let's stick to standard behavior: new tab = reset state = show play button.
-              // showInitialPreview() handles that. 
-              
+              // showInitialPreview() handles that.
+
               // However, check if we want to suppress it:
               // "User can click play button or canvas to start"
             }
           }
+
+          // Ensure active tab is fully visible (not obscured by scroll buttons)
+          scrollActiveTabIntoView();
         }, 300);
       }
 
@@ -9236,7 +9358,29 @@ function generateJs(demo, timerStyle) {
       }
 
       speedSelect.addEventListener('change', function(e) {
+        var oldSpeed = speed;
         speed = parseFloat(e.target.value);
+
+        // If playing, recalculate and reschedule with new speed
+        if (isPlaying && !isPaused && animationTimeout && currentStepBaseDelay > 0) {
+          var elapsed = Date.now() - timerStartTime;
+          var elapsedBase = elapsed * oldSpeed; // Content time consumed
+          var remainingBase = currentStepBaseDelay - elapsedBase;
+
+          if (remainingBase > 0) {
+            // Cancel current timeout (but keep timer animation running)
+            clearTimeout(animationTimeout);
+
+            // Adjust timer variables so animation continues from current position
+            // progress = elapsed / timerDuration should remain the same
+            timerDuration = currentStepBaseDelay / speed;
+            timerStartTime = Date.now() - (elapsedBase / speed);
+
+            // Reschedule with remaining time at new speed
+            var remainingTime = remainingBase / speed;
+            animationTimeout = setTimeout(showNextStep, remainingTime);
+          }
+        }
       });
 
       // Handle page visibility changes (pause timer animation when tab is hidden)
@@ -9249,8 +9393,78 @@ function generateJs(demo, timerStyle) {
         });
       }
 
+      // Scroll indicators for mobile tabs
+      function updateTabScrollIndicators() {
+        if (!tabsContainer || !tabsWrapper) return;
+
+        var scrollLeft = tabsContainer.scrollLeft;
+        var maxScroll = tabsContainer.scrollWidth - tabsContainer.clientWidth;
+        var threshold = 2; // Account for sub-pixel rendering
+
+        if (scrollLeft > threshold) {
+          tabsWrapper.classList.add('can-scroll-left');
+        } else {
+          tabsWrapper.classList.remove('can-scroll-left');
+        }
+
+        if (scrollLeft < maxScroll - threshold) {
+          tabsWrapper.classList.add('can-scroll-right');
+        } else {
+          tabsWrapper.classList.remove('can-scroll-right');
+        }
+      }
+
+      // Auto-scroll to ensure active tab is fully visible (outside the fade zone)
+      function scrollActiveTabIntoView() {
+        if (!tabsContainer) return;
+        var activeTab = tabsContainer.querySelector('.tab.active');
+        if (!activeTab) return;
+
+        var containerRect = tabsContainer.getBoundingClientRect();
+        var tabRect = activeTab.getBoundingClientRect();
+        var fadeZone = 70; // Must be larger than CSS mask fade zone (60px) to keep active tab fully opaque
+
+        // Check if tab is cut off on the right
+        if (tabRect.right > containerRect.right - fadeZone) {
+          tabsContainer.scrollBy({
+            left: tabRect.right - containerRect.right + fadeZone + 8,
+            behavior: 'smooth'
+          });
+        }
+        // Check if tab is cut off on the left
+        else if (tabRect.left < containerRect.left + fadeZone) {
+          tabsContainer.scrollBy({
+            left: tabRect.left - containerRect.left - fadeZone - 8,
+            behavior: 'smooth'
+          });
+        }
+      }
+
+      if (tabsContainer && tabsWrapper) {
+        tabsContainer.addEventListener('scroll', updateTabScrollIndicators, { passive: true });
+        window.addEventListener('resize', updateTabScrollIndicators, { passive: true });
+
+        // Arrow button click handlers
+        var scrollLeftBtn = tabsWrapper.querySelector('.tab-scroll-btn.left');
+        var scrollRightBtn = tabsWrapper.querySelector('.tab-scroll-btn.right');
+        var scrollAmount = 200; // pixels to scroll per click
+
+        if (scrollLeftBtn) {
+          scrollLeftBtn.addEventListener('click', function() {
+            tabsContainer.scrollBy({ left: -scrollAmount, behavior: 'smooth' });
+          });
+        }
+
+        if (scrollRightBtn) {
+          scrollRightBtn.addEventListener('click', function() {
+            tabsContainer.scrollBy({ left: scrollAmount, behavior: 'smooth' });
+          });
+        }
+      }
+
       // Initialize
       updateTabStates();
+      updateTabScrollIndicators();
       showInitialPreview();
 
       if (prefersReducedMotion) {
@@ -9271,9 +9485,17 @@ function generateTabsHtml(demo) {
   }).join(`
       `);
   return `
-    <nav class="tabs" role="tablist">
-      ${tabButtons}
-    </nav>
+    <div class="tabs-wrapper">
+      <button class="tab-scroll-btn left" aria-label="Scroll tabs left">
+        <svg viewBox="0 0 24 24"><path d="M18.41 7.41L17 6l-6 6 6 6 1.41-1.41L13.83 12z"/><path d="M12.41 7.41L11 6l-6 6 6 6 1.41-1.41L7.83 12z"/></svg>
+      </button>
+      <nav class="tabs" role="tablist">
+        ${tabButtons}
+      </nav>
+      <button class="tab-scroll-btn right" aria-label="Scroll tabs right">
+        <svg viewBox="0 0 24 24"><path d="M5.59 7.41L7 6l6 6-6 6-1.41-1.41L10.17 12z"/><path d="M11.59 7.41L13 6l6 6-6 6-1.41-1.41L16.17 12z"/></svg>
+      </button>
+    </div>
   `;
 }
 function generateHtml(demo, options = { outputPath: "" }) {
@@ -9391,6 +9613,394 @@ async function buildDemo(demo, outputPath, options = {}) {
   await writeFile(outputPath, html, "utf-8");
 }
 
+// src/schema.ts
+function generateTemplate(theme) {
+  const selectedTheme = theme || "chat";
+  return `# Conversation Replay - Demo Configuration
+# Documentation: https://github.com/lennyzeltser/conversation-replay
+#
+# Run: conversation-replay build this-file.yaml -o output.html
+# Validate: conversation-replay validate this-file.yaml
+
+meta:
+  title: "My Demo Title"                    # Required: shown in header
+  description: "A brief description"        # Optional: shown below title
+  theme: ${selectedTheme}                            # chat | email | slack | terminal | generic
+  # articleUrl: "/related-article"          # Optional: "View Article" link
+  # annotationLabel: "Behind the Scenes"    # Label for annotation steps
+  # autoAdvance: true                        # Auto-play next scenario when current ends
+
+  # Timer and visual style
+  # timerStyle: circle                       # circle | bar
+  # cornerStyle: rounded                     # rounded | straight
+  # initialBlur: 1                           # Blur amount for play overlay (px)
+
+  # Custom colors (all optional)
+  # colors:
+  #   accent: "#4f46e5"                      # Buttons, links (Indigo 600)
+  #   pageBg: "#f8fafc"                      # Page background (Slate 50)
+  #   canvasBg: "#ffffff"                    # Chat container background
+  #   leftBg: "#eef2ff"                      # Left bubble background (Indigo 50)
+  #   leftBorder: "transparent"              # Left bubble border
+  #   rightBg: "#f1f5f9"                     # Right bubble background (Slate 100)
+  #   rightBorder: "transparent"             # Right bubble border
+  #   annotationText: "#475569"              # Annotation text (Slate 600)
+  #   annotationBorder: "#cbd5e1"            # Annotation accent bar (Slate 300)
+
+  # Timing configuration (all in milliseconds)
+  # speed:
+  #   minDelay: 3000                         # Minimum delay between steps
+  #   maxDelay: 8000                         # Maximum delay between steps
+  #   msPerWord: 200                         # Reading time per word
+  #   annotationMultiplier: 1.15             # Extra time for annotations
+  #   upNextDelay: 2500                      # "Up Next" display time
+
+scenarios:
+  - id: main
+    title: "Scenario Title"                  # Shown in tab (if multiple scenarios)
+
+    participants:
+      - id: user1
+        label: "Person A"
+        role: left                           # Messages appear on left
+      - id: user2
+        label: "Person B"
+        role: right                          # Messages appear on right
+
+    steps:
+      # Message from a participant
+      - type: message
+        from: user1                          # Must match a participant id
+        content: "Hello! This is a sample message."
+
+      - type: message
+        from: user2
+        content: "Hi there! Here's a response."
+        # footnote: "Optional italic footnote below the message"
+
+      # Message with code block
+      # - type: message
+      #   from: user2
+      #   content: "Here's some code:"
+      #   codeBlock: |
+      #     function example() {
+      #       return "hello";
+      #     }
+
+      # Annotation - educational callout with accent bar
+      - type: annotation
+        content: "This annotation explains something to the viewer."
+
+      # Transition - centered scene break
+      # - type: transition
+      #   content: "Later that day..."
+
+  # Additional scenarios appear as tabs
+  # - id: part2
+  #   title: "Part Two"
+  #   participants:
+  #     - id: analyst
+  #       label: "Analyst"
+  #       role: left
+  #   steps:
+  #     - type: message
+  #       from: analyst
+  #       content: "This is another scenario."
+`;
+}
+var jsonSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://github.com/lennyzeltser/conversation-replay/schema.json",
+  title: "Conversation Replay Demo",
+  description: "Schema for conversation-replay YAML configuration files",
+  type: "object",
+  required: ["meta", "scenarios"],
+  properties: {
+    meta: {
+      type: "object",
+      description: "Demo metadata and configuration",
+      required: ["title"],
+      properties: {
+        title: {
+          type: "string",
+          description: "Demo title shown in header",
+          minLength: 1
+        },
+        description: {
+          type: "string",
+          description: "Brief description shown below title"
+        },
+        theme: {
+          type: "string",
+          enum: ["chat", "email", "slack", "terminal", "generic"],
+          description: "Visual theme for message styling",
+          default: "chat"
+        },
+        articleUrl: {
+          type: "string",
+          description: "URL for 'View Article' link in header"
+        },
+        hideHeaderInIframe: {
+          type: "boolean",
+          description: "Auto-hide header when embedded in iframe",
+          default: true
+        },
+        autoAdvance: {
+          type: "boolean",
+          description: "Auto-play next scenario when current one completes"
+        },
+        annotationLabel: {
+          type: "string",
+          description: "Label shown above annotation content",
+          default: "Behind the Scenes"
+        },
+        timerStyle: {
+          type: "string",
+          enum: ["bar", "circle"],
+          description: "Countdown timer display style",
+          default: "circle"
+        },
+        cornerStyle: {
+          type: "string",
+          enum: ["rounded", "straight"],
+          description: "Border radius style for containers and bubbles",
+          default: "rounded"
+        },
+        initialBlur: {
+          type: "number",
+          description: "Blur amount in pixels for play overlay",
+          default: 1,
+          minimum: 0
+        },
+        colors: {
+          type: "object",
+          description: "Custom color overrides",
+          properties: {
+            accent: { type: "string", description: "Primary accent color (buttons, links)" },
+            pageBg: { type: "string", description: "Page background color" },
+            canvasBg: { type: "string", description: "Chat container background" },
+            leftBg: { type: "string", description: "Left participant bubble background" },
+            leftBorder: { type: "string", description: "Left participant bubble border" },
+            rightBg: { type: "string", description: "Right participant bubble background" },
+            rightBorder: { type: "string", description: "Right participant bubble border" },
+            tabInactiveColor: { type: "string", description: "Inactive tab text color" },
+            annotationText: { type: "string", description: "Annotation text color" },
+            annotationBorder: { type: "string", description: "Annotation accent bar color" }
+          }
+        },
+        speed: {
+          type: "object",
+          description: "Timing configuration for playback",
+          properties: {
+            minDelay: { type: "number", description: "Minimum delay between steps (ms)", default: 3000 },
+            maxDelay: { type: "number", description: "Maximum delay between steps (ms)", default: 8000 },
+            msPerWord: { type: "number", description: "Milliseconds per word for reading time", default: 200 },
+            annotationMultiplier: { type: "number", description: "Time multiplier for annotations", default: 1.15 },
+            upNextDelay: { type: "number", description: "'Up Next' display duration (ms)", default: 2500 }
+          }
+        }
+      }
+    },
+    scenarios: {
+      type: "array",
+      description: "One or more conversation scenarios (shown as tabs if multiple)",
+      minItems: 1,
+      items: {
+        type: "object",
+        required: ["id", "title", "participants", "steps"],
+        properties: {
+          id: {
+            type: "string",
+            description: "Unique identifier for this scenario",
+            minLength: 1
+          },
+          title: {
+            type: "string",
+            description: "Display title (shown in tab)",
+            minLength: 1
+          },
+          participants: {
+            type: "array",
+            description: "People/entities in this conversation",
+            minItems: 1,
+            items: {
+              type: "object",
+              required: ["id", "label"],
+              properties: {
+                id: {
+                  type: "string",
+                  description: "Unique identifier (referenced in message 'from' field)"
+                },
+                label: {
+                  type: "string",
+                  description: "Display name shown above messages"
+                },
+                role: {
+                  type: "string",
+                  enum: ["left", "right"],
+                  description: "Which side messages appear on",
+                  default: "left"
+                }
+              }
+            }
+          },
+          steps: {
+            type: "array",
+            description: "Sequence of messages, annotations, and transitions",
+            minItems: 1,
+            items: {
+              oneOf: [
+                {
+                  type: "object",
+                  description: "A message from a participant",
+                  required: ["type", "from", "content"],
+                  properties: {
+                    type: { const: "message" },
+                    from: { type: "string", description: "Participant ID" },
+                    content: { type: "string", description: "Message text" },
+                    codeBlock: { type: "string", description: "Optional code/preformatted text" },
+                    footnote: { type: "string", description: "Optional italic footnote" }
+                  }
+                },
+                {
+                  type: "object",
+                  description: "An educational annotation/callout",
+                  required: ["type", "content"],
+                  properties: {
+                    type: { const: "annotation" },
+                    content: { type: "string", description: "Annotation text" }
+                  }
+                },
+                {
+                  type: "object",
+                  description: "A scene break/transition",
+                  required: ["type", "content"],
+                  properties: {
+                    type: { const: "transition" },
+                    content: { type: "string", description: "Transition text (e.g., 'Later that day...')" }
+                  }
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+};
+function getSchemaReference(section) {
+  if (section === "meta") {
+    return `
+META OPTIONS
+============
+
+Required:
+  title: string              Demo title shown in header
+
+Optional:
+  description: string        Brief description below title
+  theme: string              chat | email | slack | terminal | generic (default: chat)
+  articleUrl: string         URL for "View Article" link
+  annotationLabel: string    Label for annotations (default: "Behind the Scenes")
+  autoAdvance: boolean       Auto-play next scenario when current ends
+  hideHeaderInIframe: bool   Auto-hide header when embedded (default: true)
+  timerStyle: string         circle | bar (default: circle)
+  cornerStyle: string        rounded | straight (default: rounded)
+  initialBlur: number        Play overlay blur in px (default: 1)
+  colors: object             Custom color overrides (see: schema colors)
+  speed: object              Timing configuration (see: schema speed)
+`;
+  }
+  if (section === "colors") {
+    return `
+COLOR OPTIONS (meta.colors)
+===========================
+
+All colors are optional CSS color values (hex, rgb, named colors, etc.)
+
+  accent: string             Buttons, links (default: #4f46e5)
+  pageBg: string             Page background (default: #f8fafc)
+  canvasBg: string           Chat container background (default: #ffffff)
+  leftBg: string             Left bubble background (default: #eef2ff)
+  leftBorder: string         Left bubble border (default: transparent)
+  rightBg: string            Right bubble background (default: #f1f5f9)
+  rightBorder: string        Right bubble border (default: transparent)
+  tabInactiveColor: string   Inactive tab text (default: #94a3b8)
+  annotationText: string     Annotation text (default: #475569)
+  annotationBorder: string   Annotation accent bar (default: #cbd5e1)
+`;
+  }
+  if (section === "speed") {
+    return `
+SPEED OPTIONS (meta.speed)
+==========================
+
+All values are in milliseconds.
+
+  minDelay: number           Minimum delay between steps (default: 3000)
+  maxDelay: number           Maximum delay between steps (default: 8000)
+  msPerWord: number          Reading time per word (default: 200)
+  annotationMultiplier: num  Extra time multiplier for annotations (default: 1.15)
+  upNextDelay: number        "Up Next" indicator duration (default: 2500)
+`;
+  }
+  if (section === "steps") {
+    return `
+STEP TYPES
+==========
+
+MESSAGE - A chat bubble from a participant
+  type: message              (required)
+  from: string               Participant ID (required)
+  content: string            Message text (required)
+  codeBlock: string          Optional preformatted code block
+  footnote: string           Optional italic footnote
+
+ANNOTATION - Educational callout with accent bar
+  type: annotation           (required)
+  content: string            Annotation text (required)
+
+TRANSITION - Centered scene break
+  type: transition           (required)
+  content: string            Transition text (required)
+`;
+  }
+  return `
+CONVERSATION REPLAY SCHEMA
+==========================
+
+STRUCTURE
+---------
+meta:                        Demo configuration (see: schema meta)
+scenarios:                   Array of conversation scenarios
+
+SCENARIO
+--------
+  id: string                 Unique identifier (required)
+  title: string              Display title for tab (required)
+  participants: array        People in conversation (required)
+  steps: array               Message/annotation sequence (required)
+
+PARTICIPANT
+-----------
+  id: string                 Unique ID, used in message 'from' field (required)
+  label: string              Display name shown above messages (required)
+  role: string               left | right (default: left)
+
+STEP TYPES
+----------
+  message                    Chat bubble (requires: from, content)
+  annotation                 Educational callout (requires: content)
+  transition                 Scene break (requires: content)
+
+Use 'schema <section>' for details:
+  schema meta                Meta/configuration options
+  schema colors              Color customization
+  schema speed               Timing configuration
+  schema steps               Step type details
+`;
+}
+
 // src/cli.ts
 var HELP = `
 conversation-replay - Create annotated replays of text conversations from YAML
@@ -9398,22 +10008,31 @@ conversation-replay - Create annotated replays of text conversations from YAML
 Usage:
   conversation-replay build <scenario.yaml> -o <output.html> [options]
   conversation-replay validate <scenario.yaml>
-  conversation-replay --help
+  conversation-replay init <output.yaml> [--theme <theme>]
+  conversation-replay schema [section] [--json]
+  conversation-replay info
+  conversation-replay --help | --version
 
 Commands:
   build      Generate HTML from a scenario file
   validate   Check a scenario file for errors
+  init       Create a starter YAML template with documentation
+  schema     Show schema reference (sections: meta, colors, speed, steps)
+  info       Show tool name, version, author, and links
 
 Options:
   -o, --output <path>   Output HTML file path (required for build)
   --theme <theme>       Override theme (chat, email, slack, terminal, generic)
   --no-header           Exclude the demo header
+  --json                Output JSON schema (for schema command)
   -h, --help            Show this help message
+  -v, --version         Show version number
 
 Examples:
   conversation-replay build demo.yaml -o demo.html
-  conversation-replay build demo.yaml -o demo.html --theme email
-  conversation-replay validate demo.yaml
+  conversation-replay init my-demo.yaml
+  conversation-replay schema meta
+  conversation-replay info
 `;
 var VALID_THEMES2 = ["chat", "email", "slack", "terminal", "generic"];
 async function main() {
@@ -9423,18 +10042,32 @@ async function main() {
       output: { type: "string", short: "o" },
       theme: { type: "string" },
       "no-header": { type: "boolean" },
-      help: { type: "boolean", short: "h" }
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" }
     },
     allowPositionals: true
   });
+  if (values.version) {
+    console.log(`conversation-replay v${package_default.version}`);
+    process.exit(0);
+  }
   if (values.help || positionals.length === 0) {
     console.log(HELP);
     process.exit(0);
   }
   const command = positionals[0];
-  const inputFile = positionals[1];
-  if (!inputFile) {
-    console.error(`Error: No input file specified
+  const arg1 = positionals[1];
+  if (command === "schema") {
+    handleSchema(arg1, values.json);
+    process.exit(0);
+  }
+  if (command === "info") {
+    handleInfo();
+    process.exit(0);
+  }
+  if (!arg1) {
+    console.error(`Error: No file specified
 `);
     console.log(HELP);
     process.exit(1);
@@ -9447,10 +10080,13 @@ async function main() {
   try {
     switch (command) {
       case "build":
-        await handleBuild(inputFile, values);
+        await handleBuild(arg1, values);
         break;
       case "validate":
-        await handleValidate(inputFile);
+        await handleValidate(arg1);
+        break;
+      case "init":
+        await handleInit(arg1, values.theme);
         break;
       default:
         console.error(`Error: Unknown command "${command}"
@@ -9523,6 +10159,41 @@ async function handleValidate(inputFile) {
       console.log(`      - Transitions: ${counts.transition}`);
   }
 }
+async function handleInit(outputFile, theme) {
+  const fs = await import("fs/promises");
+  try {
+    await fs.access(outputFile);
+    console.error(`Error: File already exists: ${outputFile}`);
+    console.error("Use a different filename or delete the existing file.");
+    process.exit(1);
+  } catch {}
+  const template = generateTemplate(theme);
+  await fs.writeFile(outputFile, template, "utf-8");
+  console.log(`Created ${outputFile}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  1. Edit ${outputFile} to define your conversation`);
+  console.log(`  2. Validate: conversation-replay validate ${outputFile}`);
+  console.log(`  3. Build: conversation-replay build ${outputFile} -o output.html`);
+  console.log("");
+  console.log("For schema reference: conversation-replay schema");
+}
+function handleInfo() {
+  console.log(`
+Conversation Replay v${package_default.version}
+https://github.com/lennyzeltser/conversation-replay
+
+Created by Lenny Zeltser
+https://zeltser.com
+`.trim());
+}
+function handleSchema(section, outputJson) {
+  if (outputJson) {
+    console.log(JSON.stringify(jsonSchema, null, 2));
+    return;
+  }
+  console.log(getSchemaReference(section));
+}
 main().catch((error) => {
   console.error("Unexpected error:", error);
   process.exit(1);