@hustle-together/api-dev-tools 2.0.4 → 2.0.6

package/demo/audio/narration-timing.sample.json

@@ -0,0 +1,48 @@
+{
+  "generated": "2025-12-08T00:00:00.000Z",
+  "duration": 300,
+  "wordCount": 850,
+  "sections": [
+    { "id": "intro", "timestamp": 0 },
+    { "id": "problems", "timestamp": 35 },
+    { "id": "solution", "timestamp": 95 },
+    { "id": "workflow", "timestamp": 140 },
+    { "id": "installation", "timestamp": 220 },
+    { "id": "credits", "timestamp": 260 },
+    { "id": "outro", "timestamp": 285 }
+  ],
+  "highlights": [
+    { "selector": "#hustleBrand", "section": "intro", "timestamp": 2 },
+    { "selector": "[data-phase='research']", "section": "intro", "timestamp": 8 },
+    { "selector": "[data-phase='interview']", "section": "intro", "timestamp": 14 },
+    { "selector": "[data-phase='test']", "section": "intro", "timestamp": 20 },
+    { "selector": "[data-phase='code']", "section": "intro", "timestamp": 26 },
+    { "selector": "[data-phase='docs']", "section": "intro", "timestamp": 32 },
+    { "selector": "#problems h2", "section": "problems", "timestamp": 36 },
+    { "selector": ".gap-item:nth-child(1)", "section": "problems", "timestamp": 42 },
+    { "selector": ".gap-item:nth-child(2)", "section": "problems", "timestamp": 54 },
+    { "selector": ".gap-item:nth-child(3)", "section": "problems", "timestamp": 66 },
+    { "selector": ".gap-item:nth-child(4)", "section": "problems", "timestamp": 78 },
+    { "selector": ".gap-item:nth-child(5)", "section": "problems", "timestamp": 88 },
+    { "selector": "#solution h2", "section": "solution", "timestamp": 96 },
+    { "selector": ".hook-box:nth-child(1)", "section": "solution", "timestamp": 104 },
+    { "selector": ".hook-box:nth-child(2)", "section": "solution", "timestamp": 118 },
+    { "selector": ".hook-box:nth-child(3)", "section": "solution", "timestamp": 130 },
+    { "selector": "#workflow h2", "section": "workflow", "timestamp": 141 },
+    { "selector": ".workflow-phase:nth-child(1)", "section": "workflow", "timestamp": 148 },
+    { "selector": ".workflow-phase:nth-child(2)", "section": "workflow", "timestamp": 155 },
+    { "selector": ".workflow-phase:nth-child(3)", "section": "workflow", "timestamp": 162 },
+    { "selector": ".workflow-phase:nth-child(4)", "section": "workflow", "timestamp": 172 },
+    { "selector": ".workflow-phase:nth-child(5)", "section": "workflow", "timestamp": 180 },
+    { "selector": ".workflow-phase:nth-child(6)", "section": "workflow", "timestamp": 188 },
+    { "selector": ".workflow-phase:nth-child(7)", "section": "workflow", "timestamp": 196 },
+    { "selector": ".workflow-phase:nth-child(8)", "section": "workflow", "timestamp": 204 },
+    { "selector": ".workflow-phase:nth-child(9)", "section": "workflow", "timestamp": 211 },
+    { "selector": ".workflow-phase:nth-child(10)", "section": "workflow", "timestamp": 218 },
+    { "selector": "#installation h2", "section": "installation", "timestamp": 221 },
+    { "selector": ".install-command", "section": "installation", "timestamp": 228 },
+    { "selector": "#credits h2", "section": "credits", "timestamp": 261 },
+    { "selector": "#intro", "section": "outro", "timestamp": 286 }
+  ],
+  "words": []
+}

package/demo/workflow-demo.html

@@ -500,6 +500,95 @@
       box-shadow: 0 0 15px var(--accent-red-glow);
     }
 
+    .nav-btn.active {
+      background: var(--accent-red);
+      color: #fff;
+      border-color: var(--accent-red);
+    }
+
+    .nav-btn.disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+      text-decoration: line-through;
+    }
+
+    .nav-btn.disabled:hover {
+      background: transparent;
+      color: var(--grey);
+      border-color: var(--grey);
+      box-shadow: none;
+    }
+
+    /* ============================================
+       AUDIO NARRATION PLAYER
+       ============================================ */
+    .audio-progress-container {
+      position: fixed;
+      bottom: 60px;
+      left: 50%;
+      transform: translateX(-50%);
+      width: 80%;
+      max-width: 600px;
+      background: rgba(0, 0, 0, 0.9);
+      border: 1px dashed var(--grey);
+      padding: 15px 20px;
+      z-index: 1001;
+      border-radius: 0;
+    }
+
+    .audio-time-display {
+      display: flex;
+      justify-content: space-between;
+      font-size: 0.75rem;
+      color: var(--grey);
+      margin-bottom: 10px;
+      font-family: 'Courier New', monospace;
+    }
+
+    .audio-progress-bar {
+      position: relative;
+      height: 6px;
+      background: var(--dark-grey);
+      cursor: pointer;
+    }
+
+    .audio-progress-fill {
+      height: 100%;
+      background: var(--accent-red);
+      width: 0%;
+      transition: width 0.1s linear;
+    }
+
+    .audio-section-markers {
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      pointer-events: none;
+    }
+
+    .audio-section-marker {
+      position: absolute;
+      top: -3px;
+      width: 2px;
+      height: 12px;
+      background: var(--white);
+      opacity: 0.5;
+    }
+
+    .audio-section-marker:hover {
+      opacity: 1;
+    }
+
+    /* Audio highlight effect for elements being narrated */
+    .audio-highlighted {
+      box-shadow: 0 0 30px var(--accent-red-glow), 0 0 60px var(--accent-red-glow) !important;
+      border-color: var(--accent-red) !important;
+      transform: scale(1.02);
+      transition: all 0.3s ease !important;
+    }
+
     /* Progress indicator */
     .progress-bar {
       position: fixed;
@@ -1589,10 +1678,28 @@
 
   <!-- Navigation -->
   <nav class="nav">
-    <button class="nav-btn" id="playBtn">AUTO PLAY</button>
-    <button class="nav-btn" id="resetBtn">RESTART</button>
+    <button class="nav-btn" id="playBtn">▶ AUTO PLAY</button>
+    <button class="nav-btn" id="audioToggleBtn" title="Toggle narration audio">🔊 WITH AUDIO</button>
+    <button class="nav-btn" id="resetBtn">↺ RESTART</button>
   </nav>
 
+  <!-- Audio Narration Player (hidden) -->
+  <audio id="narrationAudio" preload="auto">
+    <source src="audio/narration.mp3" type="audio/mpeg">
+  </audio>
+
+  <!-- Audio Progress Bar -->
+  <div class="audio-progress-container" id="audioProgressContainer" style="display: none;">
+    <div class="audio-time-display">
+      <span id="audioCurrentTime">0:00</span>
+      <span id="audioTotalTime">0:00</span>
+    </div>
+    <div class="audio-progress-bar" id="audioProgressBar">
+      <div class="audio-progress-fill" id="audioProgressFill"></div>
+      <div class="audio-section-markers" id="audioSectionMarkers"></div>
+    </div>
+  </div>
+
   <!-- Section Indicators -->
   <div class="section-indicator" id="sectionIndicator"></div>
 
@@ -1606,7 +1713,7 @@
         <span class="hustle-word hustle-highlight">API-DEV-TOOLS</span>
       </div>
       <div class="package-name" id="packageName">@hustle-together/api-dev-tools</div>
-      <div class="version" id="versionText">v2.0.4</div>
+      <div class="version" id="versionText">v2.0.6</div>
       <p class="tagline">"Hustle together. Share resources. Build stronger."<span class="cursor"></span></p>
 
       <div class="intro-text">
@@ -2664,32 +2771,272 @@
       .to('.made-with', { opacity: 1, duration: 0.5 });
 
     // ============================================
-    // AUTO-PLAY BUTTON
+    // UNIFIED AUTO-PLAY + AUDIO SYSTEM
     // ============================================
-    document.getElementById('playBtn').addEventListener('click', () => {
-      if (!isPlaying) {
-        isPlaying = true;
-        document.getElementById('playBtn').textContent = 'PLAYING...';
-        document.getElementById('playBtn').style.background = 'var(--white)';
-        document.getElementById('playBtn').style.color = 'var(--black)';
-
-        let currentSection = 0;
-        const autoScroll = setInterval(() => {
-          if (currentSection < sections.length) {
-            document.getElementById(sections[currentSection]).scrollIntoView({
-              behavior: 'smooth'
-            });
-            currentSection++;
-          } else {
-            clearInterval(autoScroll);
-            isPlaying = false;
-            document.getElementById('playBtn').textContent = 'AUTO PLAY';
-            document.getElementById('playBtn').style.background = 'transparent';
-            document.getElementById('playBtn').style.color = 'var(--white)';
+    const playBtn = document.getElementById('playBtn');
+    const audioToggleBtn = document.getElementById('audioToggleBtn');
+    const narrationAudio = document.getElementById('narrationAudio');
+    const audioProgressContainer = document.getElementById('audioProgressContainer');
+    const audioProgressBar = document.getElementById('audioProgressBar');
+    const audioProgressFill = document.getElementById('audioProgressFill');
+    const audioCurrentTime = document.getElementById('audioCurrentTime');
+    const audioTotalTime = document.getElementById('audioTotalTime');
+    const audioSectionMarkers = document.getElementById('audioSectionMarkers');
+
+    let audioEnabled = true; // Audio on by default
+    let timingData = null;
+    let currentHighlight = null;
+    let highlightIndex = 0;
+    let currentSectionIdx = 0;
+    let autoPlayInterval = null;
+
+    // Format seconds to MM:SS
+    function formatTime(seconds) {
+      const mins = Math.floor(seconds / 60);
+      const secs = Math.floor(seconds % 60);
+      return `${mins}:${secs.toString().padStart(2, '0')}`;
+    }
+
+    // Load timing data
+    async function loadTimingData() {
+      if (timingData) return timingData;
+      try {
+        const response = await fetch('audio/narration-timing.json');
+        if (!response.ok) throw new Error('Failed to load timing data');
+        timingData = await response.json();
+
+        // Update total time display
+        if (audioTotalTime) {
+          audioTotalTime.textContent = formatTime(timingData.duration);
+        }
+
+        // Create section markers on progress bar
+        if (audioSectionMarkers && timingData.sections) {
+          audioSectionMarkers.innerHTML = '';
+          timingData.sections.forEach((section, i) => {
+            if (i === 0) return;
+            const marker = document.createElement('div');
+            marker.className = 'audio-section-marker';
+            marker.style.left = `${(section.timestamp / timingData.duration) * 100}%`;
+            marker.title = section.id.toUpperCase();
+            audioSectionMarkers.appendChild(marker);
+          });
+        }
+
+        console.log('Timing data loaded:', timingData.sections.length, 'sections,', timingData.highlights.length, 'highlights');
+        return timingData;
+      } catch (error) {
+        console.error('Failed to load timing data:', error);
+        return null;
+      }
+    }
+
+    // Apply highlight to an element
+    function applyHighlight(selector) {
+      removeHighlight();
+      try {
+        const el = document.querySelector(selector);
+        if (el) {
+          currentHighlight = el;
+          el.classList.add('audio-highlighted');
+          el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          gsap.fromTo(el,
+            { boxShadow: '0 0 0px var(--accent-red-glow)' },
+            { boxShadow: '0 0 40px var(--accent-red-glow), 0 0 80px var(--accent-red-glow)', duration: 0.4, ease: 'power2.out' }
+          );
+        }
+      } catch (e) {
+        console.warn('Could not highlight:', selector, e);
+      }
+    }
+
+    // Remove current highlight
+    function removeHighlight() {
+      if (currentHighlight) {
+        currentHighlight.classList.remove('audio-highlighted');
+        gsap.to(currentHighlight, { boxShadow: 'none', duration: 0.3 });
+        currentHighlight = null;
+      }
+    }
+
+    // Handle audio time update (syncs highlights with narration)
+    function onAudioTimeUpdate() {
+      if (!timingData || !audioEnabled) return;
+
+      const currentTime = narrationAudio.currentTime;
+
+      // Update progress bar
+      const progress = (currentTime / timingData.duration) * 100;
+      audioProgressFill.style.width = `${progress}%`;
+
+      // Update time display
+      if (audioCurrentTime) {
+        audioCurrentTime.textContent = formatTime(currentTime);
+      }
+
+      // Check for highlight triggers
+      for (let i = highlightIndex; i < timingData.highlights.length; i++) {
+        const highlight = timingData.highlights[i];
+        if (currentTime >= highlight.timestamp) {
+          if (i !== highlightIndex || !currentHighlight) {
+            highlightIndex = i;
+            applyHighlight(highlight.selector);
           }
-        }, 5000);
+        } else {
+          break;
+        }
+      }
+    }
+
+    // Handle seek on progress bar click
+    function onProgressBarClick(e) {
+      if (!timingData || !narrationAudio.duration) return;
+
+      const rect = audioProgressBar.getBoundingClientRect();
+      const clickX = e.clientX - rect.left;
+      const percentage = clickX / rect.width;
+      const seekTime = percentage * timingData.duration;
+
+      narrationAudio.currentTime = seekTime;
+
+      // Reset highlight tracking
+      highlightIndex = 0;
+      for (let i = 0; i < timingData.highlights.length; i++) {
+        if (timingData.highlights[i].timestamp <= seekTime) {
+          highlightIndex = i;
+        } else {
+          break;
+        }
+      }
+    }
+
+    // Silent auto-play (no audio, timed sections)
+    function startSilentAutoPlay() {
+      let sectionIdx = 0;
+      autoPlayInterval = setInterval(() => {
+        if (sectionIdx < sections.length) {
+          document.getElementById(sections[sectionIdx]).scrollIntoView({ behavior: 'smooth' });
+          sectionIdx++;
+        } else {
+          stopAutoPlay();
+        }
+      }, 5000);
+    }
+
+    // Start auto-play
+    async function startAutoPlay() {
+      if (isPlaying) return;
+
+      isPlaying = true;
+      playBtn.classList.add('active');
+      playBtn.textContent = '⏸ STOP';
+
+      // Scroll to top first
+      window.scrollTo({ top: 0, behavior: 'smooth' });
+
+      await loadTimingData();
+
+      if (audioEnabled && timingData) {
+        // Try to play audio
+        audioProgressContainer.style.display = 'block';
+
+        try {
+          await narrationAudio.play();
+          console.log('Audio playing');
+        } catch (err) {
+          console.error('Audio playback failed:', err);
+          // Fall back to silent mode
+          audioEnabled = false;
+          audioToggleBtn.textContent = '🔇 NO AUDIO';
+          audioToggleBtn.classList.add('disabled');
+          audioProgressContainer.style.display = 'none';
+          startSilentAutoPlay();
+        }
+      } else {
+        // Silent auto-play
+        startSilentAutoPlay();
+      }
+    }
+
+    // Stop auto-play
+    function stopAutoPlay() {
+      isPlaying = false;
+      playBtn.classList.remove('active');
+      playBtn.textContent = '▶ AUTO PLAY';
+
+      if (autoPlayInterval) {
+        clearInterval(autoPlayInterval);
+        autoPlayInterval = null;
+      }
+
+      narrationAudio.pause();
+      narrationAudio.currentTime = 0;
+      audioProgressContainer.style.display = 'none';
+      removeHighlight();
+      highlightIndex = 0;
+      currentSectionIdx = 0;
+    }
+
+    // Audio ended
+    function onAudioEnded() {
+      stopAutoPlay();
+      setTimeout(() => {
+        window.scrollTo({ top: 0, behavior: 'smooth' });
+      }, 500);
+    }
+
+    // Toggle audio on/off
+    function toggleAudio() {
+      audioEnabled = !audioEnabled;
+      if (audioEnabled) {
+        audioToggleBtn.textContent = '🔊 WITH AUDIO';
+        audioToggleBtn.classList.remove('disabled');
+      } else {
+        audioToggleBtn.textContent = '🔇 SILENT';
+        audioToggleBtn.classList.add('disabled');
+      }
+
+      // If currently playing, adjust
+      if (isPlaying) {
+        if (audioEnabled) {
+          narrationAudio.play().catch(() => {});
+          audioProgressContainer.style.display = 'block';
+          if (autoPlayInterval) {
+            clearInterval(autoPlayInterval);
+            autoPlayInterval = null;
+          }
+        } else {
+          narrationAudio.pause();
+          audioProgressContainer.style.display = 'none';
+          startSilentAutoPlay();
+        }
+      }
+    }
+
+    // Event listeners
+    playBtn.addEventListener('click', () => {
+      if (isPlaying) {
+        stopAutoPlay();
+      } else {
+        startAutoPlay();
       }
     });
+    audioToggleBtn.addEventListener('click', toggleAudio);
+    narrationAudio.addEventListener('timeupdate', onAudioTimeUpdate);
+    narrationAudio.addEventListener('ended', onAudioEnded);
+    audioProgressBar.addEventListener('click', onProgressBarClick);
+
+    // Check if audio file is accessible
+    narrationAudio.addEventListener('error', (e) => {
+      console.error('Audio error:', e);
+      audioEnabled = false;
+      audioToggleBtn.textContent = '🔇 NO AUDIO';
+      audioToggleBtn.classList.add('disabled');
+      audioToggleBtn.title = 'Audio file not accessible (run from a web server)';
+    });
+
+    // Preload timing data
+    loadTimingData();
 
     // ============================================
     // RESET BUTTON
@@ -2889,6 +3236,7 @@
         }
       });
     });
+
   </script>
 
 </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Interview-driven API development workflow for Claude Code - Automates research, testing, and documentation",
   "main": "bin/cli.js",
   "bin": {