executable-stories-formatters 0.7.4 → 0.7.5

package/dist/cli.js

@@ -1529,6 +1529,7 @@ function applyAllFilters() {
   });
 
   updateFilterResults(visibleCount, totalCount);
+  syncTocVisibility();
   writeUrlState();
 }
 
@@ -1545,13 +1546,135 @@ function updateFilterResults(visible, total) {
   if (tc) tc.textContent = total;
 }
 
-// Keyboard shortcuts
+// Keyboard navigation
+var focusedScenarioIndex = -1;
+
+function getVisibleScenarios() {
+  return Array.from(document.querySelectorAll('.scenario')).filter(function(s) {
+    return s.style.display !== 'none' && s.closest('.feature').style.display !== 'none';
+  });
+}
+
+function focusScenario(index) {
+  var scenarios = getVisibleScenarios();
+  if (scenarios.length === 0) return;
+
+  // Remove previous focus
+  var prev = document.querySelector('.scenario-focused');
+  if (prev) prev.classList.remove('scenario-focused');
+
+  // Wrap around
+  if (index < 0) index = scenarios.length - 1;
+  if (index >= scenarios.length) index = 0;
+  focusedScenarioIndex = index;
+
+  var scenario = scenarios[index];
+  scenario.classList.add('scenario-focused');
+  scenario.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+}
+
+function showShortcutsOverlay() {
+  if (document.querySelector('.shortcuts-overlay')) return;
+  var overlay = document.createElement('div');
+  overlay.className = 'shortcuts-overlay';
+  overlay.innerHTML = '<div class="shortcuts-modal">' +
+    '<div class="shortcuts-title">Keyboard Shortcuts</div>' +
+    '<div class="shortcuts-grid">' +
+    '<kbd>j</kbd><span>Next scenario</span>' +
+    '<kbd>k</kbd><span>Previous scenario</span>' +
+    '<kbd>Enter</kbd><span>Expand/collapse scenario</span>' +
+    '<kbd>Escape</kbd><span>Collapse scenario / close</span>' +
+    '<kbd>/</kbd><span>Focus search</span>' +
+    '<kbd>?</kbd><span>Toggle this help</span>' +
+    '<kbd>e</kbd><span>Expand all</span>' +
+    '<kbd>c</kbd><span>Collapse all</span>' +
+    '<kbd>t</kbd><span>Toggle table of contents</span>' +
+    '</div></div>';
+  overlay.addEventListener('click', function(ev) {
+    if (ev.target === overlay) hideShortcutsOverlay();
+  });
+  document.body.appendChild(overlay);
+}
+
+function hideShortcutsOverlay() {
+  var overlay = document.querySelector('.shortcuts-overlay');
+  if (overlay) overlay.remove();
+}
+
 function initKeyboardShortcuts() {
   document.addEventListener('keydown', function(e) {
-    if (e.key === '/' && !e.ctrlKey && !e.metaKey && e.target.tagName !== 'INPUT') {
-      e.preventDefault();
-      var input = document.querySelector('.search-input');
-      if (input) input.focus();
+    var tag = e.target.tagName;
+    if (tag === 'INPUT' || tag === 'SELECT' || tag === 'TEXTAREA') {
+      if (e.key === 'Escape') {
+        e.target.blur();
+        if (e.target.classList.contains('search-input')) {
+          e.target.value = '';
+          applyAllFilters();
+        }
+      }
+      return;
+    }
+
+    if (e.ctrlKey || e.metaKey || e.altKey) return;
+
+    switch (e.key) {
+      case 'j':
+        e.preventDefault();
+        focusScenario(focusedScenarioIndex + 1);
+        break;
+      case 'k':
+        e.preventDefault();
+        focusScenario(focusedScenarioIndex - 1);
+        break;
+      case 'Enter':
+        e.preventDefault();
+        var scenarios = getVisibleScenarios();
+        if (focusedScenarioIndex >= 0 && focusedScenarioIndex < scenarios.length) {
+          var s = scenarios[focusedScenarioIndex];
+          var h = s.querySelector('.scenario-header');
+          if (h) toggleCollapse(h, s);
+        }
+        break;
+      case 'Escape':
+        if (document.querySelector('.shortcuts-overlay')) {
+          hideShortcutsOverlay();
+        } else {
+          var scenarios2 = getVisibleScenarios();
+          if (focusedScenarioIndex >= 0 && focusedScenarioIndex < scenarios2.length) {
+            var sc = scenarios2[focusedScenarioIndex];
+            if (!sc.classList.contains('collapsed')) {
+              sc.classList.add('collapsed');
+              var sh = sc.querySelector('.scenario-header');
+              if (sh) sh.setAttribute('aria-expanded', 'false');
+            }
+          }
+        }
+        break;
+      case '/':
+        e.preventDefault();
+        var input = document.querySelector('.search-input');
+        if (input) input.focus();
+        break;
+      case '?':
+        e.preventDefault();
+        if (document.querySelector('.shortcuts-overlay')) {
+          hideShortcutsOverlay();
+        } else {
+          showShortcutsOverlay();
+        }
+        break;
+      case 'e':
+        e.preventDefault();
+        expandAll();
+        break;
+      case 'c':
+        e.preventDefault();
+        collapseAll();
+        break;
+      case 't':
+        e.preventDefault();
+        if (typeof toggleToc === 'function') toggleToc();
+        break;
     }
   });
 }
@@ -1689,6 +1812,189 @@ function writeUrlState() {
   var url = window.location.pathname + (qs ? '?' + qs : '');
   history.replaceState(null, '', url);
 }
+
+// Permalink copy
+function copyPermalink(anchorId) {
+  var url = location.origin + location.pathname + location.search + '#' + anchorId;
+  navigator.clipboard.writeText(url).then(function() {
+    var el = document.getElementById(anchorId);
+    if (el) showCopyToast(el);
+  });
+}
+
+function showCopyToast(el) {
+  var existing = el.querySelector('.copy-toast');
+  if (existing) existing.remove();
+  var toast = document.createElement('span');
+  toast.className = 'copy-toast';
+  toast.textContent = 'Copied!';
+  var header = el.querySelector('.feature-header, .scenario-header');
+  if (header) {
+    header.style.position = 'relative';
+    header.appendChild(toast);
+  }
+  setTimeout(function() { toast.remove(); }, 1500);
+}
+
+// Copy scenario as markdown
+function copyScenarioAsMarkdown(scenarioId) {
+  var scenario = document.getElementById(scenarioId);
+  if (!scenario) return;
+
+  var title = (scenario.querySelector('.scenario-name') || {}).textContent || '';
+  var steps = scenario.querySelectorAll('.step, .step.continuation');
+  var lines = ['### Scenario: ' + title.trim(), ''];
+
+  steps.forEach(function(step) {
+    var keyword = step.getAttribute('data-keyword') || '';
+    var text = step.getAttribute('data-text') || '';
+    lines.push('- **' + keyword + '** ' + text);
+  });
+
+  var errorBox = scenario.querySelector('.error-message');
+  if (errorBox) {
+    var errorText = errorBox.textContent || '';
+    lines.push('');
+    lines.push('> **Error:** ' + errorText.trim());
+  }
+
+  var md = lines.join('\\n');
+  navigator.clipboard.writeText(md).then(function() {
+    showCopyToast(scenario);
+  });
+}
+
+// Hash scroll on load
+function initHashScroll() {
+  if (!location.hash) return;
+  var target = document.querySelector(location.hash);
+  if (!target) return;
+  var feature = target.closest('.feature');
+  if (feature && feature.classList.contains('collapsed')) {
+    feature.classList.remove('collapsed');
+    var fh = feature.querySelector('.feature-header');
+    if (fh) fh.setAttribute('aria-expanded', 'true');
+  }
+  if (target.classList.contains('collapsed')) {
+    target.classList.remove('collapsed');
+    var sh = target.querySelector('.scenario-header');
+    if (sh) sh.setAttribute('aria-expanded', 'true');
+  }
+  setTimeout(function() {
+    target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    target.classList.add('hash-highlight');
+  }, 100);
+}
+
+// Table of contents
+function toggleToc() {
+  var sidebar = document.querySelector('.toc-sidebar');
+  var wrapper = document.querySelector('.report-layout');
+  if (!sidebar || !wrapper) return;
+  var isMobile = window.matchMedia('(max-width: 767px)').matches;
+  if (isMobile) {
+    sidebar.classList.toggle('toc-mobile-open');
+  } else {
+    wrapper.classList.toggle('toc-hidden');
+    var hidden = wrapper.classList.contains('toc-hidden');
+    localStorage.setItem('toc-visible', String(!hidden));
+  }
+}
+
+function initToc() {
+  var sidebar = document.querySelector('.toc-sidebar');
+  if (!sidebar) return;
+
+  var saved = localStorage.getItem('toc-visible');
+  var wrapper = document.querySelector('.report-layout');
+  if (saved === 'false' && wrapper) {
+    wrapper.classList.add('toc-hidden');
+  }
+
+  // Active tracking via IntersectionObserver
+  var observer = new IntersectionObserver(function(entries) {
+    entries.forEach(function(entry) {
+      if (entry.isIntersecting) {
+        var id = entry.target.id;
+        if (!id) return;
+        document.querySelectorAll('.toc-scenario, .toc-feature-toggle').forEach(function(el) {
+          el.classList.remove('toc-active');
+        });
+        var tocLink = sidebar.querySelector('a[href="#' + id + '"]');
+        if (tocLink) tocLink.classList.add('toc-active');
+      }
+    });
+  }, { rootMargin: '-10% 0px -80% 0px' });
+
+  document.querySelectorAll('.feature, .scenario').forEach(function(el) {
+    if (el.id) observer.observe(el);
+  });
+
+  // Click navigation: expand collapsed parents
+  sidebar.querySelectorAll('.toc-scenario').forEach(function(link) {
+    link.addEventListener('click', function(e) {
+      var hash = link.getAttribute('href');
+      if (!hash) return;
+      var target = document.querySelector(hash);
+      if (!target) return;
+      var feature = target.closest('.feature');
+      if (feature && feature.classList.contains('collapsed')) {
+        feature.classList.remove('collapsed');
+        var fh = feature.querySelector('.feature-header');
+        if (fh) fh.setAttribute('aria-expanded', 'true');
+      }
+      if (target.classList.contains('collapsed')) {
+        target.classList.remove('collapsed');
+        var sh = target.querySelector('.scenario-header');
+        if (sh) sh.setAttribute('aria-expanded', 'true');
+      }
+    });
+  });
+}
+
+// Theme picker
+function initThemePicker() {
+  var picker = document.querySelector('.theme-picker');
+  if (!picker) return;
+
+  var saved = localStorage.getItem('report-theme');
+  if (saved) {
+    picker.value = saved;
+    switchReportTheme(saved);
+  }
+
+  picker.addEventListener('change', function(e) {
+    switchReportTheme(e.target.value);
+    localStorage.setItem('report-theme', e.target.value);
+  });
+}
+
+function switchReportTheme(name) {
+  document.querySelectorAll('style[data-theme-name]').forEach(function(s) {
+    s.disabled = s.dataset.themeName !== name;
+  });
+}
+
+// Sync TOC visibility with filters
+function syncTocVisibility() {
+  var sidebar = document.querySelector('.toc-sidebar');
+  if (!sidebar) return;
+
+  sidebar.querySelectorAll('.toc-scenario').forEach(function(link) {
+    var href = link.getAttribute('href');
+    if (!href) return;
+    var target = document.querySelector(href);
+    link.style.display = (target && target.style.display !== 'none') ? '' : 'none';
+  });
+
+  sidebar.querySelectorAll('.toc-feature').forEach(function(feature) {
+    var visibleScenarios = feature.querySelectorAll('.toc-scenario');
+    var anyVisible = Array.from(visibleScenarios).some(function(s) {
+      return s.style.display !== 'none';
+    });
+    feature.style.display = anyVisible ? '' : 'none';
+  });
+}
 `;
 var JS_MARKDOWN_FN = `
 function parseMarkdownSections(marked) {
@@ -1729,6 +2035,9 @@ function generateScript(options) {
   initCalls.push("initCollapse();");
   initCalls.push("initDetailLevel();");
   initCalls.push("applyAllFilters();");
+  initCalls.push("initHashScroll();");
+  initCalls.push("initToc();");
+  initCalls.push("initThemePicker();");
   const initScript = `
 // Initialize on load
 document.addEventListener('DOMContentLoaded', () => {
@@ -1790,6 +2099,7 @@ function generateHtmlTemplate(title, styles, body, options = {}) {
   }
   const cdnStylesHtml = cdnStyles.length > 0 ? "\n  " + cdnStyles.join("\n  ") : "";
   const esmScriptHtml = generateEsmScript(options);
+  const additionalThemeStyles = (options.additionalThemeCss ?? []).map((t) => `<style data-theme-name="${escapeHtml(t.name)}" disabled>${t.css}</style>`).join("\n  ");
   return `<!DOCTYPE html>
 <html lang="en"${themeAttr} data-detail-level="full">
 <head>
@@ -1797,19 +2107,27 @@ function generateHtmlTemplate(title, styles, body, options = {}) {
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <meta name="color-scheme" content="light dark">
   <title>${escapeHtml(title)}</title>${cdnStylesHtml}
-  <style>${styles}</style>
+  <style${options.additionalThemeCss ? ` data-theme-name="${escapeHtml(options.activeThemeName ?? "default")}"` : ""}>${styles}</style>
+  ${additionalThemeStyles}
 </head>
 <body>
-  <div class="container">
-    <header class="header">
-      <h1>${escapeHtml(title)}</h1>
-      <div class="header-actions">
-        ${includeSearch ? '<input type="text" class="search-input" placeholder="Search scenarios..." aria-label="Search scenarios">' : ""}
-        <button type="button" class="detail-toggle" onclick="toggleDetailLevel()" aria-label="Toggle detail level" title="Toggle documentation detail"></button>
-        ${includeDarkMode ? '<button type="button" class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme"></button>' : ""}
+  <div class="report-layout">
+    ${options.tocHtml ?? ""}
+    <div class="main-content">
+      <div class="container">
+        <header class="header">
+          <h1>${escapeHtml(title)}</h1>
+          <div class="header-actions">
+            <button type="button" class="toc-toggle" onclick="toggleToc()" aria-label="Toggle table of contents" title="Toggle contents">&#x2630;</button>
+            ${includeSearch ? '<input type="text" class="search-input" placeholder="Search scenarios..." aria-label="Search scenarios">' : ""}
+            <button type="button" class="detail-toggle" onclick="toggleDetailLevel()" aria-label="Toggle detail level" title="Toggle documentation detail"></button>
+            ${options.themePickerHtml ?? ""}
+            ${includeDarkMode ? '<button type="button" class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme"></button>' : ""}
+          </div>
+        </header>
+        ${body}
       </div>
-    </header>
-    ${body}
+    </div>
   </div>
   <script>${script}</script>${esmScriptHtml}
 </body>
@@ -3513,6 +3831,331 @@ body {
   display: none;
 }
 
+/* ============================================================================
+   Permalink Anchors
+   ============================================================================ */
+.permalink-anchor {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border: none;
+  background: none;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.15s ease;
+  font-size: 0.875rem;
+  font-weight: 600;
+  padding: 0;
+  flex-shrink: 0;
+}
+
+.feature-header:hover .permalink-anchor,
+.scenario-header:hover .permalink-anchor,
+.permalink-anchor:focus-visible {
+  opacity: 1;
+}
+
+.permalink-anchor:hover {
+  color: var(--primary);
+}
+
+.copy-toast {
+  position: absolute;
+  right: 0.5rem;
+  top: 50%;
+  transform: translateY(-50%);
+  background: var(--foreground);
+  color: var(--background);
+  padding: 0.25rem 0.5rem;
+  border-radius: var(--radius);
+  font-size: 0.75rem;
+  font-weight: 500;
+  pointer-events: none;
+  animation: fadeOut 1.5s ease forwards;
+  z-index: 10;
+}
+
+@keyframes fadeOut {
+  0%, 70% { opacity: 1; }
+  100% { opacity: 0; }
+}
+
+.hash-highlight {
+  animation: hashPulse 2s ease;
+}
+
+@keyframes hashPulse {
+  0%, 100% { background: transparent; }
+  20% { background: color-mix(in srgb, var(--primary) 12%, transparent); }
+}
+
+.scenario-actions {
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
+  flex-shrink: 0;
+}
+
+.copy-scenario-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.5rem;
+  height: 1.5rem;
+  border: none;
+  background: none;
+  color: var(--muted-foreground);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.15s ease;
+  font-size: 0.875rem;
+  padding: 0;
+  flex-shrink: 0;
+}
+
+.scenario-header:hover .copy-scenario-btn,
+.copy-scenario-btn:focus-visible {
+  opacity: 1;
+}
+
+.copy-scenario-btn:hover {
+  color: var(--primary);
+}
+
+/* ============================================================================
+   Keyboard Navigation
+   ============================================================================ */
+.scenario-focused {
+  border-left: 2px solid var(--primary);
+}
+
+.shortcuts-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgb(0 0 0 / 0.5);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 100;
+}
+
+.shortcuts-modal {
+  background: var(--card);
+  color: var(--card-foreground);
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) * 2);
+  padding: 1.5rem 2rem;
+  max-width: 400px;
+  width: 90vw;
+  box-shadow: var(--shadow-md, 0 4px 12px rgb(0 0 0 / 0.15));
+}
+
+.shortcuts-title {
+  font-weight: 600;
+  font-size: 1.125rem;
+  margin-bottom: 1rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--border);
+}
+
+.shortcuts-grid {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 0.5rem 1rem;
+  align-items: center;
+}
+
+.shortcuts-grid kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.75rem;
+  padding: 0.125rem 0.375rem;
+  background: var(--muted);
+  border: 1px solid var(--border);
+  border-radius: calc(var(--radius) * 0.5);
+  font-family: var(--font-mono);
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--muted-foreground);
+}
+
+.shortcuts-grid span {
+  font-size: 0.875rem;
+  color: var(--foreground);
+}
+
+/* ============================================================================
+   Table of Contents Sidebar
+   ============================================================================ */
+.report-layout {
+  display: flex;
+  min-height: 100vh;
+}
+
+.report-layout.toc-hidden .toc-sidebar {
+  display: none;
+}
+
+.main-content {
+  flex: 1;
+  min-width: 0;
+}
+
+.toc-sidebar {
+  width: 260px;
+  flex-shrink: 0;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+  overflow-y: auto;
+  border-right: 1px solid var(--border);
+  background: var(--card);
+  padding: 1rem 0;
+  font-size: 0.8125rem;
+}
+
+.toc-header {
+  padding: 0 1rem 0.75rem;
+  border-bottom: 1px solid var(--border);
+  margin-bottom: 0.5rem;
+}
+
+.toc-title {
+  font-weight: 600;
+  font-size: 0.875rem;
+  color: var(--foreground);
+}
+
+.toc-feature {
+  margin-bottom: 0.25rem;
+}
+
+.toc-feature-toggle {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  padding: 0.375rem 1rem;
+  border: none;
+  background: none;
+  text-align: left;
+  cursor: pointer;
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--foreground);
+  font-family: var(--font-sans);
+}
+
+.toc-feature-toggle:hover {
+  background: var(--accent);
+}
+
+.toc-feature-toggle[aria-expanded="false"] + .toc-scenarios {
+  display: none;
+}
+
+.toc-scenarios {
+  display: flex;
+  flex-direction: column;
+}
+
+.toc-scenario {
+  display: flex;
+  align-items: baseline;
+  gap: 0.375rem;
+  padding: 0.25rem 1rem 0.25rem 1.5rem;
+  color: var(--muted-foreground);
+  text-decoration: none;
+  font-size: 0.8125rem;
+  line-height: 1.4;
+  border-left: 2px solid transparent;
+  transition: all 0.1s ease;
+}
+
+.toc-scenario:hover {
+  color: var(--foreground);
+  background: var(--accent);
+}
+
+.toc-scenario.toc-active {
+  color: var(--foreground);
+  border-left-color: var(--primary);
+  font-weight: 500;
+}
+
+.toc-scenario.toc-failed {
+  border-left-color: var(--error, var(--destructive));
+}
+
+.toc-status {
+  flex-shrink: 0;
+  font-size: 0.75rem;
+}
+
+.toc-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--background);
+  cursor: pointer;
+  color: var(--foreground);
+  font-size: 1rem;
+  transition: all 0.15s ease;
+}
+
+.toc-toggle:hover {
+  background: var(--accent);
+}
+
+/* Mobile: overlay sidebar */
+@media (max-width: 767px) {
+  .toc-sidebar {
+    position: fixed;
+    left: 0;
+    top: 0;
+    z-index: 50;
+    box-shadow: var(--shadow-sm, 0 1px 3px rgb(0 0 0 / 0.1));
+    transform: translateX(-100%);
+    transition: transform 0.2s ease;
+  }
+
+  .toc-sidebar.toc-mobile-open {
+    transform: translateX(0);
+  }
+}
+
+/* ============================================================================
+   Theme Picker
+   ============================================================================ */
+.theme-picker {
+  height: 2.25rem;
+  padding: 0 0.5rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--background);
+  color: var(--foreground);
+  font-size: 0.8125rem;
+  font-family: var(--font-sans);
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.theme-picker:hover {
+  background: var(--accent);
+}
+
+.theme-picker:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
 `;
 
 // src/formatters/html/themes/default.ts
@@ -12769,6 +13412,11 @@ function resolveTheme(nameOrTheme) {
   }
   return theme;
 }
+function getCssOnlyThemes() {
+  return [...THEME_REGISTRY.values()].filter(
+    (theme) => !theme.buildBody && !theme.generateTemplate
+  );
+}
 
 // src/formatters/html/renderers/status.ts
 function getStatusIcon(status) {
@@ -13050,7 +13698,7 @@ function renderStep(step, stepResult, index, deps) {
   const stepClass = isContinuation ? "step continuation" : "step";
   const stepDocs = deps.renderDocs(step.docs, "step-docs");
   const textHtml = deps.highlightStepParams ? deps.highlightStepParams(step.text) : deps.escapeHtml(step.text);
-  return `<div class="${stepClass}">
+  return `<div class="${stepClass}" data-keyword="${deps.escapeHtml(keywordTrimmed)}" data-text="${deps.escapeHtml(step.text)}">
   <span class="step-status ${statusClass}">${statusIcon}</span>
   <span class="step-keyword">${deps.escapeHtml(step.keyword)}</span>
   <span class="step-text">${textHtml}</span>
@@ -13176,7 +13824,11 @@ function renderScenario(args, deps) {
       </div>
       <div class="scenario-meta">${tags}${tickets}${sourceLink}${traceBadge}${metricBadges}</div>
     </div>
-    <span class="scenario-duration">${duration}</span>
+    <div class="scenario-actions">
+      <button class="copy-scenario-btn" onclick="copyScenarioAsMarkdown('scenario-${tc.id}')" aria-label="Copy scenario as markdown" title="Copy as Markdown">&#x2398;</button>
+      <button class="permalink-anchor" onclick="copyPermalink('scenario-${tc.id}')" aria-label="Copy link to scenario" title="Copy link">#</button>
+      <span class="scenario-duration">${duration}</span>
+    </div>
   </div>
   <div class="scenario-content">
     ${storyDocs}
@@ -13386,6 +14038,7 @@ function renderFeature(args, deps) {
   const featureName = suitePaths.length > 0 && suitePaths[0].length > 0 ? suitePaths[0][0] : file.split("/").pop()?.replace(/\.[^.]+$/, "") ?? file;
   const collapsedClass = deps.startCollapsed ? " collapsed" : "";
   const ariaExpanded = !deps.startCollapsed;
+  const featureSlug = `feature-${slugify(file)}`;
   const scenarios = testCases.map(
     (tc) => deps.renderScenario(
       { tc, metrics: args.metricsMap?.get(tc.id) },
@@ -13393,8 +14046,9 @@ function renderFeature(args, deps) {
     )
   ).join("\n");
   return `
-<div class="feature${collapsedClass}">
+<div class="feature${collapsedClass}" id="${featureSlug}">
   <div class="feature-header" role="button" tabindex="0" aria-expanded="${ariaExpanded}">
+    <button class="permalink-anchor" onclick="copyPermalink('${featureSlug}')" aria-label="Copy link to feature" title="Copy link">#</button>
     <div class="feature-info">
       <div class="feature-title">${deps.escapeHtml(featureName)}</div>
       <div class="feature-path">${deps.escapeHtml(file)}</div>
@@ -13507,6 +14161,57 @@ function renderFailureSummary(args, deps) {
 </div>`;
 }
 
+// src/formatters/html/renderers/toc.ts
+function groupBy4(items, keyFn) {
+  const map = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = keyFn(item);
+    const existing = map.get(key);
+    if (existing) {
+      existing.push(item);
+    } else {
+      map.set(key, [item]);
+    }
+  }
+  return map;
+}
+function renderToc(args, deps) {
+  const { run } = args;
+  if (run.testCases.length === 0) return "";
+  const byFile = groupBy4(run.testCases, (tc) => tc.sourceFile);
+  const features = [];
+  for (const [file, testCases] of byFile) {
+    const suitePaths = testCases.map((tc) => tc.titlePath).filter((p) => p.length > 0);
+    const featureName = suitePaths.length > 0 && suitePaths[0].length > 0 ? suitePaths[0][0] : file.split("/").pop()?.replace(/\.[^.]+$/, "") ?? file;
+    const featureSlug = `feature-${slugify(file)}`;
+    const scenarios = testCases.map((tc) => {
+      const statusIcon = deps.getStatusIcon(tc.status);
+      const statusClass = `status-${tc.status}`;
+      const failedClass = tc.status === "failed" ? " toc-failed" : "";
+      return `<a class="toc-scenario${failedClass}" href="#scenario-${tc.id}">
+          <span class="toc-status ${statusClass}">${statusIcon}</span>
+          ${deps.escapeHtml(tc.story.scenario)}
+        </a>`;
+    }).join("\n");
+    features.push(`<div class="toc-feature">
+      <button class="toc-feature-toggle" aria-expanded="true" onclick="this.setAttribute('aria-expanded', this.getAttribute('aria-expanded') === 'true' ? 'false' : 'true'); this.nextElementSibling.style.display = this.getAttribute('aria-expanded') === 'true' ? '' : 'none'" data-feature="#${featureSlug}">
+        ${deps.escapeHtml(featureName)}
+      </button>
+      <div class="toc-scenarios">
+        ${scenarios}
+      </div>
+    </div>`);
+  }
+  return `<nav class="toc-sidebar" aria-label="Table of contents">
+  <div class="toc-header">
+    <span class="toc-title">Contents</span>
+  </div>
+  <div class="toc-body">
+    ${features.join("\n")}
+  </div>
+</nav>`;
+}
+
 // src/formatters/html/renderers/index.ts
 function normalizeOptions(options = {}) {
   return {
@@ -13520,7 +14225,9 @@ function normalizeOptions(options = {}) {
     markdownEnabled: options.markdownEnabled ?? true,
     permalinkBaseUrl: options.permalinkBaseUrl,
     ticketUrlTemplate: options.ticketUrlTemplate,
-    theme: options.theme ?? "default"
+    tocEnabled: options.tocEnabled ?? true,
+    theme: options.theme ?? "default",
+    themePickerEnabled: options.themePickerEnabled ?? false
   };
 }
 function createHtmlFormatter(options = {}) {
@@ -13562,6 +14269,10 @@ function createHtmlFormatter(options = {}) {
     scenarioDeps
   };
   const tagBarDeps = { escapeHtml };
+  const tocDeps = {
+    escapeHtml,
+    getStatusIcon
+  };
   const bodyDeps = {
     renderMetaInfo,
     renderSummary,
@@ -13580,6 +14291,16 @@ function createHtmlFormatter(options = {}) {
       const bodyFn = theme.buildBody ?? buildBody;
       const body = bodyFn({ run }, bodyDeps);
       const templateFn = theme.generateTemplate ?? generateHtmlTemplate;
+      const isStructuralTheme = !!(theme.buildBody || theme.generateTemplate);
+      const tocHtml = opts.tocEnabled && !isStructuralTheme ? renderToc({ run }, tocDeps) : void 0;
+      let themePickerHtml;
+      let additionalThemeCss;
+      if (opts.themePickerEnabled) {
+        const cssOnlyThemes = getCssOnlyThemes();
+        const pickerOptions = cssOnlyThemes.map((t) => `<option value="${t.name}"${t.name === theme.name ? " selected" : ""}>${t.label}</option>`).join("");
+        themePickerHtml = `<select class="theme-picker" aria-label="Select theme">${pickerOptions}</select>`;
+        additionalThemeCss = cssOnlyThemes.filter((t) => t.name !== theme.name).map((t) => ({ name: t.name, label: t.label, css: t.css }));
+      }
       return templateFn(
         opts.title,
         theme.css,
@@ -13591,7 +14312,11 @@ function createHtmlFormatter(options = {}) {
           mermaidEnabled: opts.mermaidEnabled,
           markdownEnabled: opts.markdownEnabled,
           additionalJs: theme.additionalJs,
-          additionalImports: theme.additionalImports
+          additionalImports: theme.additionalImports,
+          tocHtml,
+          themePickerHtml,
+          additionalThemeCss,
+          activeThemeName: theme.name
         }
       );
     }
@@ -13647,7 +14372,7 @@ var JUnitFormatter = class {
     lines.push(
       `<testsuites name="${escapeXml(this.options.suiteName)}" tests="${tests}" failures="${failures}" errors="${errors}" skipped="${skipped}" time="${time}">`
     );
-    const byFile = groupBy4(run.testCases, (tc) => tc.sourceFile);
+    const byFile = groupBy5(run.testCases, (tc) => tc.sourceFile);
     for (const [file, testCases] of byFile) {
       lines.push(...this.buildTestSuite(file, testCases, indent, newline));
     }
@@ -13820,7 +14545,7 @@ var JUnitFormatter = class {
 function escapeXml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
-function groupBy4(items, keyFn) {
+function groupBy5(items, keyFn) {
   const map = /* @__PURE__ */ new Map();
   for (const item of items) {
     const key = keyFn(item);
@@ -13995,7 +14720,7 @@ var MarkdownFormatter = class {
    * Render scenarios grouped by file.
    */
   renderByFile(lines, testCases) {
-    const byFile = groupBy5(testCases, (tc) => tc.sourceFile);
+    const byFile = groupBy6(testCases, (tc) => tc.sourceFile);
     for (const [file, fileTestCases] of byFile) {
       lines.push(`## ${file}`);
       lines.push("");
@@ -14012,7 +14737,7 @@ var MarkdownFormatter = class {
    * Render suite groups.
    */
   renderSuiteGroups(lines, testCases, baseLevel) {
-    const bySuite = groupBy5(
+    const bySuite = groupBy6(
       testCases,
       (tc) => tc.titlePath.join(this.options.suiteSeparator)
     );
@@ -14306,7 +15031,7 @@ var MarkdownFormatter = class {
     return entries;
   }
 };
-function groupBy5(items, keyFn) {
+function groupBy6(items, keyFn) {
   const map = /* @__PURE__ */ new Map();
   for (const item of items) {
     const key = keyFn(item);
@@ -17259,7 +17984,9 @@ var ReportGenerator = class {
         markdownEnabled: options.html?.markdownEnabled ?? true,
         permalinkBaseUrl: options.html?.permalinkBaseUrl,
         ticketUrlTemplate: options.html?.ticketUrlTemplate,
-        theme: options.html?.theme ?? "default"
+        theme: options.html?.theme ?? "default",
+        tocEnabled: options.html?.tocEnabled ?? true,
+        themePickerEnabled: options.html?.themePickerEnabled ?? false
       },
       junit: {
         suiteName: options.junit?.suiteName ?? "Test Suite",
@@ -17382,7 +18109,9 @@ var ReportGenerator = class {
           mermaidEnabled: this.options.html.mermaidEnabled,
           markdownEnabled: this.options.html.markdownEnabled,
           permalinkBaseUrl: this.options.html.permalinkBaseUrl,
-          ticketUrlTemplate: this.options.html.ticketUrlTemplate
+          ticketUrlTemplate: this.options.html.ticketUrlTemplate,
+          tocEnabled: this.options.html.tocEnabled,
+          themePickerEnabled: this.options.html.themePickerEnabled
         });
         return formatter.format(run);
       }
@@ -17503,6 +18232,8 @@ OPTIONS
   --html-no-mermaid             Disable mermaid diagrams in HTML (enabled by default)
   --html-no-markdown            Disable markdown parsing in HTML (enabled by default)
   --html-permalink-base-url <url> Base URL for source permalinks in HTML (e.g. "https://github.com/org/repo/blob/main")
+  --html-no-toc                 Disable table of contents sidebar in HTML (enabled by default)
+  --html-theme-picker           Include theme picker in HTML report (embeds all CSS-only themes)
   --html-ticket-url-template <url> URL template for ticket links in HTML (use {ticket} as placeholder)
   --asset-mode <mode>         Asset bundling: "none" (default) or "copy"
   --allow-missing-assets      Warn on missing assets instead of failing
@@ -17586,6 +18317,8 @@ function parseCliArgs(argv) {
       "html-no-markdown": { type: "boolean", default: false },
       "html-permalink-base-url": { type: "string" },
       "html-ticket-url-template": { type: "string" },
+      "html-no-toc": { type: "boolean", default: false },
+      "html-theme-picker": { type: "boolean", default: false },
       stdin: { type: "boolean", default: false },
       "json-summary": { type: "boolean", default: false },
       "emit-canonical": { type: "string" },
@@ -17745,6 +18478,8 @@ function parseCliArgs(argv) {
     htmlNoMarkdown: values["html-no-markdown"],
     htmlPermalinkBaseUrl: values["html-permalink-base-url"],
     htmlTicketUrlTemplate: values["html-ticket-url-template"],
+    htmlNoToc: values["html-no-toc"],
+    htmlThemePicker: values["html-theme-picker"],
     jsonSummary: values["json-summary"],
     emitCanonical: values["emit-canonical"],
     slackWebhook,
@@ -18247,7 +18982,9 @@ async function generateReports(run, args, _droppedMissingStory = 0) {
       mermaidEnabled: !args.htmlNoMermaid,
       markdownEnabled: !args.htmlNoMarkdown,
       permalinkBaseUrl: args.htmlPermalinkBaseUrl,
-      ticketUrlTemplate: args.htmlTicketUrlTemplate
+      ticketUrlTemplate: args.htmlTicketUrlTemplate,
+      tocEnabled: !args.htmlNoToc,
+      themePickerEnabled: args.htmlThemePicker
     },
     assetMode: args.assetMode,
     allowMissingAssets: args.allowMissingAssets