feat: add Table of Contents to published article

Adapted from the research-article-template TOC system:
- Desktop (>1100px): sticky sidebar on the left in a 3-column grid
- Mobile (<1100px): hamburger button + sliding panel from the left
- Active section tracking on scroll (h2/h3/h4)
- Auto-generated IDs on headings (slugified, deduplicated)
- Theme toggle now persists to localStorage
- Print styles hide TOC and UI elements

Made-with: Cursor

backend/src/publisher/html-renderer.ts

@@ -88,10 +88,16 @@ body {
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
 }
 
-.article-container {
-  max-width: 780px;
+/* Grid: TOC | Article | (empty) */
+.content-grid {
+  max-width: 1280px;
   margin: 0 auto;
-  padding: 2rem 32px 4rem;
+  padding: 0 24px;
+  margin-top: 40px;
+  display: grid;
+  grid-template-columns: 240px minmax(0, 720px) 1fr;
+  gap: 32px;
+  align-items: start;
 }
 
 .article-header {
@@ -131,13 +137,8 @@ body {
   margin-left: 0.25rem;
 }
 
-.article-header .author-affiliation::before {
-  content: "(";
-}
-
-.article-header .author-affiliation::after {
-  content: ")";
-}
+.article-header .author-affiliation::before { content: "("; }
+.article-header .author-affiliation::after  { content: ")"; }
 
 .article-header .date {
   color: var(--text-tertiary);
@@ -159,6 +160,118 @@ body {
   z-index: 100;
 }
 
+/* ---------- Table of Contents ---------- */
+.toc {
+  position: sticky;
+  top: 32px;
+  max-height: calc(100vh - 64px);
+  overflow-y: auto;
+}
+
+.toc .toc-title {
+  font-weight: 600;
+  font-size: 14px;
+  margin-bottom: 8px;
+  color: var(--text-primary);
+}
+
+.toc nav { border-left: 1px solid var(--border); padding-left: 16px; font-size: 13px; }
+.toc nav ul { margin: 0 0 4px; padding-left: 1em; }
+.toc nav li { list-style: none; margin: 0.25em 0; }
+.toc nav a { color: var(--text-secondary); text-decoration: none; transition: color 0.15s; }
+.toc nav > ul > li > a { font-weight: 600; color: var(--text-primary); }
+.toc nav a:hover { color: var(--accent-light); }
+.toc nav a.active { color: var(--accent-light); text-decoration: underline; text-underline-offset: 2px; }
+
+/* Mobile TOC toggle */
+.toc-mobile-toggle {
+  display: none;
+  position: fixed;
+  top: 1rem;
+  left: 1rem;
+  z-index: 200;
+  width: 40px;
+  height: 40px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  background: var(--bg-primary);
+  color: var(--text-primary);
+  cursor: pointer;
+  align-items: center;
+  justify-content: center;
+  box-shadow: var(--shadow-sm);
+}
+
+/* Mobile backdrop */
+.toc-mobile-backdrop {
+  display: none;
+  position: fixed;
+  inset: 0;
+  z-index: 201;
+  background: rgba(0,0,0,.4);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 250ms ease;
+}
+.toc-mobile-backdrop.open { opacity: 1; pointer-events: auto; }
+
+/* Mobile sidebar */
+.toc-mobile-sidebar {
+  display: none;
+  position: fixed;
+  top: 0; left: 0; bottom: 0;
+  z-index: 202;
+  width: min(320px, 85vw);
+  background: var(--bg-primary);
+  border-right: 1px solid var(--border);
+  transform: translateX(-100%);
+  transition: transform 300ms cubic-bezier(.4,0,.2,1);
+  flex-direction: column;
+}
+.toc-mobile-sidebar.open { transform: translateX(0); }
+
+.toc-mobile-sidebar__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+.toc-mobile-sidebar__title { font-weight: 700; font-size: 15px; }
+.toc-mobile-sidebar__close {
+  background: none; border: none; color: var(--text-tertiary);
+  cursor: pointer; padding: 6px; border-radius: 6px;
+  display: flex; align-items: center; justify-content: center;
+}
+.toc-mobile-sidebar__close:hover { color: var(--text-primary); background: var(--bg-secondary); }
+
+.toc-mobile-sidebar__body {
+  flex: 1;
+  overflow-y: auto;
+  -webkit-overflow-scrolling: touch;
+  padding: 0.75rem 1rem 2rem;
+}
+.toc-mobile-sidebar__body nav ul { margin: 0 0 4px; padding-left: 1em; }
+.toc-mobile-sidebar__body nav li { list-style: none; margin: 0.35em 0; }
+.toc-mobile-sidebar__body nav a { color: var(--text-secondary); text-decoration: none; font-size: 14px; line-height: 1.5; }
+.toc-mobile-sidebar__body nav > ul > li > a { font-weight: 600; color: var(--text-primary); }
+.toc-mobile-sidebar__body nav a:hover { color: var(--accent-light); }
+.toc-mobile-sidebar__body nav a.active { color: var(--accent-light); text-decoration: underline; }
+
+/* Responsive: collapse grid below 1100px */
+@media (max-width: 1100px) {
+  .content-grid {
+    display: block;
+    padding: 0 16px;
+    margin-top: 1rem;
+  }
+  .toc { display: none; }
+  .toc-mobile-toggle { display: flex; }
+  .toc-mobile-backdrop { display: block; }
+  .toc-mobile-sidebar { display: flex; }
+}
+
 /* Accordion as details/summary */
 details[data-component="accordion"] {
   border: 1px solid var(--border);
@@ -176,60 +289,70 @@ details[data-component="accordion"] > summary {
   user-select: none;
 }
 
-details[data-component="accordion"] > summary::-webkit-details-marker {
-  display: none;
-}
+details[data-component="accordion"] > summary::-webkit-details-marker { display: none; }
 
 details[data-component="accordion"] > summary::before {
-  content: "▸";
+  content: "\\25B8";
   display: inline-block;
   margin-right: 0.5rem;
   transition: transform 0.2s;
 }
 
-details[data-component="accordion"][open] > summary::before {
-  transform: rotate(90deg);
-}
-
-details[data-component="accordion"] > .accordion-content {
-  padding: 0 1rem 1rem;
-}
+details[data-component="accordion"][open] > summary::before { transform: rotate(90deg); }
+details[data-component="accordion"] > .accordion-content { padding: 0 1rem 1rem; }
 
 /* Image lightbox dialog */
-dialog.lightbox {
-  border: none;
-  background: transparent;
-  padding: 0;
-  max-width: 95vw;
-  max-height: 95vh;
-}
-
-dialog.lightbox::backdrop {
-  background: rgba(0, 0, 0, 0.85);
-}
-
-dialog.lightbox img {
-  max-width: 95vw;
-  max-height: 90vh;
-  object-fit: contain;
-  border-radius: 4px;
+dialog.lightbox { border: none; background: transparent; padding: 0; max-width: 95vw; max-height: 95vh; }
+dialog.lightbox::backdrop { background: rgba(0, 0, 0, 0.85); }
+dialog.lightbox img { max-width: 95vw; max-height: 90vh; object-fit: contain; border-radius: 4px; }
+
+/* Print */
+@media print {
+  .toc, .toc-mobile-toggle, .toc-mobile-backdrop, .toc-mobile-sidebar, .theme-toggle { display: none !important; }
+  .content-grid { display: block !important; }
 }
   </style>
 </head>
 <body>
-  <button class="theme-toggle" aria-label="Toggle theme" onclick="toggleTheme()">🌓</button>
-
-  <article class="article-container">
-    <header class="article-header">
-      <h1>${safeTitle}</h1>
-      ${meta.authors.length > 0 ? `<div class="authors">${renderAuthors(meta.authors)}</div>` : ""}
-      ${meta.date ? `<p class="date">${escapeHtml(formatDate(meta.date))}</p>` : ""}
-    </header>
+  <button class="theme-toggle" aria-label="Toggle theme" onclick="toggleTheme()">&#127763;</button>
+
+  <!-- Mobile TOC toggle -->
+  <button class="toc-mobile-toggle" aria-label="Open table of contents" aria-expanded="false">
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/>
+    </svg>
+  </button>
+  <div class="toc-mobile-backdrop" aria-hidden="true"></div>
+  <aside class="toc-mobile-sidebar" aria-label="Table of Contents">
+    <div class="toc-mobile-sidebar__header">
+      <span class="toc-mobile-sidebar__title">Table of Contents</span>
+      <button class="toc-mobile-sidebar__close" aria-label="Close">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>
+        </svg>
+      </button>
+    </div>
+    <div class="toc-mobile-sidebar__body" id="toc-mobile-placeholder"></div>
+  </aside>
 
-    <div class="tiptap">
-      ${enrichedBody}
+  <section class="content-grid">
+    <div class="toc" aria-label="Table of Contents">
+      <div class="toc-title">Table of Contents</div>
+      <div id="toc-placeholder"></div>
     </div>
-  </article>
+
+    <article>
+      <header class="article-header">
+        <h1>${safeTitle}</h1>
+        ${meta.authors.length > 0 ? `<div class="authors">${renderAuthors(meta.authors)}</div>` : ""}
+        ${meta.date ? `<p class="date">${escapeHtml(formatDate(meta.date))}</p>` : ""}
+      </header>
+
+      <div class="tiptap">
+        ${enrichedBody}
+      </div>
+    </article>
+  </section>
 
   <!-- Image lightbox -->
   <dialog class="lightbox" id="lightbox">
@@ -237,30 +360,160 @@ dialog.lightbox img {
   </dialog>
 
   <script>
+  (function() {
     // Theme toggle
-    function toggleTheme() {
-      const html = document.documentElement;
-      const current = html.getAttribute('data-theme');
-      html.setAttribute('data-theme', current === 'dark' ? 'light' : 'dark');
-    }
+    window.toggleTheme = function() {
+      var html = document.documentElement;
+      var next = html.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
+      html.setAttribute('data-theme', next);
+      localStorage.setItem('theme', next);
+    };
+    var saved = localStorage.getItem('theme');
+    if (saved) document.documentElement.setAttribute('data-theme', saved);
 
     // Image lightbox
     document.querySelectorAll('.tiptap img').forEach(function(img) {
       img.style.cursor = 'zoom-in';
       img.addEventListener('click', function() {
-        var d = document.getElementById('lightbox');
         document.getElementById('lightbox-img').src = img.src;
-        d.showModal();
+        document.getElementById('lightbox').showModal();
       });
     });
     document.getElementById('lightbox').addEventListener('click', function(e) {
       if (e.target === this) this.close();
     });
 
-    // Glossary tooltips
+    // Glossary tabindex
     document.querySelectorAll('[data-type="glossary"]').forEach(function(el) {
       el.setAttribute('tabindex', '0');
     });
+
+    // ---- Table of Contents ----
+    var holder = document.getElementById('toc-placeholder');
+    var holderMobile = document.getElementById('toc-mobile-placeholder');
+    var articleRoot = document.querySelector('.content-grid article');
+    if (!articleRoot) return;
+
+    var headings = articleRoot.querySelectorAll('h2, h3, h4');
+    if (!headings.length) return;
+    var headingsArr = Array.from(headings);
+
+    // Ensure unique IDs
+    var usedIds = {};
+    var slugify = function(s) {
+      return String(s || '').toLowerCase().trim().replace(/\\s+/g, '_').replace(/[^a-z0-9_-]/g, '');
+    };
+    headingsArr.forEach(function(h) {
+      var id = (h.id || '').trim() || slugify(h.textContent) || 'section';
+      var candidate = id;
+      var n = 2;
+      while (usedIds[candidate]) { candidate = id + '-' + (n++); }
+      if (h.id !== candidate) h.id = candidate;
+      usedIds[candidate] = true;
+    });
+
+    // Build nested nav
+    var nav = document.createElement('nav');
+    var ulStack = [document.createElement('ul')];
+    nav.appendChild(ulStack[0]);
+    var levelOf = function(tag) { return tag === 'H2' ? 2 : tag === 'H3' ? 3 : 4; };
+    var prev = 2;
+    headingsArr.forEach(function(h) {
+      var lvl = levelOf(h.tagName);
+      while (lvl > prev) {
+        var ul = document.createElement('ul');
+        var last = ulStack[ulStack.length - 1].lastElementChild;
+        if (last) last.appendChild(ul);
+        ulStack.push(ul);
+        prev++;
+      }
+      while (lvl < prev) { ulStack.pop(); prev--; }
+      var li = document.createElement('li');
+      var a = document.createElement('a');
+      a.href = '#' + h.id;
+      a.textContent = h.textContent;
+      li.appendChild(a);
+      ulStack[ulStack.length - 1].appendChild(li);
+    });
+
+    if (holder) holder.appendChild(nav);
+    var navClone = nav.cloneNode(true);
+    if (holderMobile) holderMobile.appendChild(navClone);
+
+    // Active section tracking
+    var allLinks = [].concat(
+      holder ? Array.from(holder.querySelectorAll('a')) : [],
+      holderMobile ? Array.from(holderMobile.querySelectorAll('a')) : []
+    );
+    var OFFSET = 80;
+    var lastScrollTime = 0;
+
+    var onScroll = function() {
+      var now = performance.now();
+      if (now - lastScrollTime < 50) return;
+      lastScrollTime = now;
+      requestAnimationFrame(function() {
+        var activeId = null;
+        for (var i = headingsArr.length - 1; i >= 0; i--) {
+          if (headingsArr[i].getBoundingClientRect().top - OFFSET <= 0) {
+            activeId = headingsArr[i].id;
+            break;
+          }
+        }
+        allLinks.forEach(function(l) {
+          if (activeId && l.getAttribute('href') === '#' + activeId) {
+            l.classList.add('active');
+          } else {
+            l.classList.remove('active');
+          }
+        });
+      });
+    };
+    window.addEventListener('scroll', onScroll, { passive: true });
+    onScroll();
+
+    // Mobile sidebar
+    var sidebar = document.querySelector('.toc-mobile-sidebar');
+    var backdrop = document.querySelector('.toc-mobile-backdrop');
+    var toggleBtn = document.querySelector('.toc-mobile-toggle');
+    var closeBtn = document.querySelector('.toc-mobile-sidebar__close');
+
+    var openSidebar = function() {
+      sidebar.classList.add('open');
+      backdrop.classList.add('open');
+      toggleBtn.setAttribute('aria-expanded', 'true');
+      document.body.style.overflow = 'hidden';
+      requestAnimationFrame(function() {
+        var active = sidebar.querySelector('a.active');
+        if (active) {
+          var body = sidebar.querySelector('.toc-mobile-sidebar__body');
+          if (body) body.scrollTop = Math.max(0, active.offsetTop - body.offsetTop - body.clientHeight / 3);
+        }
+      });
+    };
+    var closeSidebar = function() {
+      sidebar.classList.remove('open');
+      backdrop.classList.remove('open');
+      toggleBtn.setAttribute('aria-expanded', 'false');
+      document.body.style.overflow = '';
+    };
+
+    if (toggleBtn) toggleBtn.addEventListener('click', openSidebar);
+    if (closeBtn) closeBtn.addEventListener('click', closeSidebar);
+    if (backdrop) backdrop.addEventListener('click', closeSidebar);
+    if (holderMobile) holderMobile.addEventListener('click', function(e) {
+      if (e.target.closest && e.target.closest('a')) closeSidebar();
+    });
+    document.addEventListener('keydown', function(e) {
+      if (e.key === 'Escape' && sidebar.classList.contains('open')) closeSidebar();
+    });
+
+    // Handle initial hash navigation
+    if (window.location.hash) {
+      var target = document.querySelector(window.location.hash);
+      if (target) setTimeout(function() { target.scrollIntoView({ block: 'start' }); }, 100);
+    }
+  })();
   </script>
 </body>
 </html>`;